Налаштування обробки помилок інтеграцій Bitrix24
Інтеграція, яка падає мовчки — гірше, ніж відсутність інтеграції. Менеджер думає, що заявка пішла на склад, а вона застрягла у черзі з помилкою аутентифікації три дні тому. Правильна обробка помилок — це не красиві повідомлення, а система, яка знає про проблему раніше, ніж скаржиться клієнт.
Типологія помилок в інтеграціях Bitrix24
Помилки API Bitrix24. Коди відповідей: 200 з полем error у тілі (логічна помилка), 401 (токен істік), 429 (перевищено обмеження запитів), 503 (сервіс тимчасово недоступний). Кожен тип вимагає своєї реакції.
Помилки зовнішної системи. Логістика повернула 400 Bad Request (невірна адреса), банківський API — 422 Unprocessable Entity (ІНН не знайдено). Це бізнес-помилки, які вимагають уваги працівника, а не автоматичного повтору.
Помилки трансформації даних. Маппінг даних з Bitrix24 у формат зовнішної системи — обов'язкове поле, але порожнє. Або тип даних не збігається. Такі помилки виникають при зміні структури даних в одній з систем.
Мережеві помилки. Timeout з'єднання, DNS не резолвується, SSL-помилка. Зазвичай тимчасові, придатні для автоматичного повтору.
Структура обробки
Для кожного інтеграційного потоку визначаємо три речі: що вважається помилкою, як реагуємо, кого сповіщаємо.
Логування. Кожен запит до зовнішної системи та його відповідь фіксуються у лог. Мінімальний набір: timestamp, метод, вхідні дані (з маскуванням чутливих полів), статус відповіді, тіло помилки, час виконання. У Bitrix24 можна використовувати штатний механізм \Bitrix\Main\Diag\Debug::writeToFile() або зовнішній стек (Monolog → ELK).
Класифікація помилки. В обробнику помилок визначаємо, до якого класу належить проблема:
switch (true) {
case $e instanceof RateLimitException:
// Чекаємо та повторюємо
$this->scheduleRetry($job, delay: 60);
break;
case $e instanceof AuthException:
// Оновлюємо токен та повторюємо
$this->refreshToken();
$this->scheduleRetry($job, delay: 5);
break;
case $e instanceof ValidationException:
// Це бізнес-помилка — сповіщаємо менеджера
$this->notifyManager($job, $e->getMessage());
$this->markFailed($job);
break;
case $e instanceof NetworkException:
// Тимчасова проблема — retry з експоненціальною затримкою
$this->scheduleRetry($job, delay: $job->getBackoffDelay());
break;
}
Сповіщення. Бізнес-помилки (дані не пройшли валідацію, контрагент не знайдено) — сповіщаємо відповідального менеджера через im.notify.system.add у Bitrix24. Системні помилки (сервіс недоступний, помилка аутентифікації) — сповіщаємо технічний персонал через Telegram-бота або пошту.
Дашборд помилок
Для підтримки інтеграції потрібен інтерфейс перегляду помилкових операцій. Реалізується як вбудований додаток Bitrix24 або окремий адміністративний інтерфейс. Показує:
- Список зависших операцій з описом помилки
- Можливість повторити операцію вручну
- Історія спроб з відповідями зовнішної системи
Альтернатива: таблиця помилок у користувацькому інфоблоці або смарт-процесі Bitrix24 — тоді відповідальна особа бачить помилки прямо у CRM без окремого інтерфейсу.
Моніторинг та сповіщення
| Метрика | Поріг для сповіщення | Дія |
|---|---|---|
| Error rate за 5 хвилин | > 10% | Сповіщення дежурному |
| Розмір черги помилок | > 100 операцій | Сповіщення + ескалація |
| Час без успішних операцій | > 30 хвилин | Критичне сповіщення |
| Застарілий refresh_token | За 24 години до істечення | Попередження |
Налаштування обробки помилок — це 20% коду, який рятує 80% нервів при експлуатації інтеграції. Системи, де обробка помилок не передбачена, вимагають ручного втручання при кожній проблемі та накопичують «втрачені» операції, які не виконалися та нікому не повідомили про це.