REST API Битрикс24: первые запросы и авторизация

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

Разберём, как устроен запрос, чем вебхук отличается от приложения, как читать ответ с постраничной выдачей, объединять вызовы в пакеты и не упираться в лимиты.

Два способа авторизации

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

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

Структура запроса

Любой вызов REST API строится по одной схеме:

https://your-portal.bitrix24.ru/rest/1/x7k2m9p4q1w8e5r3/crm.lead.list.json
                                      |  |                 |
                                      |  |                 +-- метод
                                      |  +-- код вебхука
                                      +-- ID пользователя

Параметры передаются методом POST в теле запроса или GET-строкой. POST предпочтительнее: у GET есть ограничение на длину URL, и при передаче больших фильтров запрос просто оборвётся.

Самый простой способ проверить, что доступ работает, — вызвать метод profile:

https://your-portal.bitrix24.ru/rest/1/x7k2m9p4q1w8e5r3/profile.json

В ответ придут данные сотрудника, от имени которого работает вебхук:

{
    "result": {
        "ID": "1",
        "ADMIN": true,
        "NAME": "Иван",
        "LAST_NAME": "Петров",
        "TIME_ZONE_OFFSET": 10800
    },
    "time": { "duration": 0.08 }
}

Если вместо этого вернулась ошибка INVALID_CREDENTIALS — код вебхука неверен или сотрудник заблокирован. Полезно начинать отладку именно с profile: он не требует никаких прав и сразу отвечает на вопрос «доступ вообще есть?».

Первый содержательный запрос

Получим список лидов. Метод crm.lead.list принимает три знакомых по ORM параметра: select, filter и order.

<?php

use Bitrix\Main\Web\HttpClient;

$webhook = 'https://your-portal.bitrix24.ru/rest/1/x7k2m9p4q1w8e5r3/';

$params = [
    'select' => ['ID', 'TITLE', 'STATUS_ID', 'DATE_CREATE'],
    'filter' => [
        'STATUS_ID'     => 'NEW',
        '>DATE_CREATE'  => '2026-08-01T00:00:00+03:00',
    ],
    'order'  => ['DATE_CREATE' => 'DESC'],
];

$http = new HttpClient(['waitResponse' => true]);
$response = $http->post($webhook . 'crm.lead.list.json', http_build_query($params));

$data = json_decode($response, true);

foreach ($data['result'] as $lead) {
    echo $lead['ID'] . ' — ' . $lead['TITLE'] . PHP_EOL;
}

Префиксы в фильтре работают так же, как в ORM Битрикс:

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

Списочные методы возвращают не более 50 записей за раз — независимо от того, сколько их в базе. Это главный источник ошибок у тех, кто впервые выгружает данные: скрипт отрабатывает без ошибок, но забирает только первые 50 сделок.

Кроме result в ответе приходят два служебных поля:

Поле next приходит только тогда, когда есть что забирать дальше. На этом и строится цикл выгрузки:

$all   = [];
$start = 0;

do {
    $params['start'] = $start;

    $response = $http->post($webhook . 'crm.lead.list.json', http_build_query($params));
    $data     = json_decode($response, true);

    if (!isset($data['result'])) {
        break; // ошибка — дальше идти бессмысленно
    }

    $all = array_merge($all, $data['result']);

    $start = $data['next'] ?? null;

    usleep(500000); // 0.5 сек: держимся в пределах лимита

} while ($start !== null);

echo 'Выгружено: ' . count($all);

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

Основные группы методов

Методов в Битрикс24 несколько сотен. Ориентироваться проще по префиксу — он совпадает с названием модуля:

Два служебных метода стоит запомнить отдельно:

• methods — вернёт список методов, доступных с текущими правами;
• scope — покажет, какие права выданы вебхуку или приложению.

Если метод возвращает insufficient_scope, вызов scope сразу показывает, чего не хватает, — это быстрее, чем перебирать галочки в настройках наугад.

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

Когда нужно выполнить много операций, отправлять их по одной бессмысленно: упрётесь в лимит частоты. Метод batch принимает до 50 команд за один вызов.

$params = [
    'halt' => 0, // 0 — продолжать при ошибке, 1 — остановиться
    'cmd'  => [
        'lead1' => 'crm.lead.add?' . http_build_query([
            'fields' => ['TITLE' => 'Заявка 1', 'NAME' => 'Иван'],
        ]),
        'lead2' => 'crm.lead.add?' . http_build_query([
            'fields' => ['TITLE' => 'Заявка 2', 'NAME' => 'Пётр'],
        ]),
    ],
];

$response = $http->post($webhook . 'batch.json', http_build_query($params));
$data     = json_decode($response, true);

// Результаты лежат под теми же ключами, что и команды
$firstLeadId = $data['result']['result']['lead1'];

Внутри пакета команды могут ссылаться на результаты предыдущих через выражение $result[ключ]. Это позволяет за один запрос создать контакт и сразу привязать к нему сделку, не дожидаясь ответа с ID.

Ошибки и лимиты

Успешный ответ всегда содержит ключ result. Ошибка — ключи error и error_description. Проверять нужно именно наличие result: HTTP-код при ошибке метода может остаться 200.

Ограничения, о которые чаще всего спотыкаются:

• Не более двух запросов в секунду — считается по интенсивности обращений;
• 50 записей в ответе списочного метода;
• 50 команд в одном пакете batch;
• часть методов доступна не на всех тарифах — например, работа с бизнес-процессами.

Как отлаживать

Несколько приёмов, которые экономят часы:

• Начинайте с profile. Он отделяет проблемы доступа от проблем в самом запросе.
• Проверяйте состав полей через *.fields. Методы вида crm.lead.fields возвращают актуальный список полей вместе с пользовательскими, и это надёжнее любой документации.
• Логируйте полный ответ, а не только результат. В error_description обычно написано ровно то, что пошло не так.
• Сначала выполните запрос вручную в браузере. Для GET-методов достаточно вставить URL в адресную строку и посмотреть JSON.

Итог

REST API Битрикс24 устроен предсказуемо: единый формат URL, JSON на выходе, знакомые по ORM фильтры и сортировки. Для интеграции одной компании подойдёт вебхук, для тиражируемого продукта — приложение с OAuth.

Три вещи, которые определяют, будет ли интеграция работать на реальных объёмах: помнить про постраничную выдачу по 50 записей, держать паузу между запросами и объединять массовые операции в batch. Всё остальное — детали конкретных методов, которые всегда можно уточнить вызовом *.fields у самого портала.