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

Коли менеджер закриває угоду в CRM, а логісти вручну переносять дані в TMS, втрачається до 30 хвилин на кожну заявку — а на місяць це сотні годин операційного часу?

Помилки ручного введення (неправильна адреса, невірна вага) призводять до пересортування та повторної доставки, що спричиняє додаткові витрати. Ми розробляємо інтеграцію Бітрікс24 з вашою логістичною системою — від створення заявки до трекінгу та повідомлень. Заявка формується автоматично при зміні стадії угоди, дані отримувача підтягуються з контакту, товари — з угоди. Час на обробку скорочується з годин до секунд, а кількість помилок — до нуля. Під ключ, з гарантією стабільної роботи та значною економією часу відділу доставки. Економія від впровадження може бути значною, особливо при інтеграції з кількома перевізниками. Наше рішення автоматизації доставки охоплює всі ключові процеси: від заявки до повернення.

Які логістичні системи та 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. Інтеграція складніша через застарілі протоколи.

За даними документації СДЭК API, версія v2 обробляє до 100 запитів на хвилину з середнім часом відповіді 1.5 секунди.

Чому асинхронна обробка критична для інтеграції?

Логістичні API нестабільні: ліміти запитів, таймаути, недоступність. Тому ми будуємо асинхронну чергу (Redis + вбудовані агенти Бітрікс). Webhook від Бітрікс24 приймається миттєво, а виклик логістичного API та оновлення статусів виконуються асинхронно. Це в 2-3 рази надійніше синхронного підходу і не блокує роботу менеджерів. Наприклад, при таймауті в 30 секунд синхронний запит заблокує інтерфейс, а асинхронний — просто спробує знову через 30 секунд.

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

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

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

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

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

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

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

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

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

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

Приклад обробки webhook на PHP:

function handleBitrixWebhook($event) { $dealId = $event['data']['FIELDS']['ID']; $deal = CRest::call('crm.deal.get', ['id' => $dealId]); $address = $deal['UF_DELIVERY_ADDRESS']; $phone = $deal['UF_DELIVERY_PHONE']; // Call CDEK API $cdek = new CdekApiClient(); $order = $cdek->createOrder([ 'recipient' => ['name' => $deal['CONTACT_NAME'], 'phone' => $phone], 'address' => $address, 'items' => $deal['PRODUCTS'] ]); CRest::call('crm.deal.update', [ 'id' => $dealId, 'fields' => ['UF_CDEK_ORDER_ID' => $order['uuid']] ]); } 

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

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

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

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

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

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

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

Що робити при збоях логістичного API?

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

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

Для обробки винятків використовуємо чергу з повторними спробами (експоненційна затримка до 5 разів: 1, 2, 4, 8, 16 хвилин) та повідомлення в CRM. Якщо після всіх ретраїв API недоступний, створюється задача оператору з повним контекстом помилки.

Що входить в роботу

• Аналіз API ваших логістичних систем та вибір сценаріїв
• Розробка адаптера з асинхронною чергою та повторними спробами
• Налаштування полів угоди, смарт-процесів та бізнес-процесів (Bizproc) Бітрікс24 для автоматичної логістики
• Створення віджета вибору ПВЗ (якщо потрібно)
• Автоматичні сповіщення покупців за статусами через SMS та email
• Тестування на реальних заявках в тестовому середовищі
• Технічна документація та навчання співробітників
• Гарантія на інтеграцію — 6 місяців після здачі

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

Готова інтеграція скорочує час від оформлення угоди до створення заявки на доставку з кількох годин до секунд — і прибирає помилки ручного введення даних отримувача. Замовте інтеграцію — отримайте працююче рішення з гарантією 6 місяців. Зв'яжіться з нами для оцінки вашого проекту: ми підберемо оптимальне рішення під ключ.