REST API Bitrix Framework

REST API Bitrix Framework — это программный интерфейс приложения (API), основанный на архитектурном стиле REST (Representational State Transfer), предоставляемый системой управления веб-контентом «1С-Битрикс: Управление сайтом» и облачным сервисом «Битрикс24». Он позволяет внешним приложениям, скриптам и сервисам взаимодействовать с данными и функционалом системы по протоколу HTTP, используя стандартные методы (GET, POST, PUT, DELETE) и форматы данных (JSON, XML). REST API является ключевым инструментом для интеграции «1С-Битрикс» с другими информационными системами, автоматизации бизнес-процессов и создания кастомных решений (мобильных приложений, внешних виджетов, корпоративных порталов).

История и развитие

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

Первые версии (до 2015 года)

Изначально «1С-Битрикс: Управление сайтом» (версии 16.x и ранее) не имел встроенного REST API. Для внешнего доступа использовались:

SOAP-протокол — громоздкий и сложный для веб-разработки.
Пользовательские скрипты — прямой вызов PHP-компонентов через HTTP, что было небезопасно и нестандартизировано.
Модуль «Интеграция с 1С» — специализированный протокол CommerceML для обмена данными с бухгалтерскими системами.

Появление REST API (2015–2017)

С запуском облачного сервиса Битрикс24 (2012) и ростом его популярности возникла необходимость в универсальном интерфейсе. В 2015 году компания «1С-Битрикс» анонсировала REST API для Битрикс24, а затем адаптировала его для коробочной версии «Управление сайтом» (начиная с версии 17.0.0). Первая версия API охватывала базовые сущности: контакты, компании, сделки, задачи, календари.

Современное состояние (2018 – настоящее время)

Начиная с версии 18.0.0, REST API стал полноценным инструментом разработки. В него были добавлены:

Работа с файлами (загрузка, скачивание, удаление).
Управление пользователями и группами.
Интеграция с CRM (лиды, счета, предложения).
Работа с модулем «Интернет-магазин» (товары, заказы, склады, цены).
Вебхуки — механизм для уведомлений внешних систем о событиях (например, создание сделки, изменение заказа).
События (Event System) — возможность подписываться на события внутри системы и обрабатывать их.

К 2024 году REST API поддерживает более 300 методов, разделённых по модулям (CRM, задачи, календари, документооборот, телефония, почта и др.).

Архитектура и принципы работы

REST API Bitrix Framework построен на стандартных веб-технологиях и следует принципам RESTful-архитектуры.

Протокол и методы

HTTP/HTTPS — единственный транспортный протокол.
Методы HTTP:
GET — получение данных (список, один элемент).
POST — создание новой записи.
PUT — обновление существующей записи.
DELETE — удаление записи.
Формат данных — преимущественно JSON (JavaScript Object Notation), реже XML.

URL-шаблон

Базовый URL для REST API выглядит так: `` https://<домен>/rest/<метод>; ` Где <домен> — адрес сайта или портала Битрикс24, а <метод> — имя метода, например crm.lead.add (добавить лид), task.item.list (список задач), user.get` (получить пользователя).

Аутентификация и авторизация

Для доступа к API требуется аутентификация. Используются два основных механизма:

OAuth 2.0 — стандартный протокол для выдачи токенов доступа. Приложение регистрируется в системе, получает client_id и client_secret, после чего пользователь проходит авторизацию через веб-интерфейс. В результате приложение получает access_token (срок действия — 1 час) и refresh_token (для продления сессии).
Вебхуки (Webhooks) — упрощённый способ для серверных приложений. Создаётся URL с встроенным секретным ключом, который не требует OAuth-авторизации. Используется для автоматизации и интеграции с другими серверами.

Формат ответа

Ответ сервера всегда содержит HTTP-статус (200 — успех, 400 — ошибка запроса, 403 — недостаточно прав, 500 — ошибка сервера) и тело в JSON: ``json { "result": { ... }, "time": { "start": 1234567890.1234, "finish": 1234567890.5678, "duration": 0.4444, "processing": 0.2222, "date_start": "2024-01-01T12:00:00+03:00", "date_finish": "2024-01-01T12:00:01+03:00" } } ``

result — данные (массив, объект или примитив).
time — служебная информация о времени выполнения запроса (поле time может быть отключено в настройках).

Основные методы и модули

REST API Bitrix Framework охватывает практически все функциональные модули системы. Ниже приведены ключевые группы методов.

CRM (crm.*)

crm.lead.* — лиды (создание, получение, обновление, удаление, список).
crm.contact.* — контакты.
crm.company.* — компании.
crm.deal.* — сделки.
crm.invoice.* — счета.
crm.quote.* — коммерческие предложения.
crm.product.* — товары.
crm.currency.* — валюты.
crm.status.* — справочники (статусы, стадии, типы).

Задачи (tasks.*)

task.item.add — создание задачи.
task.item.getdata — получение данных задачи.
task.item.list — список задач с фильтрацией.
task.item.update — обновление задачи.
task.item.delete — удаление задачи.
task.commentitem.* — комментарии к задачам.

Пользователи и группы (user., sonet_group.)

user.get — получение списка пользователей.
user.current — данные текущего пользователя.
user.search — поиск пользователей.
sonet_group.get — список рабочих групп.

