Как настроить REST API на 1С-Битрикс: Управление сайтом?

Нужно отдать каталог сайта мобильному приложению или внешнему сервису, а в админке нет кнопки "Создать вебхук"? На 1С-Битрикс: Управление сайтом REST включается вручную: модуль rest, страница /local/rest/, два правила в urlrewrite и галочка у инфоблока. После настройки вы получите рабочий URL вида /rest/1/ключ/iblock.Element.get и JSON с элементами - без путаницы с облачным CRM, который часто встречается в поиске по запросу "битрикс rest api".

REST на коробочной CMS - это способ дать внешней программе читать данные сайта по HTTPS без входа в админку. На БУС нет встроенного раздела для вебхуков: вы сами создаете страницу с компонентом bitrix:rest.hook, прописываете urlrewrite и включаете доступ у инфоблока. Тестовый вызов iblock.Element.get с iblockId и elementId должен вернуть JSON, а не METHOD_NOT_FOUND.

На практике типичная ошибка — открыть apidocs.bitrix24.ru и потратить час на методы crm.*, которые на вашем сайте не работают: главная проблема запроса «битрикс rest api» — путаница с облачным CRM. В реальном проекте с Flutter-каталогом разработчик видит ERROR_METHOD_NOT_FOUND, пока не добавит два правила urlrewrite и не включит «Включен доступ через REST» у инфоблока.

REST API (программный интерфейс по HTTP) на сайте нужен, когда данные должны уходить во внешний мир: мобильное приложение, виджет на другом домене, скрипт обмена. На коробочном "Управление сайтом" это не тот же продукт, что портальный REST облачного CRM: методы crm.* там не заработают на вашем каталоге.

Ниже - один связный сценарий от проверки модуля до тестового запроса к инфоблоку. Если инфоблока еще нет, сначала создайте его по инструкции по инфоблокам; для обмена с 1С смотрите обзор интеграции с 1С - REST там один из вариантов, не единственный.

Определите, когда нужен REST на CMS

Берите модульный REST, если внешней системе нужен стабильный URL и JSON без разработки своего контроллера с нуля. Типичные задачи: каталог для Flutter-приложения, выгрузка новостей на лендинг, точечная синхронизация остатков.

Делайте: уточняйте в ТЗ продукт - "1С-Битрикс: Управление сайтом" на вашем домене, а не облачный портал. Не делайте: не копируйте примеры с apidocs.bitrix24.ru - они про CRM и не откроют ваш инфоблок.

Проверьте модуль rest и подготовьте окружение

Модуль REST API для "Управление сайтом" доступен с версии продукта 16.6.0. Проверьте: Настройки - Настройки продукта - Модули - найдите "rest" и убедитесь, что он установлен.

1. Убедитесь, что сайт открывается по HTTPS - без SSL вебхуки и apauth работать не будут.
2. Создайте отдельного пользователя с минимальными правами (только то, что нужно API), не администратора.
3. Проверьте версию модуля iblock: REST для инфоблоков появился с iblock 20.5.0; штатные методы read-only.
4. Очистите кеш после правок urlrewrite - иначе правила не подхватятся.
5. Для отладки включите вывод ошибок в settings.php на тестовом стенде, не на боевом.

Делайте: ведите чек-лист "модуль - SSL - пользователь - кеш". Не делайте: не выдавайте вебхук от учетной записи с полным доступом к админке.

Создайте страницу вебхуков в /local/rest/

На БУС нет раздела "Разработчикам" как в облаке. Интерфейс входящего вебхука собирают вручную - страницей с компонентом bitrix:rest.hook.

Создайте файл /local/rest/index.php:

<?php
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");
$APPLICATION->SetTitle("REST API");
$APPLICATION->IncludeComponent(
    "bitrix:rest.hook",
    "",
    [
        "SEF_MODE" => "Y",
        "SEF_FOLDER" => "/local/rest/",
        "SEF_URL_TEMPLATES" => [
            "list" => "",
            "event" => "event/",
        ],
    ]
);
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");

После сохранения откройте https://ваш-сайт.ru/local/rest/ под пользователем с правом на REST. Там создаете входящий вебхук и выбираете scope (права), например iblock.

Делайте: храните страницу в /local/, чтобы обновления ядра ее не затерли. Не делайте: не публикуйте ссылку на /local/rest/ в открытом доступе без авторизации в админке.

