REST API Битрикс24: руководство для разработчиков и интеграторов

Что можно сделать через API

Через REST API доступны почти все модули Битрикс24: CRM, задачи, чаты, календарь, диск, каталог товаров, бизнес-процессы, телефония. Типичные задачи:

создавать лиды и сделки из сайта, маркетплейса или внешней системы;
выгружать данные CRM в BI, хранилище или отчёты;
синхронизировать товары, цены и остатки с учётной системой;
реагировать на события: новая сделка, смена стадии, новое сообщение;
добавлять в Битрикс24 свои роботы, вкладки в карточках и действия бизнес-процессов.

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

Входящий вебхук

Самый простой способ. В портале создаётся вебхук с нужными правами, и вы получаете адрес вида https://портал.bitrix24.ru/rest/ID/КЛЮЧ/. Дальше к нему добавляется имя метода, и запрос выполняется от имени пользователя, создавшего вебхук.

Подходит для интеграций «одна система — один портал»: форма сайта, выгрузка в отчёт, обмен со своим сервисом. Подробнее — в статье о вебхуках Битрикс24.

Ключ вебхука — это пароль. Не публикуйте его в коде на фронтенде и в открытых репозиториях, давайте только нужные права (например, только CRM) и удаляйте вебхуки, которые больше не используются.

Приложение

Приложение авторизуется по OAuth 2.0, получает токен доступа и токен обновления, может встраиваться в интерфейс портала и устанавливаться на много порталов. Это путь для тиражных решений, приложений в маркетплейсе и интеграций, которым нужен интерфейс внутри Битрикс24.

	Вебхук	Приложение
Авторизация	Ключ в адресе	OAuth 2.0, токены обновляются
Интерфейс в портале	Нет	Да: вкладки, кнопки, роботы
Несколько порталов	Нет	Да
Сложность	Минимальная	Выше: нужен сервер и хранение токенов

Как выглядит запрос

Запрос — это обычный HTTPS-запрос с параметрами. Например, создать лид:

POST https://портал.bitrix24.ru/rest/1/ключ/crm.lead.add.json
fields[TITLE]=Заявка с сайта
fields[NAME]=Иван
fields[PHONE][0][VALUE]=+79130000000
fields[PHONE][0][VALUE_TYPE]=WORK
fields[SOURCE_ID]=WEB

В ответе приходит JSON с полем result — для этого метода это ID нового лида. При ошибке в ответе будут error и error_description: их обязательно нужно проверять и записывать в журнал.

Основные методы

CRM

crm.lead.add, crm.lead.update, crm.lead.list — лиды;
crm.deal.add, crm.deal.update, crm.deal.list — сделки;
crm.contact.*, crm.company.* — контакты и компании;
crm.item.* — универсальные методы для смарт-процессов и других типов;
crm.duplicate.findbycomm — поиск дублей по телефону и почте;
crm.activity.* — дела в карточках.

Задачи, чаты, пользователи

tasks.task.add, tasks.task.update, tasks.task.list — задачи;
im.message.add, im.notify.* — сообщения и уведомления;
user.get — сотрудники;
bizproc.workflow.start — запуск бизнес-процесса.

Каталог

catalog.product.* — товары;
catalog.price.* — цены;
catalog.storeproduct.* — остатки по складам.

Постраничная выборка

Методы *.list возвращают данные порциями по 50 записей. В ответе есть поле next — с какого номера запрашивать следующую страницу (параметр start). Частая ошибка новичков — забыть про постраничность и думать, что в CRM всего 50 сделок.

Для больших выгрузок полезно фильтровать по ID (>ID) и сортировать по нему: так выборка не «плывёт», если во время выгрузки появляются новые записи. Ещё одна экономия — параметр select, который ограничивает список полей в ответе.

Пакетные запросы

Метод batch выполняет до 50 команд за один HTTP-запрос. Это ускоряет массовые операции и бережёт лимиты. Внутри пакета можно ссылаться на результат предыдущей команды — например, сначала создать контакт, а потом сделку с его ID.

Лимиты

У портала есть ограничение на частоту запросов: примерно два запроса в секунду с запасом на короткие всплески. При превышении API вернёт ошибку QUERY_LIMIT_EXCEEDED. Правила простые:

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

Для тяжёлых методов есть и ограничение по суммарному времени выполнения, поэтому огромные выборки лучше дробить.

События

Вместо того чтобы постоянно спрашивать «появились ли новые сделки», можно подписаться на события. Битрикс24 отправит запрос на ваш адрес, когда что-то произойдёт: ONCRMDEALADD, ONCRMDEALUPDATE, ONCRMLEADADD, ONTASKADD и другие.

Важные детали:

в событие приходит только ID изменённой записи — сами данные нужно запросить отдельно;
обработчик должен отвечать быстро, а долгую работу выполнять в фоне;
проверяйте ключ приложения или токен в событии, чтобы не принимать поддельные запросы;
события могут прийти повторно — обработка должна быть идемпотентной.

Простой вариант без программирования — исходящий вебхук, который вызывается из робота на стадии сделки.

Практики, которые экономят время

Журнал запросов. Записывайте метод, параметры и ответ. Без журнала разбор ошибок обмена превращается в гадание.
Внешние ID. Храните в Битрикс24 ID записи из внешней системы, а во внешней — ID Битрикс24. Это избавит от дублей при повторной синхронизации.
Поиск дублей перед созданием. Перед созданием контакта ищите его по телефону и почте. Подробнее — в статье о дублях в CRM.
Пользовательские поля. Их коды выглядят как UF_CRM_...; получить список можно методами *.fields или *.userfield.list.
Тестовый портал. Отлаживайте интеграцию не на рабочем портале, а на копии или отдельном тестовом.

Типичные сценарии

Сайт → CRM. Форма сайта создаёт лид или сделку, передаёт UTM-метки. Подробно — в статье об интеграции сайта с Битрикс24.
Учётная система ↔ CRM. Товары и остатки идут в каталог, заказы — обратно. Для 1С чаще используют коннектор или свою интеграцию.
CRM → BI. Регулярная выгрузка сделок для отчётов, которых нет в Битрикс24.
Свой робот. Приложение добавляет в конструктор действие, которого нет в стандартном наборе.

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

Работает ли API на всех тарифах?

Входящие вебхуки и приложения доступны на коммерческих тарифах, а для части возможностей нужна подписка на маркетплейс. Уточняйте условия для вашего тарифа.

Можно ли через API получить записи звонков и переписку?

Да, через дела CRM и методы телефонии и открытых линий, в пределах прав пользователя или приложения.

Как не потерять данные при сбое?

Используйте очередь: событие сначала сохраняется у вас, затем обрабатывается с повторами. Так временная недоступность любой из систем не приводит к потере записей.

Если нужна интеграция, приложение или свой робот для Битрикс24, посмотрите, что мы разрабатываем, или почитайте, как заказать приложение.

REST API Битрикс24