Интернет-магазин (sale., catalog.)

sale.order.add — создание заказа.
sale.order.list — список заказов.
sale.basketitem.* — товарные позиции в корзине.
catalog.product.* — товары каталога.
catalog.section.* — разделы каталога.
catalog.price.* — цены.

Документооборот (documentgenerator.*)

documentgenerator.document.add — создание документа.
documentgenerator.template.list — список шаблонов.
documentgenerator.document.get — получение документа.

Телефония (telephony.*)

telephony.externalcall.register — регистрация внешнего звонка.
telephony.externalcall.finish — завершение звонка.
telephony.externalcall.attachrecord — прикрепление записи разговора.

Почта (mail.*)

mail.message.add — создание письма.
mail.message.list — список писем.

Календари (calendar.*)

calendar.event.add — создание события.
calendar.event.get — получение события.
calendar.event.list — список событий.

Вебхуки и события

Вебхуки (Webhooks)

Вебхуки — это URL, которые генерируются системой для внешних сервисов. Они содержат секретный ключ и не требуют OAuth-авторизации. Вебхуки бывают двух типов:

Входящие (Inbound) — внешний сервис отправляет запрос на URL вебхука, и система выполняет метод API.
Исходящие (Outbound) — система отправляет POST-запрос на указанный URL при наступлении определённого события (например, создание сделки, изменение задачи).

События (Event System)

Система событий позволяет подписываться на действия внутри системы. При наступлении события (например, ONCRMDEALUPDATE) система отправляет HTTP-запрос с данными о событии на указанный URL. Это используется для синхронизации данных, логирования, отправки уведомлений.

Ограничения и производительность

REST API Bitrix Framework имеет ряд ограничений, установленных для защиты от перегрузок и злоупотреблений:

Лимит запросов — в облачной версии Битрикс24 действует ограничение на количество запросов в секунду (обычно 2 запроса в секунду на одно приложение, в коробочной версии лимит настраивается).
Пагинация — при получении списков данных используется постраничная выдача (по умолчанию 50 записей на страницу, максимум 500).
Размер данных — максимальный размер тела запроса/ответа — 10 МБ (в коробочной версии может быть увеличен).
Время выполнения — каждый запрос должен выполняться не более 30 секунд (в коробочной версии настраивается).

Примеры использования

Пример 1: Получение списка сделок (cURL)

``bash curl -X GET \ 'https://example.bitrix24.ru/rest/crm.deal.list.json?auth=YOUR_ACCESS_TOKEN' \ -H 'Content-Type: application/json' ` Ответ: `json { "result": [ { "ID": "1", "TITLE": "Сделка №1", "STAGE_ID": "C1:NEW", "OPPORTUNITY": "50000.00", "CURRENCY_ID": "RUB" } ], "total": 1 } ``

Пример 2: Создание лида (PHP)

``php $httpClient = new \Bitrix\Main\Web\HttpClient(); $httpClient->setHeader('Content-Type', 'application/json'); $response = $httpClient->post( 'https://example.bitrix24.ru/rest/crm.lead.add.json?auth=YOUR_ACCESS_TOKEN', json_encode([ 'fields' => [ 'TITLE' => 'Новый лид', 'NAME' => 'Иван', 'LAST_NAME' => 'Петров', 'PHONE' => [['VALUE' => '+7-123-456-78-90', 'VALUE_TYPE' => 'WORK']], 'EMAIL' => [['VALUE' => 'ivan@example.com', 'VALUE_TYPE' => 'WORK']] ] ]) ); ``

Инструменты для разработки

Для работы с REST API Bitrix Framework разработчики используют:

Официальная документация — раздел «REST API» на сайте dev.1c-bitrix.ru.
Sandbox (песочница) — тестовый портал Битрикс24 для отладки приложений.
Библиотеки и SDK — официальные SDK для PHP, JavaScript, Python, Java, C#.
Postman — популярный инструмент для тестирования HTTP-запросов.
Swagger/OpenAPI — некоторые версии API поддерживают генерацию спецификации.

Критика и ограничения

Несмотря на широкие возможности, REST API Bitrix Framework подвергается критике по ряду причин:

Неполная документация — некоторые методы описаны поверхностно, отсутствуют примеры для сложных сценариев.
Ограничения по производительности — в облачной версии лимиты могут быть недостаточны для высоконагруженных интеграций.
Сложность с OAuth 2.0 — процесс получения токенов требует взаимодействия с пользователем, что усложняет автоматизацию.
Отсутствие версионирования — изменения в API могут ломать старые интеграции без предупреждения.
Зависимость от версии продукта — в коробочной версии «1С-Битрикс: Управление сайтом» доступность методов зависит от установленных модулей и версии ядра.

Источники

Официальная документация «1С-Битрикс» — «REST API» (dev.1c-bitrix.ru).
Руководство разработчика «Битрикс24» — «REST API» (helpdesk.bitrix24.ru).
Статья «REST API в Битрикс: что это и как использовать» — официальный блог «1С-Битрикс» (blog.1c-bitrix.ru).
Материалы курса «Разработка интеграций с Битрикс24» — Учебный центр «1С-Битрикс» (academy.1c-bitrix.ru).

BFOmetr — база данных и аналитика по компаниям России.

На главную BFOmetr →