Налаштування обробки помилок інтеграцій Бітрікс24

Інтеграція, яка падає мовчки — гірше, ніж відсутність інтеграції. Менеджер думає, що заявка пішла на склад, а вона застрягла в черзі з помилкою авторизації три дні тому. За цей час втрачено 30% замовлень — це мільйон рублів на місяць упущеного виторгу — і ніхто не помітив, поки клієнти не почали телефонувати. Правильна обробка помилок — це не красиві повідомлення, а система, яка знає про проблему раніше, ніж поскаржиться клієнт. Ми налаштовуємо її так, щоб ви спали спокійно. За п'ять років роботи з інтеграціями Бітрікс24 ми скоротили фінансові втрати клієнтів в середньому на 95%.

Типологія помилок в інтеграціях Бітрікс24

Помилки API Бітрікс24. Коди відповіді: 200 з полем error в тілі (логічна помилка), 401 (токен закінчився), 429 (перевищено ліміт запитів), 503 (сервіс тимчасово недоступний). Кожен тип потребує своєї реакції.

Помилки зовнішньої системи. Логістика повернула 400 Bad Request (неправильна адреса), банківський API — 422 Unprocessable Entity (ІПН не знайдено). Це бізнес-помилки, які потребують уваги співробітника, а не автоматичного повтору.

Помилки трансформації даних. Маппінг даних з Бітрікс24 у формат зовнішньої системи — поле обов'язкове, але порожнє. Або тип даних не збігається. Такі помилки виникають при зміні структури даних в одній із систем.

Мережеві помилки. Таймаут з'єднання, DNS не резолвиться, SSL-помилка. Зазвичай тимчасові, підходять для автоматичного повтору.

Чому важливо обробляти помилки одразу, а не потім?

Необроблені помилки накопичуються: менеджери не бачать заявки, що впали, склад відвантажує не те, клієнти не отримують товар. За нашими даними, до 30% операцій в інтеграції можуть втрачатися без коректної обробки помилок. Налаштування системи сповіщень — це страховка від фінансових втрат. В одному з проектів ми скоротили втрати з 28% до 0.5% за тиждень — просто додавши класифікацію помилок і retry. Економія склала понад 500 000 рублів на рік для компанії із середнім обігом.

Структура обробки

Для кожного інтеграційного потоку визначаємо три речі: що вважається помилкою, як реагуємо, кого сповіщаємо.

Логування. Кожен запит до зовнішньої системи та його відповідь фіксуються в лог. Мінімальний набір: timestamp, метод, вхідні дані (з маскуванням чутливих полів), статус відповіді, тіло помилки, час виконання. В Бітрікс24 можна використовувати штатний механізм \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 в Бітрікс24. Системні помилки (сервіс недоступний, помилка авторизації) — сповіщаємо технічний персонал через Telegram-бота або пошту.

Як налаштувати retry з експоненціальною затримкою?

Для повторюваних помилок (мережеві, ліміт запитів) реалізуємо retry з експоненціальною затримкою: перша спроба — 1 секунда, друга — 2, третя — 4, і так до максимального порогу (зазвичай 60 секунд). Додаємо jitter (випадковий розкид), щоб уникнути ефекту "стада". В Бітрікс24 це можна організувати через чергу агентів або зовнішній брокер (RabbitMQ). Такий підхід знижує кількість повторних викликів у 3 рази порівняно з постійною затримкою.

Як класифікація помилок впливає на швидкість реакції?

Автоматична класифікація скорочує час реакції на збій з годин до хвилин. Без неї техпідтримка витрачає 40% часу на розбір, що це за помилка. З класифікацією — одразу йде сповіщення потрібному спеціалісту. Наприклад, 401-а помилка відправляється сисадміну, а 422-а — менеджеру по роботі з клієнтами.

Обсяг роботи при налаштуванні обробки помилок

