Интеграция Битрикс с транспортными компаниями: что работает

Интеграция 1С-Битрикс с транспортной компанией может успешно создать отправление и всё равно дать сбой: покупатель не видит трек-номер, менеджер повторно оформляет заказ, а статус доставки расходится с тем, что показывает перевозчик. Для магазина на 1С-Битрикс: Управление сайтом 24.x главное — выбрать способ обмена под ваши процессы и заранее проверить весь путь заказа, а не только вызов API.

Сначала определите, что именно интегрируете

Под словом «интеграция» обычно скрываются разные задачи: показать способы и цены доставки при оформлении заказа, создать отправление после оплаты, получить накладную, передать трек-номер покупателю и обновлять статусы. Модуль, который решает первую задачу, не обязательно закрывает остальные.

До выбора решения составьте короткую карту процесса:

• какие службы доставки нужны и в каких регионах вы продаёте;
• кто выбирает тариф и точку выдачи — покупатель, менеджер или правило магазина;
• в какой момент создаётся отправление: после заказа, оплаты или подтверждения менеджером;
• кто отвечает за отмену, изменение адреса и повторное оформление;
• где покупатель увидит трек-номер и какие статусы получит.

Это помогает не купить модуль с подходящим названием, но неподходящим сценарием. Отдельно проверьте версию PHP, редакцию и версию Битрикс, совместимость с оформлением заказа и установленными модулями. Для 1С-Битрикс: Управление сайтом 24.x конкретные возможности зависят от версии решения и выбранного модуля; перед установкой сверяйтесь с его документацией.

Три подхода и цена каждого

Варианты различаются не только стоимостью запуска. Важно, сколько контроля вы получаете над данными заказа и кто будет разбирать сбои после релиза.

Не считайте интеграцию готовой по факту успешного ответа API. Уточните, кто выдаёт учётные данные, где хранит их безопасно и кто отвечает за обновление модуля. Если заказов мало, готовое решение может обойтись дешевле разработки. Если служб несколько, а правила доставки сложные, сравните совокупные затраты: лицензия или комиссия, работа команды, разбор ошибок и дальнейшая поддержка.

Рабочий процесс без сюрпризов

1. Разведите заказ, отгрузку и отправление

Не связывайте создание отправления просто с фактом появления заказа. Заказ в Битрикс может быть неоплаченным, отменённым или ещё требовать подтверждения. Определите событие, после которого менеджер или система вправе передать данные перевозчику. Отдельно решите, как повторный запуск обработчика отличит уже созданное отправление от нового.

На тестовом заказе проверьте: отправление появляется в кабинете перевозчика только в нужный момент, а повторная обработка не создаёт второй экземпляр. Если решение не позволяет безопасно повторить операцию, уточните у разработчика модуля, как он предотвращает дубли.

2. Согласуйте состав и формат данных

Перевозчику могут понадобиться контакт получателя, адрес или пункт выдачи, вес и размеры мест, состав вложения и параметры оплаты. Наличие этих сведений в заказе ещё не означает, что модуль передаст их в нужных полях. Особенно часто расходятся единицы измерения и модель упаковки: магазин хранит вес товара, а отправление оформляют на несколько коробок.

Сверьте обязательные поля с документацией конкретной службы и проверьте несколько характерных заказов: один товар, несколько товаров, крупногабаритный товар и получение в пункте выдачи. Успешная проверка — данные в кабинете перевозчика совпадают с заказом и не требуют ручной правки.

3. Не смешивайте статусы заказа и доставки

Статус заказа в магазине отвечает на вопрос, что происходит с продажей; статус перевозчика — где находится отправление. Если каждое обновление доставки напрямую меняет статус заказа, можно случайно пометить заказ завершённым раньше, чем решена оплата или возврат. Составьте таблицу соответствий: какие статусы перевозчика показывать покупателю, какие передавать менеджеру и какие вообще не влияют на статус заказа.

Для проверки используйте тестовую отправку или тестовую среду перевозчика, если она доступна. Пройдите путь от создания накладной до получения. Если статусы должны обновляться автоматически, проверьте не только первый ответ, но и обновление через предусмотренный модулем механизм.

4. Разберите ошибки и повторные попытки

Сетевой тайм-аут не всегда означает, что перевозчик не создал отправление: запрос мог дойти, а ответ потеряться. Поэтому повторять операцию вслепую опасно. Сначала предусмотрите проверку, можно ли найти уже созданное отправление по сохранённому идентификатору или данным заказа; затем определите, кто и как запускает повтор.

В журнале ошибок должны быть дата, внутренний номер заказа, операция и понятное описание сбоя. Не записывайте туда пароли, токены и лишние персональные данные. Проверьте на тестах, что менеджер видит проблему и понимает следующий шаг, а не получает сообщение «ошибка интеграции» без контекста.

Надёжная интеграция — не та, что ни разу не падает. Это та, где сбой не создаёт вторую посылку, не теряет заказ и оставляет понятный след для разбора.

Что выбрать и что ломается

Для одного перевозчика со стандартным процессом начните с готового модуля и проверьте его на тестовых заказах. Если нужна одна точка подключения к нескольким службам, сравните агрегаторы по конкретным функциям: тарифы, пункты выдачи, создание отправлений, отмена и синхронизация статусов. Собственную интеграцию выбирайте, когда типовые решения не поддерживают нужный процесс и у команды есть ресурс сопровождать её после запуска.

В любом варианте отдельно проверьте такие границы:

• Изменили заказ после оформления. Уточните, обновится ли отправление или потребуется отменить его и создать заново.
• Поменялся пункт выдачи. Проверьте, откуда модуль берёт выбранную точку и что увидит менеджер после изменения адреса.
• Перевозчик не ответил. Убедитесь, что заказ не получил ложный статус успеха и повторная обработка не создаёт дубль.
• Обновили модуль или Битрикс. Проверьте обмен на тестовой копии сайта до обновления рабочего магазина.
• Покупатель просит отмену. Сверьте, как отмена заказа отражается у перевозчика и кто подтверждает её результат.

Если тестовой среды нет, проводите проверки на согласованном тестовом заказе и заранее выясните, как отменить созданное отправление. Не тестируйте повторные запросы на реальном заказе покупателя.

Что проверить перед запуском

1. На тестовой копии сайта оформите заказ для каждого нужного типа доставки. Проверка: адрес или пункт выдачи и тариф передались корректно.
2. Создайте отправление в предусмотренный процессом момент. Проверка: оно появилось у перевозчика и связано с верным заказом.
3. Повторите обработку тестового заказа. Проверка: система не создала вторую отправку либо показала безопасный сценарий повтора.
4. Проверьте трек-номер и обновление статуса. Проверка: покупатель и менеджер видят ожидаемую информацию в предусмотренных местах.
5. Имитируйте недоступность сервиса или некорректные данные на тестовой среде. Проверка: ошибка попала в журнал, а менеджер знает, как действовать.

Идемпотентность¹ — свойство операции, при котором повторный запуск не создаёт повторный результат. Для оформления отправлений это защита от дублей при тайм-ауте или повторной обработке заказа.

Что делать дальше

Зафиксируйте карту статусов, момент создания отправления и порядок действий при сбое — затем прогоните сценарии на копии сайта. После запуска следите за долей отправлений с ошибкой, повторными накладными и временем от оплаты до передачи заказа перевозчику. Если какой-то показатель растёт, сначала проверьте журналы и конкретный этап обмена, а не заменяйте модуль наугад. Детали API, доступных статусов и ограничений сверяйте в документации выбранной службы и решения для Битрикс.