REST API Битрикс24: с чего начать

REST API Битрикс24 — это единый HTTP-интерфейс к CRM, задачам, диску, телефонии и другим модулям облачного или коробочного портала. Разберём, как устроен доступ, чем вебхук отличается от приложения и с чего начать первую интеграцию, не наступая на типовые грабли.

Что такое REST API Битрикс24 и чем он не является

REST API Битрикс24 — это программный интерфейс к порталу и CRM, а не к CMS «1С-Битрикс: Управление сайтом». Методы вызываются по HTTP, данные передаются в JSON, а базовый адрес привязан к домену вашего портала: https://ваш-портал.bitrix24.ru/rest/. У коробочной версии адрес указывает на ваш сервер, но набор методов и логика те же.

Через API доступны почти все сущности продукта: сделки и лиды CRM, товары, задачи, чаты и открытые линии, файлы на Диске, звонки телефонии, пользователи и структура компании. Каждый метод имеет имя вида модуль.сущность.действие — например, crm.deal.add, tasks.task.list, user.get.

• Что можно: читать и писать данные CRM, автоматизировать создание сделок, синхронизировать каталог, слать сообщения в чат, ставить задачи.
• Чего нельзя: напрямую лезть в SQL портала, менять ядро, обходить права пользователя — API работает строго в рамках выданных прав (scope).

Два способа доступа: вебхук и приложение

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

Практическое правило: если вы делаете обмен для одного своего портала и никому его не продаёте — начните с вебхука, это быстрее. Если продукт будет ставиться на чужие порталы или нужны встройки в интерфейс — только приложение с OAuth.

Формат запроса и ответа

Любой метод можно вызвать через GET или POST. Параметры передаются как обычные поля формы (или JSON в теле). Ответ всегда содержит поле result, а для выборок — служебные total, next и time.

POST /rest/1/xxxxxxxxxxxx/crm.deal.add.json
{
  "fields": {
    "TITLE": "Заявка с сайта",
    "OPPORTUNITY": 15000,
    "CURRENCY_ID": "RUB"
  }
}

// Ответ
{
  "result": 128,
  "time": { "start": 1712300000.1, "finish": 1712300000.4, "duration": 0.3 }
}

Ошибка приходит с полями error и error_description. Например, {"error":"invalid_token","error_description":"..."} означает, что токен истёк или отозван, а INSUFFICIENT_SCOPE — что не хватает прав.

Лимиты, пагинация и batch

API возвращает не более 50 записей за один вызов списочного метода. Для следующей страницы используйте значение поля next в параметре start.

• Скорость: у облака действует ограничение на частоту запросов (по умолчанию порядка 2 запросов в секунду на метод, плюс защита от перегрузки). При превышении вернётся ошибка QUERY_LIMIT_EXCEEDED.
• Отключение подсчёта: для быстрой постраничной выгрузки передавайте start=-1 — тогда не считается общий total и выборка идёт быстрее.
• batch: метод batch объединяет до 50 команд в одном запросе и умеет подставлять результат предыдущей команды в следующую через ссылки $result[cmd].

POST /rest/1/xxxx/batch.json
{
  "halt": 0,
  "cmd": {
    "deal": "crm.deal.add?fields[TITLE]=Тест",
    "tovar": "crm.deal.productrows.set?id=$result[deal]&rows[0][PRODUCT_NAME]=Услуга&rows[0][PRICE]=1000&rows[0][QUANTITY]=1"
  }
}

Инструменты и документация

Официальная документация живёт на apidocs.bitrix24.ru (ранее — раздел «Разработчикам» в справке). Для отладки удобны:

1. Postman / curl — быстрый ручной вызов методов по URL вебхука.
2. Метод methods — вернёт список доступных вам методов, а scope — выданные права.
3. Событие в консоли портала — раздел «Разработчикам» показывает вебхуки, приложения и логи.
4. BX24.js — JS-SDK для клиентских приложений и встроек, оборачивает вызовы в BX24.callMethod().

Начните с безобидных методов чтения: profile, user.current, app.info. Они не меняют данные и сразу показывают, что доступ настроен верно.

План первой интеграции

Минимальный маршрут от нуля до рабочего обмена выглядит так:

1. Определите сценарий: что и куда передаём (например, заявки с сайта → лиды CRM).
2. Создайте входящий вебхук и выдайте ему только нужный scope (crm).
3. Проверьте доступ методом crm.lead.fields — увидите структуру полей.
4. Реализуйте запись через crm.lead.add и обработку ошибок.
5. Добавьте пагинацию и batch там, где идёт массовая выгрузка.
6. Настройте логирование запросов и ответов для разбора инцидентов.

Когда сценарий перерастает один портал или требует встроек в интерфейс — переходите на приложение с OAuth 2.0, вебхук при этом можно оставить для внутренних задач.

Итог

REST API Битрикс24 даёт полный программный доступ к порталу через понятные HTTP-методы. Для старта достаточно понять три вещи: способ авторизации (вебхук или приложение), формат «result + служебные поля» и лимиты с пагинацией и batch. С этим фундаментом можно строить любой обмен — от простой передачи заявок до двусторонней синхронизации с 1С.

Если сценарий сложный — двусторонняя синхронизация, высокая нагрузка, тиражное приложение — мы в B2Bsite проектируем и разрабатываем такие интеграции под ключ: от схемы обмена и обработки ошибок до мониторинга и SLA.