REST API 1С-Битрикс: руководство по настройке и интеграциям
Когда встаёт задача связать сайт на «1С-Битрикс: Управление сайтом» с CRM, учётной системой или мобильным приложением, первый вопрос — как сделать это надёжно, без правки ядра и риска потерять данные. Практичный ответ — REST API: набор HTTP-методов, которые отдают и принимают данные в формате JSON.
Разберём, чем такой подход отличается от Битрикс24, как активировать модуль, создать входящий вебхук, настроить доступ к инфоблокам и расширить API собственными D7-контроллерами.
REST API — набор HTTP-методов для чтения, создания и обновления данных без правки кода сайта; отвечает в формате JSON. Входящий вебхук — ссылка с ключом доступа, через которую внешнее приложение обращается к API. Инфоблок — хранилище контента (товары, новости, каталог), доступное через REST-методы. urlrewrite.php — файл правил обработки ЧПУ-адресов, куда добавляют маршруты. D7-контроллер — класс для расширения API собственными методами. OAuth 2.0 — протокол авторизации с access-токеном и разграничением доступов.
Коротко: REST API в БУС позволяет внешним системам — CRM, ERP, маркетплейсам и мобильным приложениям — обмениваться данными с сайтом через HTTP и JSON. В отличие от Битрикс24, здесь нет штатного интерфейса ключей: модуль активируется вручную, страница вебхуков создаётся в /local/rest/, а маршруты прописываются в urlrewrite.php.
Что нужно знать о REST API в 1С-Битрикс
REST API (Representational State Transfer) — архитектурный стиль взаимодействия систем через HTTP. Клиент отправляет запрос, сервер отвечает данными в JSON. В «1С-Битрикс: Управление сайтом» это набор методов, позволяющий внешнему приложению читать, создавать, обновлять и удалять данные — заказы, товары, лиды, инфоблоки — без прямого вмешательства в основной код сайта.
Простыми словами: вместо скриптов внутри CMS или прямого доступа к базе вы обращаетесь к API по понятному адресу и получаете ответ. Такой подход безопаснее для ядра, проще в поддержке и легко переносится между системами.
Главное отличие от Битрикс24: там REST API встроен из коробки — есть интерфейс генерации вебхуков, документация и готовый SDK. В БУС штатного интерфейса для ключей нет, поэтому ключ доступа создают вручную: страницу управления вебхуками размещают в каталоге /local/rest/ и настраивают маршруты. При этом сам набор методов и принципы авторизации у БУС и Битрикс24 во многом схожи, так что опыт работы с B24 переносится на коробочную версию — просто настройка требует больше ручных шагов.
Через REST API доступны практически все ключевые сущности сайта. В зависимости от установленных модулей и выданных прав внешняя система может работать с:
- Инфоблоками — элементы, разделы, свойства, поля API_CODE и DETAIL_TEXT/PREVIEW_TEXT.
- Каталогом и торговыми предложениями — товары, цены, остатки, привязки к разделам.
- Пользователями и группами — создание, обновление, назначение прав.
- Заказами и корзинами — чтение и модификация для интернет-магазина.
- Произвольными сущностями — через D7-контроллеры наружу выводятся любые данные проекта.
Именно этот набор определяет, какие интеграции можно построить — от простой синхронизации каталога до сквозного обмена данными между сайтом и ERP.
Основные возможности и способы авторизации
Главная ценность REST API — возможность соединить сайт с внешней инфраструктурой бизнеса. Типичные связки:
- CRM — лиды и сделки синхронизируются с заявками с сайта, менеджер работает в одной системе.
- Маркетплейсы — каталог, цены и остатки выгружаются на площадки и обновляются автоматически.
- ERP — заказы попадают в учётную систему, а статусы и складские остатки возвращаются на сайт.
- Мобильное приложение — использует API как единый источник данных о товарах и заказах.
Преимущество такого подхода — единая точка входа и предсказуемый формат обмена. Интеграцию проще тестировать, расширять и передавать команде в сопровождение.
Входящий вебхук или OAuth 2.0
В REST API БУС доступны два основных способа авторизации. Выбор зависит от масштаба задачи.
Сравнение по ключевым параметрам:
- Сложность настройки. Входящий вебхук — низкая, ключ включён в ссылку и готов к работе за минуты. OAuth 2.0 — высокая, нужна регистрация приложения, scope и обмен токенами.
- Безопасность. У вебхука ключ в URL, требуется защищённое хранение и ручная ротация. У OAuth 2.0 — автообновление access-токена, короткий срок жизни, меньше рисков утечки.
- Управление правами. Вебхук — один ключ на приложение, права задаются при создании. OAuth 2.0 — гибкие scope-права, разграничение доступа по приложениям.
- Поддержка SaaS. У вебхука ограниченная, он привязан к адресу и ключу. OAuth 2.0 ориентирован на облачные и мультиарендные интеграции.
- Сценарии. Вебхук хорош для быстрых интеграций одной-двух систем и тестовых обменов. OAuth 2.0 — для enterprise-проектов со множеством приложений и строгими требованиями к безопасности.
Вывод: для разовой или быстрой задачи берите входящий вебхук — он настраивается за минуты. Для серьёзных проектов со множеством приложений и строгими требованиями — OAuth 2.0.
SDK CRest и популярные методы
Чтобы не писать HTTP-клиенты с нуля, доступен готовый PHP SDK — класс CRest. Это набор из пяти файлов: настройки авторизации, класс для работы с REST API, проверка конфигурации веб-сервера и пример вызова методов.
Чаще всего на практике используются:
- iblock.Element.get / iblock.Element.list — чтение элементов инфоблока.
- crm.lead.add — создание лида в CRM.
- crm.deal.update — обновление сделки по внешнему ключу.
- crm.product.list — получение списка товаров для сверки.
- batch — пакетный запрос, объединяющий несколько методов в один HTTP-вызов.
Пакетный режим особенно полезен при массовых операциях: вместо десятков запросов вы отправляете один, что заметно ускоряет синхронизацию больших каталогов.
REST API в БУС работает как конструктор: стандартные методы закрывают 80–90 % задач синхронизации без правки ядра, а недостающее добавляется собственными D7-контроллерами.
Как настроить REST API в БУС
Переходим к практической части — пошаговый сценарий активации REST API в БУС.
Установка и проверка модуля rest
Первый шаг — убедиться, что модуль rest установлен и активен. Зайдите в админку по пути Настройки → Настройки продукта → Модули. Без активного модуля REST API просто не будет отвечать на запросы.
Создание страницы управления вебхуками
В БУС нет встроенного интерфейса для генерации вебхуков, поэтому его создают вручную. В каталоге /local/rest/ разместите файл index.php с компонентом bitrix:rest.hook. Примерный код: require header, компонент bitrix:rest.hook, затем footer.
Настройка urlrewrite.php и очистка кеша
Добавьте правила в файл urlrewrite.php в корне сайта. Понадобятся два маршрута: ^/local/rest/ → /local/rest/index.php и ^/rest/ → /bitrix/services/main/ajax.php. После изменения файла обязательно очистите кеш сайта, иначе новые правила могут не примениться сразу.
Настройка доступа к инфоблокам
В настройках нужного инфоблока включите опцию «Доступ через REST» и задайте символьный код API (поле API_CODE). Без этого REST-методы не смогут обратиться к элементам. После этого можно выполнить тестовый вызов iblock.Element.get и убедиться, что связка «модуль + вебхук + инфоблок» работает.
Расширение REST API собственными методами
Стандартный метод iblock.Element.get по умолчанию возвращает ограниченный набор полей: ID, NAME, IBLOCK_SECTION_ID. DETAIL_TEXT, PREVIEW_TEXT, DETAIL_PICTURE и CODE стандартными средствами недоступны — их нужно добавить через собственную реализацию контроллера. Современный способ — D7-контроллеры.
Базовая схема расширения:
- Создайте класс контроллера, наследующий DefaultElement, и переопределите метод для формирования расширенного ответа.
- Объявите метод с уникальным scope в обработчике события OnRestServiceBuildDescription.
- Зарегистрируйте обработчик через AddEventHandler("rest", "OnRestServiceBuildDescription", ...).
- Вызовите метод по адресу /rest/ID_пользователя/токен/scope.method/.
Такой подход позволяет выставить наружу любые данные проекта.
Ключ вебхука — это фактически пароль к данным сайта. Храните его в защищённом хранилище, ограничивайте scope и регулярно ротируйте токены.
Практические рекомендации
Примеры интеграций
Три сценария, которые чаще всего реализуют через REST API БУС:
- Создание лида — отправка заявки с сайта в CRM методом crm.lead.add.
- Задача с чек-листом — автоматическое создание задачи для сотрудника с готовым перечнем шагов.
- Обмен с фулфилментом — передача данных заказа на склад и возврат статуса выполнения на сайт.
Во всех трёх случаях логика одна: сайт отдаёт или принимает данные по вебхуку, а внешняя система обрабатывает их и отвечает.
Безопасность ключей и токенов
- Храните ключи в переменных окружения или защищённом хранилище, а не в коде и репозиториях.
- Выдавайте только те scope, которые реально нужны приложению.
- Регулярно ротируйте токены и отзывайте доступ при подозрении на утечку.
- Не оставляйте ключи в логах и отчётах об ошибках.
Обработка ошибок и тестирование
Сначала убедитесь, что запрос доходит до нужного адреса и модуль REST активен. Затем проверьте формат ответа — REST возвращает JSON. Тестируйте на отдельных сущностях, а не на боевых данных. Для массовых операций используйте batch и следите за лимитами запросов.
Начните с малого: сгенерируйте входящий вебхук и вызовите тестовый метод. Каждый шаг проверяйте на боевом адресе через инструменты разработчика.
Итоги
REST API открывает сайту на «1С-Битрикс: Управление сайтом» дорогу к полноценной интеграции с CRM, ERP, маркетплейсами и мобильными приложениями. В отличие от Битрикс24, в БУС ключи настраиваются вручную: нужны активный модуль rest, страница вебхуков в /local/rest/, правила в urlrewrite.php и доступ к инфоблокам по API_CODE.
Для большинства задач достаточно входящего вебхука, а OAuth 2.0 выбирают при высоких требованиях к безопасности. Там, где встроенных методов не хватает, API расширяется собственными D7-контроллерами.
Читайте оригинальную статью: REST API 1С-Битрикс: полное руководство по настройке и интеграциям.