Bitrix24 — самая частая CRM у наших клиентов, и мы работаем с ним годами. Но у его REST API есть характер: вещи, которые выглядят очевидными, ведут себя неочевидно — и узнаёшь об этом обычно в продакшне. Вот пять квирков, съевших больше всего часов дебага.
Пять квирков
Каждый пункт — реальное поведение API, а не баг конкретного портала. Собрано из продакшн-интеграций наших агентов с Bitrix24.
| Квирк | Симптом | Обход |
|---|---|---|
| Тихий дроп невалидных значений | crm.deal.update отвечает success, но enum-поле не изменилось: значение вне списка молча игнорируется | Писать ID значения, а не текст; после критичных записей — контрольное чтение |
| Вебхуки без гарантий | События ONCRMDEALUPDATE приходят пачками, с задержкой и не в порядке изменений | Вебхук — лишь сигнал «что-то изменилось»: состояние перечитываем через API, payload не верим |
| Лимит ~2 запроса/сек | На демо всё летает, на живом потоке — QUERY_LIMIT_EXCEEDED | batch до 50 команд за вызов + очередь с ретраями и экспоненциальной паузой |
| Пагинация со скрытым COUNT | Списки на большой базе замедляются с каждой страницей: каждый запрос пересчитывает total | start=-1 отключает подсчёт; идём ID-курсором в фильтре, а не по start |
| UF_* против ufCrm* | Одно и то же кастомное поле в crm.deal.* зовётся UF_CRM_…, в смарт-процессах (crm.item.*) — ufCrm… в camelCase | Маппинг полей одним модулем; никаких «сырых» имён полей в бизнес-логике |
Почему это важно
AI-агент, который пишет в CRM, — это интеграция под нагрузкой. Каждый тихий сбой стоит доверия: если сделка не обновилась и никто не заметил, менеджер перестаёт верить агенту. А доверие команды — главная метрика пилота: второй тихий сбой вам уже не простят.
Как мы собираем это теперь
Идемпотентные записи с контрольным чтением после критичных операций. Реконсиляция состояния раз в несколько минут вместо слепой веры вебхукам. batch для всего массового. Маппинг полей в одном модуле. И прогон eval-сета интеграции перед каждым деплоем — на тестовом портале, не на клиентском.
Что сделали бы иначе
Первая неделя любой интеграции — read-only. Агент читает, анализирует, предлагает — но не пишет. Это медленнее на семь дней и дешевле на месяцы разгребания: половину квирков из таблицы мы бы поймали до того, как они коснулись живых сделок.
Наш чек-лист интеграции агента с Bitrix24 — по запросу: andrew@grow2.ai.