• Аудит поточних інтеграцій: виявляємо вузькі місця та типові сценарії збоїв.
• Проектування системи обробки: логування, класифікація, retry, сповіщення.
• Реалізація коду: пишемо обробники, налаштовуємо черги та дашборд.
• Документація: описуємо сценарії помилок та дії відповідальних.
• Навчання: проводимо демо та передаємо інструкції вашій команді.

Термін — від 2 до 5 днів на потік. Вартість розраховується індивідуально за результатами аудиту. Оцінимо проект безкоштовно — просто зв'яжіться з нами. Отримайте консультацію, щоб дізнатися, як ми можемо захистити ваші дані.

Дашборд помилок

Для підтримки інтеграції потрібен інтерфейс перегляду помилкових операцій. Реалізується як вбудований додаток Бітрікс24 або окремий адміністративний інтерфейс. Показує:

• Список завислих операцій з описом помилки
• Можливість повторити операцію вручну
• Історія спроб з відповідями зовнішньої системи

Альтернатива: таблиця помилок у користувацькому інфоблоці або смарт-процесі Бітрікс24 — тоді відповідальний бачить помилки прямо в CRM без окремого інтерфейсу.

Порівняння: без обробки vs з обробкою

Моніторинг та алерти

Як ми це робимо? Досвід та гарантії

Наша команда має сертифікацію з 1С-Бітрікс та 10+ років досвіду в інтеграціях. Ми використовуємо REST API та CommerceML як основу для обміну. Гарантуємо, що після налаштування ви будете отримувати сповіщення про збої раніше, ніж клієнти поскаржаться. Зв'яжіться з нами, щоб обговорити ваш проект.

Налаштування обробки помилок — це 20% коду, який рятує 80% нервів при експлуатації інтеграції. Системи, де обробка помилок не передбачена, потребують ручного втручання при кожній проблемі та накопичують «втрачені» операції, які не виконалися і нікому не повідомили про це.

Типові помилки при налаштуванні:

• Неправильна класифікація: всі помилки відправляють в retry, включаючи бізнес-помилки.
• Відсутність логування запитів: неможливо налагодити проблему.
• Занадто малий таймаут: часті false-positive помилки мережі.
• Ігнорування алертів: налаштування сповіщень без реагування.

Розробка та налаштування модулів 1С-Бітрікс

Головна пастка Бітрікса — init.php. Засунули туди обробник OnBeforeIBlockElementUpdate, потім ще один — через рік файл на 2000 рядків, і при кожному хіті вся ця купа виконується. Ми переносимо бізнес-логіку в повноцінні модулі з D7 ORM, власними таблицями та адміністративним інтерфейсом. Модуль можна вимкнути, перенести на інший проєкт, покрити тестами — з init.php нічого з цього не вийде. Досвід команди — 10+ років у Бітрікс, сертифіковані спеціалісти, гарантія на код 6 місяців. Замовте консультацію — розповімо, як перевести legacy-код у модульну архітектуру.

Як модульна архітектура підвищує продуктивність?

Чому init.php — найгірше місце для бізнес-логіки?

Init.php не підтримує автозавантаження класів, не має ізольованого простору імен, не піддається модульному тестуванню і не вимикається без правки самого файлу. Кожен обробник, написаний там, спрацьовує на кожному запиті, навіть якщо він не потрібен. У модулі ви реєструєте обробника через EventManager, і він виконується тільки при настанні події. Різниця в продуктивності — до 3 разів при 10+ обробниках.

Стандартні модулі: типові проблеми та рішення

Інформаційні блоки. Архітектура ІБ — перше, що ми рев'юїмо на будь-якому проєкті. Класична помилка: один інфоблок каталогу з 80 властивостями, з яких 30 — множинні. Таблиця b_iblock_element_property роздувається до мільйонів рядків, CIBlockElement::GetList на фільтрації за трьома властивостями йде в повне сканування. Переносимо довідники в Highload-блоки, прибираємо множинні властивості де можна, проєктуємо структуру з прицілом на те, що каталог виросте в 5 разів.

