Битрикс24 REST API: полный гид для интеграций 2026

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

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

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

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

Входящий вебхук — это статичная ссылка вида https://your-portal.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/, привязанная к конкретному пользователю портала и набору прав, который администратор выбрал вручную при создании. Никакого OAuth, никакого обновления токена — просто добавляете имя метода и параметры. Подходит для внутренних скриптов, разовых выгрузок, интеграций «для себя», когда вы администрируете и портал, и скрипт. Не подходит для коробочного решения, которое вы продаёте многим клиентам: вебхук нельзя автоматически выписать при установке, его нужно создавать руками в каждом портале.

Локальное/облачное приложение и OAuth 2.0

Если интеграция ставится через Битрикс24.Маркет или должна работать на множестве порталов, единственный вариант — регистрация приложения в разделе «Разработчикам» с получением client_id и client_secret. При установке портал делает редирект на ваш INSTALL-обработчик с кодом авторизации, вы обмениваете его на access_token и refresh_token. access_token живёт около часа, refresh_token нужно использовать для получения нового токена, когда приходит ответ с ошибкой expired_token. Храните оба значения в базе привязанными к domain портала — без этого приложение обслуживает только одну инсталляцию.

Структура запроса и ответа

Все методы REST API вызываются одинаково: POST или GET на https://портал/rest/METHOD, параметры — в теле или в query-строке, авторизация — либо через путь вебхука, либо через auth=access_token. Ответ всегда в JSON с полями result, time и, при ошибке, error/error_description.

POST https://your-portal.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/crm.deal.list.json
Content-Type: application/json

{
  "filter": { "STAGE_ID": "NEW", ">DATE_CREATE": "2026-01-01" },
  "select": ["ID", "TITLE", "OPPORTUNITY", "ASSIGNED_BY_ID"],
  "order": { "DATE_CREATE": "DESC" },
  "start": 0
}

// Ответ
{
  "result": [ { "ID": "1042", "TITLE": "Сделка с ООО Ромашка", "OPPORTUNITY": "150000.0000" } ],
  "next": 50,
  "total": 187,
  "time": { "start": 1736500000.0, "finish": 1736500000.2, "duration": 0.18 }
}

Основные методы: с чего реально начинается 90% интеграций

Отдельно предупреждение про select: никогда не запрашивайте поля через select=["*"] в проде — это резко увеличивает объём ответа и время формирования выборки на стороне портала, особенно на сущностях с десятками пользовательских полей. Явно перечисляйте только то, что реально используете в бизнес-логике.

Независимо от бизнес-логики, любая интеграция с CRM опирается на один и тот же костяк методов. Их стоит выучить наизусть, потому что вариации в названиях (list/get/add/update/delete/fields) одинаковы для всех сущностей.

• crm.deal.list / crm.deal.get / crm.deal.add / crm.deal.update / crm.deal.delete — сделки
• crm.contact.* и crm.company.* — контакты и компании, та же CRUD-схема
• crm.lead.* — лидеры, если в аккаунте включена классическая воронка с лидами
• crm.item.list / crm.item.add (для универсальных смарт-процессов, entityTypeId вместо жёсткой сущности)
• task.item.add / task.item.update — задачи
• user.get, user.current — данные о сотрудниках и о том, от чьего имени сделан запрос
• crm.deal.fields — получить список полей и их типов, включая пользовательские (UF_*)

Пакетные запросы: batch вместо сотен HTTP-вызовов

Метод batch объединяет до 50 вызовов в один HTTP-запрос и возвращает массив результатов в том же порядке. Это не просто оптимизация скорости — это способ не упереться в лимит запросов в секунду при массовой синхронизации. Внутри batch можно ссылаться на результат предыдущего вызова через $result[имя][поле], что удобно для связанных операций (создать сделку → сразу привязать к ней контакт).

POST /rest/1/xxxxxxxxxxxxxxxx/batch.json

{
  "halt": 0,
  "cmd": {
    "deal_new": "crm.deal.add?fields[TITLE]=Новая сделка&fields[STAGE_ID]=NEW",
    "contact_link": "crm.deal.contact.add?id=$result[deal_new]&fields[CONTACT_ID]=118"
  }
}

Лимиты запросов и обработка ошибок

Классическое ограничение Битрикс24 — не более 2 запросов в секунду на пользователя, от имени которого работает интеграция (вебхук или OAuth-приложение). При превышении сервер отвечает HTTP 200 с телом ошибки QUERY_LIMIT_EXCEEDED, а не HTTP 429, поэтому проверять нужно именно поле error в JSON, а не статус-код. Обязательно реализуйте экспоненциальный backoff: получили ошибку — подождали 500 мс, при повторной — 1 с, 2 с, 4 с, с ограничением по числу попыток (5-6 достаточно).

Правило двух в секунду. Любая интеграция, которая шлёт запросы к Битрикс24 в цикле без троттлинга, рано или поздно попадёт в QUERY_LIMIT_EXCEEDED на проде — на своём тестовом портале с парой записей вы этого не увидите. Закладывайте очередь с ограничением скорости и batch-группировку сразу в архитектуру, а не как заплатку после первого инцидента.

Постраничная выгрузка больших объёмов

Список сделок или контактов может насчитывать десятки и сотни тысяч записей. Метод *.list по умолчанию отдаёт 50 записей и поле next с offset для следующей страницы; при total выше 10000 стандартная пагинация через start начинает работать медленно и нестабильно. Для больших выгрузок используйте связку filter по ID (>ID) с сортировкой по ID вместо смещения — так вы не зависите от изменения данных между запросами и обходите ограничение на глубину пагинации.

