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

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

Логистика — одно из узких мест в компаниях, где менеджеры по продажам и отдел доставки работают в разных системах. Менеджер закрыл сделку в CRM, передал данные в Excel или по телефону, логисты создали заявку вручную в своей системе — и цепочка разорвана. Интеграция Битрикс24 с 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. Интеграция сложнее из-за устаревших протоколов.

Сценарии интеграции

Сделка → заявка на доставку. Сделка в Битрикс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)

Для надёжности — очередь (Redis + рабочий процесс или встроенные агенты Битрикс). Webhook принимается мгновенно, обработка — асинхронно.

Маппинг полей

Типичный набор полей, который нужно передать в логистику:

Вес и габариты — отдельная сложность. В Битрикс24 они хранятся в карточке товара (каталог), но в CRM-сделке они берутся из crm.product.list по PRODUCT_ID. Если интеграция со складом или 1С не настроена, весовые характеристики могут отсутствовать — нужен fallback (дефолтные значения по категории товара или ручной ввод).

Трекинг и уведомления покупателям

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

Для автоматического получения статусов доставки используем два подхода:

• Webhook от перевозчика — перевозчик сам уведомляет при изменении статуса. Лучший вариант, но поддерживается не всеми.
• Polling — агент Битрикс запрашивает статус каждые N минут по трек-номеру. Работает с любым перевозчиком, создаёт нагрузку на API.

Обработка исключений

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

• Лимиты запросов (rate limiting) — выдерживаем паузы между запросами, кешируем справочные данные (список ПВЗ, тарифы)
• Ошибки адреса — перевозчик не может определить зону доставки по адресу. Нужен UI для ручной корректировки с уведомлением менеджера
• Заблокированные заявки — если логистика заблокировала заявку (некорректные данные), менеджер должен видеть это в CRM, а не узнавать от покупателя

Этапы разработки

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