REST API и вебхуки Битрикс24: как искать ошибки интеграции

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

Главное правило: интеграция не должна считать, что запрос успешен только потому, что curl не упал. Нужно читать HTTP-код и JSON-ответ Битрикс24.

Проверить вебхук и портал

Вебхук привязан к конкретному порталу и конкретному пользователю. Если пользователь уволен, отключён или потерял права, интеграция может перестать работать.

Нужно проверить:

• домен портала;
• активен ли пользователь вебхука;
• есть ли у вебхука права на CRM;
• не был ли вебхук пересоздан;
• не используется ли тестовый портал вместо рабочего.

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

Проверить простой метод

Для диагностики удобно начать с простого метода, который не меняет данные. Например, получить информацию о текущем пользователе или список полей CRM.

curl -X POST \
    https://example.bitrix24.ru/rest/1/webhook/crm.lead.fields.json

Если простой метод не работает, не нужно сразу разбирать создание сделки. Сначала права, вебхук, домен, SSL и доступность портала.

Читать JSON-ответ

Битрикс24 может вернуть HTTP 200, но внутри JSON будет error. Код интеграции должен это учитывать.

{
    "error": "ERROR_METHOD_NOT_FOUND",
    "error_description": "Method not found"
}

Типовые ошибки:

• метод написан неверно;
• нет прав на метод;
• поле CRM указано неправильно;
• значение списка не существует;
• превышен лимит запросов;
• портал недоступен.

Поля CRM

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

crm.deal.fields
crm.lead.fields
crm.contact.fields

Если поле типа список, нужно отправлять допустимое значение. Если поле множественное, формат данных должен соответствовать API.

Телефоны и email

Для контактов и лидов телефон и email часто передаются как множественные поля. Формат должен быть корректным.

{
    "fields": {
        "TITLE": "Заявка с сайта",
        "PHONE": [
            {
                "VALUE": "+79990000000",
                "VALUE_TYPE": "WORK"
            }
        ],
        "EMAIL": [
            {
                "VALUE": "client@example.ru",
                "VALUE_TYPE": "WORK"
            }
        ]
    }
}

Если отправить телефон простой строкой туда, где ожидается массив, API может вернуть ошибку или сохранить данные не так, как нужно.

Лимиты и повторные запросы

У REST API есть ограничения по частоте запросов. Если интеграция отправляет много запросов подряд, часть может отклоняться. Нужны очереди, паузы и обработка retry.

if (isset($response['error']) && $response['error'] === 'QUERY_LIMIT_EXCEEDED') {
    sleep(2);
    // повторить позже
}

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

Логирование

В лог нужно писать метод, ID локальной сущности, HTTP-код, краткую ошибку и ID созданной сущности. Не нужно писать вебхук целиком и персональные данные без необходимости.

[
    'method' => 'crm.lead.add',
    'local_id' => 123,
    'http_code' => 200,
    'bitrix_id' => 456,
    'error' => null,
]

Идемпотентность

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

local_order_id = 123
bitrix_deal_id = 456

Это особенно важно для заказов, оплат, доставок и заявок с сайта.

Чек-лист

1. Проверить правильный домен портала.
2. Проверить пользователя и права вебхука.
3. Проверить простой REST-метод.
4. Читать JSON-ответ, а не только HTTP-код.
5. Получить реальные поля через *.fields.
6. Проверить формат телефонов, email и списков.
7. Обработать лимиты и временные ошибки.
8. Логировать без публикации вебхука.
9. Хранить связь локальной сущности и ID Битрикс24.

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