Откройте двигатель CRM: путеводитель по API Битрикс24

Когда типовых возможностей Битрикс24 перестаёт хватать, на сцену выходит REST-API — набор «выводов питания», через которые платформу можно соединить с любым внешним сервисом или собственным приложением. Именно благодаря API чаты пополняют карточку сделки, товары из 1С появляются в счёте за секунду, а маркетинговая платформа сама считает ROI рекламных кампаний.

Меня зовут Александра Гусева, я аналитик в компании RDN Group. Наша команда специализируется на автоматизации бизнес-процессов, разработке сложных и высоконагруженных решений: личных кабинетах, торговых площадках, порталах и интеграционных проектах. Мы внедряем Битрикс24 в крупных компаниях и постоянно сталкиваемся с необходимостью интеграции Битрикс24 с различными сервисами. Сегодня расскажу, как устроен REST-API, какие лимиты придётся учитывать и почему алгоритм Leaky Bucket спасает портал.

«API — это мост между идеей и действием: когда сервисы договариваются на уровне кода, ручная работа исчезает», — Дмитрий Паламарчук, аналитик RDN Group.

Что такое API и зачем он бизнесу

API (Application Programming Interface) — это правило общения двух приложений. Битрикс24 раскрывает через API сотни функций: создание задач, чтение сделок, старт бизнес-процессов, отправка сообщений, работа с файлами и даже управление телефонией. Всё, что доступно в интерфейсе, почти всегда доступно и программисту. Благодаря этому:

• Рутина исчезает. Форма на сайте сразу создаёт лид в CRM.
  
  
• Данные синхронизируются. Каталог товаров из 1С обновляется автоматически.
  
  
• Отчёты обновляются в реальном времени. BI-система не ждёт ручного экспорта CSV.
  
  

Документация открыта и постоянно пополняется новыми методами — более 1200 «команд» доступны уже сейчас. Готовые сценарии использования REST API

Важно помнить, что доступ к REST-API в облачной версии Битрикс24 предоставляется только при активной подписке «Битрикс24 Маркетплейс». Без неё портал позволяет устанавливать готовые приложения из Маркета, но запрещает выдачу токенов, создание веб-хуков и вызов методах API.

Если вы тестируете интеграцию впервые, платформа предлагает 90-дневный пробный период, в течение которого REST-доступ работает без ограничений — этого достаточно, чтобы оценить возможности и подготовить решение к продакшну.

Как работает REST-API Битрикс24 

1. Куда отправлять запрос
У каждого портала есть специальный адрес вида https://<ваш-портал>.bitrix24.ru/rest/…. Он похож на дверь: постучавшись по правильному «ключу» (токену), вы попадаете внутрь системы.

2. Что можно попросить
API понимает два простых «глагола» сети:

• GET — «покажи» (прочитать сделку, список задач).
  
• POST — «измени» (создать или обновить запись).
  
  

В 99 % случаев этого хватает.

3. Как выглядит просьба
Вы отправляете небольшой набор данных в формате JSON. Например, передаёте название будущей сделки и сумму — система создаёт эту сделку у вас в CRM.

4. Что возвращает система
Ответ тоже приходит в JSON: либо нужные данные (ID новой сделки, список задач), либо код и описание ошибки, если что-то пошло не так.

5. Экономия на пакетах
За один «батч» можно объединить до 50 запросов. Это удобно, когда нужно быстро обработать много данных и не превышать лимиты.

6. Автоматические уведомления
Битрикс24 сам сообщает вашему приложению о важных событиях: клиент сменил стадию сделки, менеджер загрузил файл и т.д. Вы подписываетесь на нужное событие — и система мгновенно отправляет уведомление.

Таким образом, REST-API — это формальный, но довольно простой язык, на котором ваше приложение может говорить с Битрикс24: спрашивать данные, создавать объекты и получать новости о том, что происходит в портале.

Лимиты запросов и Leaky Bucket

В облачной версии у каждого портала есть счётчик запросов. Он реализован по алгоритму Leaky Bucket (протекающее ведро) — в «ведро» можно быстро налить воды (сделать всплеск запросов), но она будет вытекать строго дозированно.

1. Каждый запрос увеличивает счётчик на 1.
   
   
2. Каждую секунду счётчик уменьшается на Y единиц (скорость «утечки» зависит от тарифа):
   
   
• Энтерпрайз — 5 ед./сек.
  
  
• Остальные тарифы — 2 ед./сек.
  
  
3. Если счётчик превысил порог X (250 для Энтерпрайз, 50 для остальных), следующие запросы получают ошибку 503 QUERY_LIMIT_EXCEEDED и блокируются, пока уровень не опустится.
   
   

Почему это полезно

Алгоритм позволяет приложениям делать резкие всплески трафика (например, когда внезапно пришло 30 звонков одновременно), но «отсекает» попытки штурмовать сервер без пауз и тем самым бережёт производительность портала для всех пользователей.

Практический пример

Допустим, тариф не Энтерпрайз, а базовый. Количество запросов — 0. Приложение за секунду отправило 40 запросов.

• Счётчик = 40 (< 50) — всё прошло.
  
  
• Если сразу послать ещё 20, счётчик станет 60 (> 50) и 10 запросов получат ошибку 503.
  
  
• Через 1 секунду «ведро» количество запросов уменьшится на 2.
  
  

Как жить с лимитами

• Используйте batch. 1 пакет = 50 вызовов.
  
  
• Запрашивайте списки. crm.contact.list вернёт 50 элементов за раз.
  
  
• Ставьте паузы. Большие выгрузки проще делать по 2–3 запроса в секунду, чем получать ошибку 503.
  
  
• Кэшируйте константы. Справочники стадий или пользователей не меняются каждую минуту.
  
  

Соблюдая эти правила, даже на базовом тарифе можно в сутки выгрузить более 8 миллионов записей, что с головой хватает для 99 % задач.

Добавление собственных REST-методов в «коробочной» версии Битрикс24

В коробочной редакции Битрикс24 разработчик может расширить стандартный REST-API:

1. Регистрация
   В своём модуле вы подключаетесь к системному событию OnRestServiceBuildDescription. Через него объявляете новый «scope» (логическую группу) и список собственных методов.
   
   
2. Описание
   Для каждого метода указываете человекочитаемое название и указываете, какой внутренний PHP-обработчик отвечает за логику.
   
   
3. Появление в документации
   После сохранения изменений и очистки кэша портал автоматически включает ваши методы в общий список API. Внутренние и сторонние приложения смогут запрашивать права на новый scope и вызывать ваш метод так же, как штатные команды — по обычному REST-адресу.
   
   

Итог: «коробка» позволяет встроить в REST-API любую бизнес-логику компании, при этом соблюдая единый механизм авторизации и разграничения доступа.

Заключение

API превращает Битрикс24 в гибкий конструктор, который растёт вместе с бизнесом: подключает роботов, передаёт данные в аналитику и экономит часы рутины менеджеров. 

«Хорошо настроенный REST-API — это незаметный, но незаменимый сотрудник: он работает 24/7, не ошибается и растёт вместе с компанией», — Ольга Марковская, руководитель проектов RDN Group.

Хотите заставить вашу CRM работать на полную мощность? RDN Group проведёт аудит, предложит архитектуру интеграций и реализует её — от первого запроса до публикации приложения на Маркетплейсе. Напишите нам, и ваш бизнес-процесс начнёт экономить время и деньги.