1. 1.Сделайте первый запрос с order по ID ASC и небольшим select
2. 2.Возьмите ID последней записи и добавьте фильтр {">ID": lastId} в следующий запрос
3. 3.Повторяйте, пока результат не станет пустым
4. 4.Логируйте last processed ID, чтобы при обрыве связи продолжить с того же места, а не с начала

Курс школы: Вебхуки в Битрикс24 без программирования — от 9 990 ₽

Обработчики событий (event.bind)

Кроме опроса методом list, портал умеет сам уведомлять внешний сервис о событиях через event.bind: ONCRMDEALADD, ONCRMDEALUPDATE, ONTASKADD и десятки других. Обработчик регистрируется один раз методом event.bind с указанием event, handler (URL) и опционально event_type. Битрикс24 шлёт POST на ваш URL при каждом срабатывании события, но в теле приходит только ID изменённой записи и код события — данные нужно дозапрашивать отдельным вызовом *.get, потому что событие не гарантирует доставку актуального состояния к моменту обработки.

Тестовый портал перед продакшеном

Разработку и отладку REST-интеграции никогда не ведите на боевом портале клиента. Бесплатный тестовый портал регистрируется за пять минут на bitrix24.ru и живёт достаточно долго для полного цикла разработки. На нём безопасно тестировать crm.deal.delete, массовые импорты и обработчики uninstall — операции, которые на проде обходятся дорого при ошибке в логике.

Интеграция, которая ни разу не видела реального лимита в 2 запроса в секунду, не готова к продакшену — она просто ещё не встретилась с боевой нагрузкой.

Пользовательские поля и типы данных

В реальных внедрениях почти всегда добавлены пользовательские поля — UF_CRM_1234567890_ABC для сделок, поля с привязкой к справочникам, множественные значения. Метод crm.deal.fields возвращает их с типом (string, integer, double, date, enumeration, crm_status и т.д.) и, для enumeration, список допустимых значений с внутренними ID. Прежде чем писать логику маппинга полей на стороне внешнего сервиса, всегда сначала вызывайте *.fields и сохраняйте карту соответствий — жёстко прописанные имена полей в коде ломаются при любой правке структуры CRM на портале клиента.

Отдельная особенность — множественные поля (телефон, email) у контактов и компаний: они возвращаются не строкой, а массивом объектов вида {VALUE, VALUE_TYPE, TYPE_ID}. Забыть это при первой интеграции — классика: код падает или молча теряет второй телефон клиента, потому что ожидал строку.

Версионирование и обратная совместимость

Битрикс24 регулярно обновляет ядро и REST-методы, но старается сохранять обратную совместимость: новые поля добавляются, старые почти никогда не удаляются резко. Тем не менее закладывайте в интеграцию defensive coding — не падать при появлении незнакомого поля в ответе, не полагаться на порядок полей в JSON, всегда явно указывать select в *.list вместо надежды на дефолтный набор полей (дефолт может отличаться между порталами и версиями).

Логирование и наблюдаемость интеграции

Продакшен-интеграция без логов — это чёрный ящик, в котором невозможно быстро найти причину, почему сделка не создалась. Минимальный набор: логировать каждый исходящий запрос (метод, ключевые параметры, без токенов в открытом виде), HTTP-статус и содержимое error/error_description, время выполнения. Для входящих обработчиков событий отдельно логируйте сырое тело запроса до всякой обработки — это единственный способ разобраться в инцидентах постфактум, потому что Битрикс24 не даёт возможность запросить историю уже отправленных вебхуков.

• Храните отдельно лог исходящих вызовов REST и лог входящих событий/установок
• На ошибках уровня error пишите error_description целиком, а не только код
• Добавьте correlation ID, связывающий цепочку batch-вызовов с бизнес-операцией
• Настройте алерт на рост доли INVALID_TOKEN и QUERY_LIMIT_EXCEEDED — это ранний признак проблем с масштабом

Выбор между вебхуком и приложением на практике

Если вы делаете разовую интеграцию для одной компании и у вас есть доступ администратора к порталу — берите входящий вебхук, это экономит недели разработки OAuth-обвязки. Если продукт должен ставиться самостоятельно множеством клиентов через Маркет, или вам нужны исходящие вебхуки и виджеты в интерфейсе — только полноценное приложение с OAuth. Смешанный вариант тоже существует: локальное приложение можно установить на один портал и использовать похожий на вебхук поток, но с возможностью развития до публичного продукта в будущем.

Отдельно стоит учитывать, что у вебхука права выдаются один раз при создании и не меняются без участия администратора портала, тогда как приложение запрашивает scope при установке и может расширять список прав только через новую установку с подтверждением пользователя. Это значит, что при проектировании продукта на OAuth стоит сразу запросить чуть более широкий набор прав, чем нужно на старте — иначе добавление новой фичи через полгода потребует от всех клиентов повторной установки приложения, что снижает удержание.

Чек-лист перед запуском интеграции

• Все вызовы идут через очередь с ограничением 2 запроса/сек на пользователя
• Массовые операции сгруппированы в batch по 50 вызовов
• Есть retry с backoff на QUERY_LIMIT_EXCEEDED и на сетевые таймауты
• Для OAuth-приложений реализовано обновление access_token по refresh_token
• Пагинация больших выборок идёт через фильтр по ID, а не только через start
• Обработчики событий не полагаются на данные из тела запроса — всегда дозапрашивают актуальную запись