REST API в «1С-Битрикс: Управление сайтом» для доступа к данным инфоблоков (активация и расширение)

Часто при разработке мобильных приложений (Flutter, iOS, Android) или современных веб-интерфейсов (React, Vue, Angular) для сайтов на «1С-Битрикс: Управление сайтом» (БУС) возникает необходимость получать и отправлять данные через REST API. В отличие от Битрикс24, в БУС нет встроенного интерфейса для быстрой генерации ключей доступа к REST API.

В этой статье мы подробно разберем, как не только активировать REST API в БУС с помощью вебхуков, но и расширить его возможности для получения нестандартных полей элементов инфоблока, таких как «Детальное описание».

Все проделанные шаги на момент публикации статьи были произведены на 1С-Битрикс: Управление сайтом версии 25.100.300 редакции Старт.

Предварительные шаги

Проверка модуля REST API:

• Перейдите в административную панель: Настройки > Настройки продукта > Модули.
• Убедитесь, что модуль REST API (rest) установлен. Если нет, установите его.

Шаг 1: Создание интерфейса для управления вебхуками

Поскольку в БУС нет штатного раздела для генерации вебхуков, создадим свою административную страницу для этой цели. Чтобы избежать конфликтов с URL-адресами самого API, разместим эту страницу в каталоге /local/rest/.

1. Создайте файл: /local/rest/index.php
2. Добавьте в него следующий код:

<?php
// Подключаем пролог административной части Битрикса
require_once($_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_admin.php');

// Проверяем, что модуль REST установлен и активен
if (!\Bitrix\Main\Loader::includeModule('rest')) {
    ShowError('Модуль REST не установлен');
    require($_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/epilog_admin.php');
    exit;
}

// Оборачиваем в div для стилизации в админке
echo '<div class="adm-workarea">';

// Выводим компонент REST API (отображает список вебхуков и обрабатывает страницы их создания/редактирования)
$APPLICATION->IncludeComponent(
    'bitrix:rest.hook',
    '.default',
    [
        'SEF_MODE' => 'Y',
        'SEF_FOLDER' => '/local/rest/', // Путь к нашей папке
        'COMPONENT_TEMPLATE' => '.default',
        'SEF_URL_TEMPLATES' => [ // Шаблоны ЧПУ для компонента
            'list' => '',
            'event_list' => 'event/',
            'event_edit' => 'event/#id#/',
            'ap_list' => 'ap/',
            'ap_edit' => 'ap/#id#/',
        ],
    ],
    false
);

// --- Код кнопки для добавления нового вебхука ---
?>
<br> <? // Небольшой отступ ?>
<a href="javascript:;" class="adm-btn adm-btn-green"
    onclick="BX.PopupMenu.show('rest_hook_menu', this, [{
        'href':'/local/rest/event/0/',  // Ссылка на создание исходящего вебхука
        'text':'Исходящий вебхук'
    },{
        'href':'/local/rest/ap/0/',      // Ссылка на создание входящего вебхука
        'text':'Входящий вебхук'
    }])">
    Добавить вебхук
</a>
<?php
// --- Конец кода кнопки ---

echo '</div>'; // Закрываем div adm-workarea