Настройте urlrewrite: два обязательных правила

Без двух правил вызовы /rest/... часто дают 404 или METHOD_NOT_FOUND. Схема прохождения запроса:

Цепочка вызова:
Клиент (curl, Postman, приложение) → HTTPS /rest/{user}/{code}/{method} → urlrewrite #^/rest/# → /bitrix/services/rest/index.php → модуль rest → метод iblock.Element.get → JSON-ответ

Добавьте в /urlrewrite.php (или через интерфейс "Управление адресами") два правила:

// Правило 1: страница управления вебхуками
[
    "CONDITION" => "#^/local/rest/#",
    "RULE" => "",
    "ID" => "bitrix:rest.hook",
    "PATH" => "/local/rest/index.php",
],
// Правило 2: обработчик API-вызовов
[
    "CONDITION" => "#^/rest/#",
    "RULE" => "",
    "ID" => "",
    "PATH" => "/bitrix/services/rest/index.php",
],

Делайте: проверяйте оба URL - и /local/rest/, и тестовый /rest/1/xxx/profile. Не делайте: не ограничивайтесь одним правилом "на все REST" - UI и API разведены.

Выпустите входящий вебхук и проверьте формат URL

На странице /local/rest/ создайте входящий вебхук. Формат вызова:

https://ваш-сайт.ru/rest/{ID_пользователя}/{секретный_код}/{имя_метода}

Пример теста (замените домен, user, code):

curl "https://ваш-сайт.ru/rest/1/xxxxxxxxxx/profile"

Успешный ответ - JSON с данными профиля. Для инфоблока понадобится scope iblock и методы iblock.Element.get или iblock.Element.list.

Делайте: храните код вебхука в секретах, не в git. Не делайте: не светите полный URL с ключом в логах nginx и в тикетах поддержки.

Откройте инфоблок для REST и сделайте тестовый запрос

Штатный REST инфоблоков с версии iblock 20.5.0 - только чтение: iblock.Element.get и iblock.Element.list. Запись через iblock.Element.add из коробки недоступна; для нее нужен обработчик OnRestServiceBuildDescription - см. статью про обработчики событий.

В настройках нужного инфоблока (Контент - Инфоблоки - тип - инфоблок):

• Заполните поле "Символьный код API" (API_CODE) латиницей, например catalog.
• Включите галочку "Включен доступ через REST".
• Запомните числовой ID инфоблока и ID тестового элемента.

Пример GET к одному элементу:

curl "https://ваш-сайт.ru/rest/1/xxxxxxxxxx/iblock.Element.get?iblockId=5&elementId=42"

Для списка используйте iblock.Element.list с filter и select. Если в ответе не хватает полей вроде DETAIL_TEXT, расширяйте контроллер по документации на dev.1c-bitrix.ru - базовый get отдает не все свойства.

Делайте: сначала добейтесь рабочего get на одном элементе. Не делайте: не ожидайте запись в каталог через REST без доработки - это частая ловушка после опыта с облачными списками.

Выберите: модульный REST или собственные маршруты D7

Итоговый вердикт: для чтения каталога и быстрого MVP берите модульный REST. Если ТЗ требует свой JSON и JWT вместо вебхука - проектируйте /api/v1 на D7, не ломая стандартный /rest/.

Проверьте безопасность и отладьте типичные ошибки

Частые симптомы и что проверить:

• METHOD_NOT_FOUND - опечатка в имени метода, нет правила #^/rest/#, вебхук без scope iblock.
• 404 на /rest/ - не добавлено правило urlrewrite или не сброшен кеш.
• Пустой ответ или access denied - не включен REST у инфоблока, пустой API_CODE, вебхук создан другим пользователем.
• Ошибка SSL - сайт открыт по http, а клиент требует https.

Ротация ключа: на /local/rest/ удалите старый вебхук, создайте новый, обновите URL у всех клиентов. Права пользователя для API настраивайте по принципу минимума - см. также работу с пользователями в cuser-getlist.

Нужна помощь с настройкой REST под мобильное приложение или обмен - обсудим задачу. Примеры интеграций смотрите в портфолио.

Автор: Максим Мольков, Senior-разработчик 1С-Битрикс.
Источники: документация REST 1С-Битрикс, REST API для инфоблоков, практика внедрений на CMS "Управление сайтом".

Частые вопросы