Розробка інтеграції Бітрікс24 з логістичними системами

Розробка інтеграції Bitrix24 з логістичними системами

Логістика — одне з вузьких місць у компаніях, де менеджери з продажів та відділ доставки працюють у різних системах. Менеджер закрив угоду в CRM, передав дані в Excel або по телефону, логісти вручну створили заявку у своїй системі — і ланцюжок розірваний. Інтеграція Bitrix24 з TMS (Transport Management System) або WMS (Warehouse Management System) закриває цей розрив.

Типові логістичні системи та їх API

1С:TMS Логістика. HTTP-сервіси 1С, формат даних — JSON або XML. Основні операції: створення заявки на перевезення, отримання статусу, прив'язка документів.

МійСклад. REST API з OAuth 2.0. Багата документація, sandbox. Підтримує управління замовленнями, відвантаженнями, залишками, поверненнями.

СДЕК API v2. REST API, JWT-аутентифікація. Розрахунок вартості, створення замовлення, трекінг, список ПВЗ.

Яндекс.Доставка / DPD / Boxberry / ПЕК. У кожного свій REST API, що різниться структурою даних та механізмами аутентифікації. Для універсальної інтеграції з кількома перевізниками використовуємо паттерн «адаптер»: єдиний інтерфейс усередині застосунку, під кожного перевізника — своя реалізація.

WMS-системи (Manhattan, SAP Extended Warehouse Management, 1С:WMS). Як правило, SOAP або пропрієтарний API. Інтеграція складніша через застарілі протоколи.

Сценарії інтеграції

Угода → заявка на доставку. Угода в Bitrix24 переходить на стадію «Передано на відвантаження» — спрацьовує webhook, адаптер створює заявку в логістичній системі. У картку угоди записується номер заявки (UF_LOGISTICS_ORDER_ID) та трек-номер.

Статуси доставки в CRM. Логістична система відправляє webhook при зміні статусу: «Прийнято на склад», «В дорозі», «Доставлено», «Повернення». Адаптер оновлює стадію угоди через crm.deal.update і додає коментар у timeline через crm.timeline.comment.add.

Розрахунок вартості доставки. На етапі оформлення замовлення (в угоді або в інтернет-магазині) — запит до API перевізника для розрахунку вартості за вагою, габаритами та адресою. Результат — у полі угоди або рахунку.

Вибір ПВЗ. Для інтеграцій з СДЕК, Boxberry, Укрпоштою — віджет вибору ПВЗ на карті всередині картки угоди. Реалізується як вбудований застосунок Bitrix24 з картою (Leaflet + дані ПВЗ з API перевізника).

Повернення. Покупець ініціює повернення — у CRM створюється смарт-процес «Повернення», який запускає процедуру в логістичній системі: забір від покупця, приймання на склад, статус перевірки товару.

Архітектура адаптера

Будуємо PHP-застосунок, який:

1. Слухає webhook Bitrix24 (подія зміни стадії угоди)
2. Маппить дані угоди у формат логістичної системи
3. Викликає API логістики
4. Записує відповідь назад у Bitrix24

Bitrix24 (stage change webhook)
  ↓
Адаптер (валідація, трансформація даних)
  ↓
Логістична система API
  ↓ (async — через callback або polling)
Адаптер (обробка статусу)
  ↓
Bitrix24 REST API (crm.deal.update, crm.timeline.comment.add)

Для надійності — черга (Redis + робочий процес або вбудовані агенти Bitrix). Webhook приймається миттєво, обробка — асинхронно.

Маппінг полів

Типовий набір полів, який потрібно передати в логістику:

Вага та габарити — окрема складність. У Bitrix24 вони зберігаються в картці товару (каталог), але в CRM-угоді вони беруться з crm.product.list за PRODUCT_ID. Якщо інтеграція зі складом або 1С не налаштована, вагові характеристики можуть бути відсутні — потрібен fallback (дефолтні значення за категорією товару або ручне введення).

Трекінг та сповіщення покупців

Після отримання трек-номера вибудовуємо ланцюжок сповіщень. Робот Bitrix24 відправляє SMS або email покупцю (через інтеграцію з сервісом розсилок): «Ваше замовлення передано в доставку, трек-номер: XXX». При кожній зміні статусу — аналогічно. Це знижує навантаження на колл-центр та підвищує задоволеність клієнтів.

Для автоматичного отримання статусів доставки використовуємо два підходи:

• Webhook від перевізника — перевізник сам сповіщає при зміні статусу. Найкращий варіант, але підтримується не всіма.
• Polling — агент Bitrix запитує статус кожні N хвилин за трек-номером. Працює з будь-яким перевізником, але створює навантаження на API.

Обробка виключень

Логістичні API нестабільні та мають специфічні обмеження:

• Ліміти запитів (rate limiting) — витримуємо паузи між запитами, кешуємо довідкові дані (список ПВЗ, тарифи)
• Помилки адреси — перевізник не може визначити зону доставки за адресою. Потрібен UI для ручного коригування зі сповіщенням менеджера
• Заблоковані заявки — якщо логістика заблокувала заявку (некоректні дані), менеджер має бачити це в CRM, а не дізнаватися від покупця

Етапи розробки

Готова інтеграція скорочує час від оформлення угоди до створення заявки на доставку з кількох годин до секунд — і прибирає помилки ручного введення даних отримувача.