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_…, у smart-процесах (crm.item.*) — ufCrm… у camelCase | Мапінг полів одним модулем; жодних «сирих» імен полів у бізнес-логіці |
Чому це важливо
AI-агент, який пише в CRM, — це інтеграція під навантаженням. Кожен тихий збій коштує довіри: якщо угода не оновилась і ніхто не помітив, менеджер перестає вірити агенту. А довіра команди — головна метрика пілота: другий тихий збій вам уже не пробачать.
Як ми збираємо це тепер
Ідемпотентні записи з контрольним читанням після критичних операцій. Реконсиляція стану раз на кілька хвилин замість сліпої віри вебхукам. batch для всього масового. Мапінг полів в одному модулі. І прогін eval-сету інтеграції перед кожним деплоєм — на тестовому порталі, не на клієнтському.
Що зробили б інакше
Перший тиждень будь-якої інтеграції — read-only. Агент читає, аналізує, пропонує — але не пише. Це повільніше на сім днів і дешевше на місяці розгрібання: половину квірків із таблиці ми б упіймали до того, як вони торкнулися живих угод.
Наш чек-лист інтеграції агента з Bitrix24 — за запитом: andrew@grow2.ai.