// Подключаем эпилог
require($_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/epilog_admin.php');
?>

Шаг 2: Настройка правил перезаписи URL (urlrewrite.php)

Это критически важный шаг для того, чтобы и страница управления вебхуками, и сами вызовы API работали корректно и не конфликтовали. Необходимо иметь два отдельных правила:

1. Правило для страницы управления вебхуками (/local/rest/), указывающее на компонент.
2. Правило для API-вызовов (/rest/), указывающее на стандартный обработчик Битрикса.

Откройте файл /urlrewrite.php в корне сайта и убедитесь, что он содержит следующие два правила (или добавьте их, правило для /local/rest/ должно идти ПЕРЕД правилом для /rest/):

<?php
  // Правило для страницы управления вебхуками (с компонентом)
  array (
    'CONDITION' => '#^/local/rest/#', // Условие для нашего раздела управления
    'RULE' => '',
    'ID' => 'bitrix:rest.hook', // ID Компонента - ОБЯЗАТЕЛЬНО!
    'PATH' => '/local/rest/index.php', // Путь к файлу с компонентом
    'SORT' => 100,
  ),
  // Правило для стандартной обработки вызовов REST API
  array (
    'CONDITION' => '#^/rest/#', // Условие для вызовов API
    'RULE' => '',
    'ID' => '', // ID может быть пустым
    'PATH' => '/bitrix/services/rest/index.php', // Путь к стандартному обработчику
    'SORT' => 200,
  ),
  // ... могут быть другие ваши правила ...
?>

Не забывайте очищать кеш Битрикса после внесения изменений в файлы PHP и urlrewrite.php.

Шаг 3: Генерация вебхука

Теперь, когда у нас есть страница управления, можно сгенерировать сам вебхук.

1. Перейдите по адресу https://localhost/local/rest/ (замените localhost на домен вашего сайта). Вы должны увидеть интерфейс для работы с вебхуками.
2. Нажмите зеленую кнопку «Добавить вебхук» и выберите «Входящий вебхук».
3. Откроется страница настройки. Задайте имя вебхуку (например, «Доступ для мобильного приложения»).
4. Очень важно: В разделе «Настройка прав доступа» найдите и отметьте галочкой «Информационные блоки (iblock)». Также отметьте другие права, которые могут понадобиться вашему приложению (например, user для данных пользователей, sale для заказов и т.д.).
5. Нажмите «Сохранить».
6. Система сгенерирует URL для вызова REST API. Он будет выглядеть примерно так:
   https://localhost/rest/ID_пользователя/уникальный_код/profile/
   !но в действительности будет работать по адресу:
   https://localhost/rest/ID_пользователя/уникальный_код/
   Пример: https://localhost/rest/2/26z314dyiq0m84z5/
7. Обязательно сохраните этот URL и особенно уникальный код (26z314dyiq0m84z5 в примере) – это ваш секретный ключ доступа.
8. Важно: Для работы вебхуков ваш сайт должен быть доступен по протоколу HTTPS.

Шаг 4: Настройка инфоблока и базовый вызов API

Чтобы получить доступ к данным конкретного инфоблока через REST API:

1. Перейдите в настройки нужного инфоблока: Контент -> Инфоблоки -> Типы инфоблоков -> (ваш тип) -> (ваш инфоблок).
2. Перейдите на вкладку «Инфоблок».
3. Установите галочку «Включен доступ через REST».
4. Задайте Символьный код API (API_CODE) инфоблоку.
5. Сохраните настройки.

Теперь можно попробовать получить данные элемента. Используем метод iblock.Element.get.

Пример GET-запроса:

Предположим, ваш URL вебхука: https://localhost/rest/2/26z314dyiq0m84z5/
ID инфоблока: 1
ID элемента: 34

Запрос:
GET https://localhost/rest/2/26z314dyiq0m84z5/iblock.Element.get?iblockId=1&elementId=34

Ограничения стандартного iblock.Element.get:

По умолчанию этот метод возвращает очень ограниченный набор полей элемента:

• ID
• NAME (Название)
• IBLOCK_SECTION_ID (ID раздела)

Вы не получите стандартными средствами такие поля, как DETAIL_TEXT, PREVIEW_TEXT, DETAIL_PICTURE, CODE и другие, даже если укажете их в параметре select. (Документация 1С-Битрикс по методу: iblock.Element.get)

В документации также еще описан iblock.Element.list.

Шаг 5: Расширение API с помощью своего контроллера

Чтобы обойти ограничения стандартного метода и получить доступ к полям вроде DETAIL_TEXT, необходимо создать собственный REST-контроллер для вашего инфоблока. Подробная документация об этом механизме доступна на сайте 1С-Битрикс: Своя реализация контроллера.

Мы реализуем контроллер, который наследует стандартный, но переопределяет список разрешенных полей.

1. Запишите Символьный код API (API_CODE) инфоблока:

• В настройках вашего инфоблока (например, ID=1) на вкладке «Инфоблок» найдите поле «Символьный код API» (API_CODE). Запомните его.

2. Создайте файл контроллера: /local/php_interface/lib/Rest/MyElementController.php

Разместите в нем следующий код:

<?php
namespace Local\Rest;

// use Bitrix\Main\Diag\Debug; // Пространство имен для логирования (закомментировано)

// Убедитесь, что базовый класс доступен (проверка добавлена на случай проблем с загрузкой модуля)
if (!class_exists('\Bitrix\Iblock\Controller\DefaultElement')) {
    // Debug::writeToFile('Base DefaultElement class not found!', '', '__controller_error.log'); // Лог для отладки
    return;
}

class MyElementController extends \Bitrix\Iblock\Controller\DefaultElement
{
    /**
     * Конструктор. Обязательно вызываем родительский.
     */
    public function __construct()
    {
        parent::__construct();
        // Debug::writeToFile('MyElementController (full) instantiated!', '', '__controller_exec.log'); // Лог для отладки
    }

    /**
     * Переопределяем список разрешенных полей, добавляя нужные нам.
     * Метод должен быть ПУБЛИЧНЫМ и СТАТИЧЕСКИМ (public static), как в родительском классе.
     * @return array
     */
    public static function getAllowedList()
    {
        // Debug::writeToFile('MyElementController: static getAllowedList() called.', '', '__controller_exec.log'); // Лог для отладки

        // Вызов родительского статического метода для получения базового списка
        $allowed = parent::getAllowedList();
        // Debug::writeToFile(['Parent allowed list' => $allowed], '', '__controller_exec.log'); // Лог для отладки

        // Добавляем наши поля в список разрешенных
        $allowed[] = 'DETAIL_TEXT';
        $allowed[] = 'PREVIEW_TEXT';
        $allowed[] = 'DETAIL_PICTURE';
        $allowed[] = 'PREVIEW_PICTURE';
        // $allowed[] = 'CODE'; // Можно раскомментировать, если нужен символьный код
        // Добавьте сюда другие нужные поля элемента...

        // Убираем дубликаты и возвращаем финальный список
        $finalAllowed = array_unique($allowed);
        // Debug::writeToFile(['Final allowed list' => $finalAllowed], '', '__controller_exec.log'); // Лог для отладки

        return $finalAllowed;
    }

    /**
     * Опционально: можно переопределить getAction, если нужна особая логика
     * Например, для дополнительной обработки данных перед возвратом.
     */
    /*
    public function getAction($iblockId, $elementId)
    {
        // Debug::writeToFile('MyElementController: getAction() called.', '', '__controller_exec.log'); // Лог для отладки
        $result = parent::getAction($iblockId, $elementId);
        // ... ваша кастомная логика обработки $result ...
        return $result;
    }
    */
}
?>

3. Зарегистрируйте контроллер в системе:

• Откройте файл /local/php_interface/init.php (создайте, если его нет).
• Добавьте следующий код:

<?php
use Bitrix\Main\Loader;
use Bitrix\Main\DI\ServiceLocator;
use Bitrix\Main\EventManager;
// use Bitrix\Main\Diag\Debug; // Пространство имен для логирования (закомментировано)

// --- ШАГ 1: Гарантируем, что модуль iblock загружен ПЕРЕД регистрацией ---
// Это важно, т.к. наш контроллер наследуется от класса из этого модуля
if (!Loader::includeModule('iblock')) {
    // Debug::writeToFile('Failed to load iblock module in init.php!', '', '__init_error.log'); // Лог для отладки
    return; // Прекращаем выполнение, если модуль не загружен
} else {
    // Debug::writeToFile('Iblock module loaded successfully in init.php.', '', '__init_log.log'); // Лог для отладки
}

// --- ШАГ 2: Регистрируем автозагрузку для нашего контроллера ---
// Сообщаем Битриксу, где искать наш класс Local\Rest\MyElementController
Loader::registerAutoLoadClasses(null, [
    '\Local\Rest\MyElementController' => '/local/php_interface/lib/Rest/MyElementController.php',
]);

// --- ШАГ 3: Регистрируем контроллер в Service Locator через событие OnPageStart ---
// Регистрация через событие надежнее, т.к. ядро успевает инициализироваться
$eventManager = EventManager::getInstance();
$eventManager->addEventHandlerCompatible('main', 'OnPageStart', function() {
    try {
        // --- ВАЖНО: Замените 'my_iblock_1' на РЕАЛЬНЫЙ API_CODE вашего инфоблока ---
        $apiKey = 'my_iblock_1';
        // Формируем уникальный ключ для регистрации контроллера
        $key = 'iblock.element.' . $apiKey . '.rest.controller';

        // Debug::writeToFile('OnPageStart: Attempting registration for key: ' . $key, '', '__controller_reg.log'); // Лог для отладки

        // Проверяем, что наш класс действительно доступен после автозагрузки
        if (class_exists('\Local\Rest\MyElementController')) {
            $serviceLocator = ServiceLocator::getInstance();
            $instance = new \Local\Rest\MyElementController(); // Создаем экземпляр контроллера
            $serviceLocator->addInstance($key, $instance); // Регистрируем его по ключу
            // Debug::writeToFile('OnPageStart: Controller registered successfully for key: ' . $key, '', '__controller_reg.log'); // Лог для отладки
        } else {
            // Debug::writeToFile('OnPageStart: Class \Local\Rest\MyElementController not found!', '', '__controller_reg_error.log'); // Лог для отладки
             // Дополнительная проверка базового класса для диагностики
             // if (!class_exists('\Bitrix\Iblock\Controller\DefaultElement')) {
             //     Debug::writeToFile('OnPageStart: Base \Bitrix\Iblock\Controller\DefaultElement STILL not found!', '', '__controller_reg_error.log');
             // }
        }
    } catch (\Throwable $e) { // Ловим любые ошибки при регистрации
        // Debug::writeToFile('OnPageStart: Error during registration: ' . $e->getMessage(), '', '__controller_reg_exception.log'); // Лог для отладки
    }
});
?>

Не забудьте заменить ‘my_iblock_1’ на реальный API_CODE вашего инфоблока в этом файле!

Шаг 6: Вызов API с расширенным набором полей

После создания и регистрации контроллера вы можете использовать параметр select в запросе iblock.Element.get для получения полей, добавленных в getAllowedList.

Пример GET-запроса для получения ID, NAME и DETAIL_TEXT:
GET https://localhost/rest/2/26z314dyiq0m84z5/iblock.Element.get?iblockId=1&elementId=34&select[0]=ID&select[1]=NAME&select[2]=DETAIL_TEXT

Теперь в ответе API будет присутствовать поле DETAIL_TEXT.

Заключение

Активация REST API в «1С-Битрикс: Управление сайтом» требует немного больше усилий, чем в Битрикс24, особенно если нужен доступ к расширенному набору полей инфоблоков. Следуя этой инструкции, вы сможете не только настроить базовый доступ через вебхуки, но и создать собственный контроллер для получения всех необходимых данных, включая детальное описание, превью-текст и другие стандартные поля элементов инфоблока.