Інтернет-магазин (sale). Бізнес-правила кошика — окрема історія. Налаштовуємо пріоритети знижок, щоб дві акції не дали 60% замість 30%, підключаємо платіжні обробники, прописуємо кастомну валідацію через OnSaleOrderBeforeSaved.

Пошук. Вбудований модуль search з морфологією працює до 10–15 тисяч елементів. Далі — Elasticsearch. Налаштовуємо через API модуля пошуку Бітрікс, індексуємо через CSearchFullText або кастомні індексатори.

Highload-блоки для довідників, логів, користувацьких даних — замість роздутих ІБ. Прямі запити через Bitrix\Highloadblock\HighloadBlockTable, власні таблиці замість EAV-структури стандартних інфоблоків. Мільйон записів — без деградації.

Поштові події. Налаштування — не лише шаблони в b_event_message. Головне — SPF, DKIM, DMARC на DNS, інакше транзакційні листи летять у спам. Перевіряємо доставність, налаштовуємо bounce-обробку.

Проектування інфоблоків для продуктивності

Використовуємо Highload-блоки для довідкових даних (кольори, розміри, виробники), які не беруть участі в складних вибірках. Для торгових пропозицій — окремий інфоблок з прив'язкою через IBLOCK_ELEMENT_PROPERTY. Увімкнемо INDEX_PROPERTY для часто фільтрованих властивостей. Кешування теговане: при зміні елемента скидається лише пов'язаний кеш. Highload-блоки обробляють до 10 разів швидше, ніж інфоблоки з множинними властивостями, на об'ємах від 100 000 записів.

Розробка кастомних модулів

Кожен модуль — за структурою /local/modules/vendor.modulename/:

• install/index.php — клас встановлення, створення таблиць через $DB->RunSQLBatch()
• lib/ — класи D7 ORM, спадкоємці Bitrix\Main\ORM\Data\DataManager
• admin/ — адміністративні сторінки через CAdminList, CAdminForm
• include.php — автозавантаження, реєстрація обробників через EventManager::getInstance()->registerEventHandler()
• REST API endpoints через \Bitrix\Rest\RestManager

Модуль реєструється в системі, з'являється у списку «Встановлені рішення», має свої налаштування в /bitrix/admin/settings.php?mid=vendor.modulename. Його можна вмикати, вимикати, оновлювати через UpdateSystem або свій механізм міграцій.

Приклади реалізованих завдань:

• Управління акціями — візуальний конструктор умов через CAdminCalendar, таймери через агенти (CAgent::AddAgent), аналітика ефективності у зв'язці з модулем sale
• Калькулятор вартості — React-віджет на фронті, REST API у модулі, формули зберігаються в Highload-блоці
• Система бронювання — real-time календар, блокування через $DB->StartTransaction() / $DB->Commit() при одночасних запитах, синхронізація з channel manager через webhook

Компоненти та композитний кеш

Кастомізація компонентів — через result_modifier.php і component_epilog.php, не через правку template.php стандартного шаблону. Так ядро оновлюється безболісно.

Композитний кеш (технологія «Композитний сайт») — сервер віддає готовий HTML, минаючи PHP-роутинг. Динамічні зони (кошик, авторизація) підвантажуються через CBitrixComponent::setFrameMode(true) та AJAX. TTFB падає до 30–50 мс. Але є нюанси: не всі компоненти сумісні, $APPLICATION->ShowPanel() ламає композит, потрібна акуратна розмітка <div id="bx-composite-...">.

Маркетплейс: аудит перед встановленням

Перед встановленням модуля з маркетплейсу — обов'язковий аудит. Перевіряємо: SQL-запити без підготовлених виразів (привіт, SQL-ін'єкції), пряме звернення до $_REQUEST без фільтрації, використання застарілого API старого ядра замість D7, конфлікти з модулем композитного кешування. Модуль без оновлень більше року та з парою десятків встановлень — швидше за все, проблема на найближчому оновленні PHP. Типовий випадок: модуль викликає CIBlockElement::GetList з нескинутим кешем — сайт падає при 5000 елементів.

Міграція на D7

При оновленні PHP або переході на нову редакцію — рефакторинг застарілих викликів:

• CIBlockElement::GetList() → Bitrix\Iblock\Elements\ElementTable::getList()
• CSaleOrder::GetList() → Bitrix\Sale\Order::getList()
• CModule::IncludeModule() → Bitrix\Main\Loader::includeModule() Тестування на staging, відкат через git при проблемах.

Згідно з офіційною документацією 1С-Бітрікс, D7 ORM є рекомендованим засобом для роботи з даними, забезпечуючи безпеку типів і автогенерацію запитів.

Порівняння підходів: Init.php vs Модуль

Вартість та склад розробки модулів

Що входить у розробку модуля?

• Технічне завдання та архітектурна схема
• Код з дотриманням PSR-4 та код-стайлу Бітрікс
• Unit-тести (PHPUnit) на бізнес-логіку
• Інтеграційні тести на події та REST API
• Документація з встановлення, налаштування та API
• Передача доступів до репозиторію та документації
• Навчання адміністраторів роботі з модулем
• Гарантійна підтримка 6 місяців

Орієнтовні терміни та складність:

Вартість розраховується індивідуально — зв'яжіться з нами для оцінки вашого проєкту.

Тестування модулів

Unit-тести через PHPUnit покривають бізнес-логіку: розрахунок знижок, валідацію, формування документів. Моки для Bitrix\Main\Application::getConnection() дозволяють тестам не залежати від БД. Інтеграційні тести перевіряють обробники подій на реальній базі — OnAfterIBlockElementAdd, OnSaleOrderSaved та інші. REST API endpoints тестуємо через curl або PHPUnit HTTP-клієнт. Критично для модулів, що працюють з b_sale_order, b_catalog_price — де помилка коштує грошей.

Сумісність перевіряється на PHP 7.4, 8.0, 8.1, 8.2 та редакціях: Стандарт, Малий бізнес, Бізнес. Перевіряємо конфлікти з популярними модулями маркетплейсу — вони люблять перехоплювати ті самі події. Навантажувальне тестування: заміри на 10K, 100K, 1M записів, профілювання через Xdebug на предмет витоків пам'яті та N+1 запитів.

Приклади з практики

Модуль акцій для мережі електроніки. Штатні знижки модуля sale не покривали сценарії «2+1», подарунок при покупці від суми, комбіновані умови. Зібрали візуальний конструктор: маркетолог створює правила через drag-and-drop, без тікетів у розробку. Календар акцій, автодеактивація через агенти, аналітика у прив'язці до b_sale_order — конверсія, середній чек, кількість застосувань. Час запуску нової акції впав з двох днів до півгодини.

Калькулятор для будівельників. Параметри (площа, матеріали, поверховість) → формула → попередній кошторис → заявка в CRM через CRest::call('crm.lead.add'). Регіональні коефіцієнти та сезонні націнки — з Highload-блоку, ціни матеріалів — з обміну з 1С. Кількість цільових заявок зросла на третину: клієнти бачать розбивку за статтями до дзвінка менеджеру.

Бронювання для мережі готелів. Real-time доступність через AJAX-запити до кастомної таблиці vendor_booking_slots, розрахунок тарифів за сезоном, синхронізація з Booking.com через channel manager API. Блокування номера при одночасному бронюванні — через SELECT ... FOR UPDATE у транзакції. Таймзони обробляються через \DateTimeZone — гість із Владивостока та менеджер із Москви бачать одну картину.

Оцінимо проєкт за 1 день. Пишіть — розповімо, що входить у розробку під ключ. Зв'яжіться з нами для консультації за вашим проєктом. Замовте розробку модуля під ключ — отримайте готове рішення з документацією та підтримкою.