Как подключить данные отслеживания отправлений к Oms: сопоставление заказов и правила синхронизации
Чтобы подключить данные отслеживания отправлений к системе управления заказами (OMS), сопоставьте каждую отслеживаемую посылку с внутренней записью об отправлении, а затем свяжите это отправление с заказом и его строками выполнения. Получайте обновления отслеживания через поддерживаемый интерфейс провайдера, сохраняйте исходные события и применяйте явные правила для дубликатов, запоздалых обновлений, статуса отправления и завершения заказа. Не используйте только трек-номер в качестве идентификатора заказа и не позволяйте одному событию доставки автоматически закрывать заказ, состоящий из нескольких посылок.

Это руководство предназначено для инженеров по интеграции и команд, отвечающих за операции в электронной коммерции, которые реализуют такое подключение. Рекомендуемая архитектура отделяет наблюдения перевозчика от бизнес-решений: данные отслеживания описывают путь посылки, а OMS определяет, что этот путь означает для выполнения заказа, коммуникации с клиентом и закрытия заказа.
Определите, какая система владеет каждой записью
До создания API-подключения согласуйте права владения с администратором OMS, командой выполнения заказов и службой поддержки клиентов. В противном случае даже технически успешная интеграция может перезаписывать корректные бизнес-данные.
- OMS: отвечает за заказы, строки заказов, требуемые количества, отмены и правила завершения заказов.
- Система выполнения заказов: отвечает за создаваемые ею записи об отправлениях или посылках, включая распределение при упаковке и назначение этикеток. Это может быть сама OMS или отдельная складская система.
- Провайдер отслеживания: предоставляет данные наблюдений за отправлением и классификации статусов, определенные провайдером.
- Интеграционный слой: отвечает за перекрестные ссылки идентификаторов, обработку событий, нормализацию, повторные попытки и записи аудита синхронизации.
Рассматривайте эти границы как рекомендуемые, а не как предположения о вашем программном обеспечении. Документируйте исключения. Например, если склад может заменить транспортную этикетку, интеграции требуется явное обновление от этой системы, а не догадка о том, что недавно обнаруженный номер заменяет старый.
Создайте сопоставление заказа с посылкой до синхронизации статусов
Практическая связь выглядит так: заказ → выполнение → посылка → назначение отслеживания. В вашей OMS могут использоваться другие названия или некоторые из этих записей могут быть объединены. Сохраняйте связи, даже если структура базы данных отличается.
Заказ может включать несколько выполнений, а выполнение — несколько посылок. Посылке также может быть назначен новый трек-номер или связанный идентификатор доставки на последней миле. Эти идентификаторы не должны создавать дополнительные заказанные количества.
| Запись | Рекомендуемые поля | Назначение |
|---|---|---|
| Заказ | Идентификатор арендатора или магазина, неизменяемый идентификатор заказа в OMS | Разделяет продавцов и исключает зависимость от отображаемых номеров заказов. |
| Выполнение | Идентификатор выполнения, идентификатор заказа, идентификаторы строк и количества, распределенные для выполнения | Определяет, какие приобретенные товары выполняются. |
| Посылка | Внутренний идентификатор посылки, идентификатор выполнения, распределение товаров по посылке, если доступно | Обеспечивает стабильную идентичность независимо от транспортных этикеток. |
| Назначение отслеживания | Идентификатор назначения, идентификатор посылки, учетная запись провайдера, идентификатор перевозчика, трек-номер, период активности | Связывает входящие наблюдения отслеживания с нужной посылкой и жизненным циклом назначения. |
Сопоставляйте обновления через сохраненную перекрестную ссылку
При создании отправления сохраните его внутренние идентификаторы до регистрации отправления для отслеживания. Сохраните любой идентификатор записи отслеживания, выданный провайдером и возвращенный документированным процессом регистрации. Если провайдер поддерживает ссылку продавца, используйте непрозрачную внутреннюю ссылку и храните сопоставление локально.
Для входящих обновлений сначала найдите сохраненный идентификатор записи провайдера в правильной учетной записи провайдера и у нужного арендатора. Если этот идентификатор недоступен, используйте документированную комбинацию трек-номера, идентификатора перевозчика, контекста учетной записи и истории назначений. Рассматривайте это как стратегию поиска, а не как гарантию глобальной уникальности комбинации.
Не выполняйте сопоставление по имени клиента, адресу электронной почты или неограниченному отображаемому номеру заказа. Храните трек-номера как строки, чтобы сохранить начальные нули. Не удаляйте символы и не изменяйте регистр, если соответствующий договор с перевозчиком или провайдером не разрешает такую нормализацию.
Если поиск не возвращает совпадений или возвращает несколько возможных совпадений, поместите обновление в карантин для расследования. Неразрешенное событие безопаснее, чем уверенное обновление заказа неправильного клиента.
Обрабатывайте разделенные заказы, не придумывая распределение товаров по посылкам
Рассмотрим пример заказа из трех единиц. Посылка A содержит две единицы, а посылка B — одну. Доставка посылки A означает, что имеются подтверждения доставки двух единиц; это не означает, что доставлен весь заказ.
Если система выполнения фиксирует только то, что обе посылки относятся к одному выполнению, не придумывайте распределение на уровне единиц. Вы по-прежнему можете определить, доставлены ли все обязательные посылки, но отчетность о доставке на уровне товаров должна оставаться недоступной или явно неопределенной, пока не появятся данные о распределении.
Подключите API отслеживания через надежный слой приема данных
Используйте конвейер, который отделяет взаимодействие с провайдером от записи в OMS:
Создание отправления → регистрация отслеживания → входящее обновление или плановое получение → надежное сохранение события → сопоставление и нормализация → обновление OMS → сверка
Для реализации на базе 17TRACK отправной точкой являются страница продукта Tracking API и официальная документация API. До реализации адаптера подтвердите используемый интерфейс регистрации, идентификаторы перевозчиков, варианты доставки обновлений, требования к аутентификации, определения статусов и ограничения учетной записи. Модель данных в этом руководстве является рекомендацией по интеграции, а не утверждением, что 17TRACK использует именно эти имена полей или предоставляет нативный коннектор для вашей OMS.
Если выбранный провайдер поддерживает вебхуки, аутентифицируйте входящие запросы с помощью документированного механизма и надежно сохраняйте принятые сообщения до их подтверждения. Выполняйте медленные операции OMS вне пути обработки запроса. Следуйте фактическому договору провайдера о подтверждениях и повторных попытках, не предполагая конкретное тело ответа или тайм-аут.
Если требуется опрос, сохраняйте прогресс получения там, где это поддерживается API, контролируйте параллелизм и соблюдайте документированные ограничения частоты запросов. Ни получение вебхука, ни успешный запрос опроса не доказывают, что OMS была обновлена; фиксируйте эти результаты отдельно.
Определите правила синхронизации, устойчивые к повторным попыткам и запоздалым событиям
1. Сделайте обработку идемпотентной
Повторная обработка одного и того же наблюдения не должна дублировать отправление, дважды увеличивать количества или повторно отправлять одно и то же уведомление клиенту. HTTP не делает произвольную операцию POST идемпотентной; интеграция должна реализовать защиту от дубликатов. RFC 9110 описывает идемпотентность методов HTTP.
Используйте стабильный идентификатор события провайдера, если он документирован и доступен. В противном случае определите отпечаток на основе идентификатора назначения и соответствующих полей события, например времени события, исходного статуса и местоположения. Документируйте возможность коллизий или изменения описаний событий. Сохраняйте исходное наблюдение, даже если оно не приводит к дополнительному действию в OMS.
Защищайте каждый побочный эффект отдельно. Например, запись статуса в OMS и уведомление по электронной почте должны иметь собственные механизмы устранения дубликатов. Используйте транзакционный исходящий журнал или эквивалентную надежную запись задания, чтобы сбой процесса не оставлял принятое событие без запланированного обновления.
2. Храните время события и время получения отдельно
Время возникновения события и время его получения интеграцией отвечают на разные вопросы. Храните оба значения, а также исходное представление временной метки и указанный сдвиг часового пояса. Не назначайте незаметно часовой пояс склада событию, для которого часовой пояс неизвестен.
Поздно поступившее сканирование статуса «в пути» обычно должно дополнять историю, не заменяя более новый статус «доставлено». Однако одних временных меток недостаточно: провайдер может выпустить исправление, а события могут содержать неполные сведения о времени. Используйте документированные поля последовательности или версии, если они доступны, а также явную политику исправлений.
3. Нормализуйте статусы, не стирая сведения об источнике
Создайте небольшой внутренний словарь, понятный OMS, например: ожидание приема перевозчиком, в пути, передано курьеру для доставки, доставлено, исключение и возврат. Сопоставьте с ним документированные статусы провайдера. Это рекомендуемые внутренние категории, а не универсальные определения перевозчиков.
Храните исходный код статуса, описание, местоположение события, ссылку на запись провайдера и версию правила сопоставления. Несопоставленное значение должно создавать условие, требующее проверки, а не по умолчанию преобразовываться в «доставлено» или «не выполнено». Создание этикетки не следует считать доказательством фактического приема отправления перевозчиком, если исходное событие явно не поддерживает такую интерпретацию.
4. Используйте правила переходов, а не простое числовое ранжирование
Состояния отправления не всегда образуют прямую последовательность. За исключением может последовать обычное движение, а попытка доставки не является доставкой. Возвратное перемещение может начаться после более раннего события доставки.
- Разрешайте устранение исключения, если последующие данные подтверждают возобновление движения.
- Не позволяйте обычному историческому сканированию незаметно заменять статус «доставлено».
- Разрешайте документированное исправление через контролируемый путь пересмотра.
- Отслеживайте возвратное перемещение отдельно от завершения исходящей доставки, если OMS это поддерживает.
- Направляйте неоднозначные или противоречивые данные в операционную очередь.
Версионируйте эти правила. При изменении сопоставления решите, применяется ли оно только к новым событиям или исторические записи требуют контролируемого перерасчета.
Рассчитывайте статус заказа на основе обязательств по выполнению
Статусы посылки и заказа должны быть отдельными полями. Посылка со статусом «доставлено» предоставляет подтверждение для этой посылки; завершение заказа зависит от оставшихся требуемых количеств и вашей бизнес-политики.
Полезное правило по умолчанию — отмечать заказ как полностью доставленный только тогда, когда для всех требуемых к доставке количеств имеются действительные подтверждения доставки на уровне посылок и не осталось неразрешенных обязательных распределений. Исключайте отмененные количества в соответствии с правилами отмены OMS. Обрабатывайте цифровые товары, заказы на самовывоз и другие обязательства, не связанные с доставкой, через собственные условия завершения.
Для заменяющих отправлений требуются явные связи. Если потерянная посылка заменена, определите, отменяет ли заменяющая отправка первоначальное обязательство по доставке. В противном случае исходная посылка может бесконечно блокировать завершение или обе посылки могут засчитываться в выполнение. Фиксируйте это решение, а не выводите его только из статуса отслеживания.
Отделяйте завершение доставки от финансового закрытия, права на возврат средств и разрешения споров. Событие доставки от перевозчика не должно автоматически разрешать возврат средств или закрывать претензию клиента.
Восстанавливайтесь после сбоев, не теряя аудиторский след
Повторяйте временные сбои с ограниченной задержкой и с учетом документированных рекомендаций по повторным попыткам. Отделяйте временные ошибки подключения от недействительных идентификаторов, истекших учетных данных, ошибок разрешений и несовместимости схем. Последние требуют корректирующих действий, а не бесконечных повторов.
Поддерживайте очередь невыполненных заданий, содержащую затронутого арендатора, посылку, ссылку на событие, выполненную операцию, классификацию ошибки и следующее действие. Записывайте достаточно контекста для расследования, не помещая в журналы лишние данные клиентов или учетные данные.
Выполняйте сверку в дополнение к обычному пути обновления. Проверяйте активные отправления с устаревшей информацией отслеживания, принятые события, для которых запись в OMS завершилась ошибкой, несопоставленные наблюдения и различия между вычисленным интеграцией состоянием и состоянием OMS. Выбирайте частоту проверок с учетом обязательств по доставке, ограничений API и операционного риска, а не применяйте произвольный единый график.
Назначьте ответственных: инженерная команда обрабатывает ошибки приема и записи; операционная команда выполнения заказов устраняет отсутствующие связи с посылками; служба поддержки рассматривает исключения, требующие коммуникации с клиентом. Очередь без ответственного владельца — это лишь место хранения.
Проверьте сопоставление и бизнес-правила до запуска
Используйте контролируемые тестовые данные и ограниченный запуск в рабочей среде. Проверьте следующие случаи как по истории событий, так и по итоговой записи в OMS:
- Заказ с одной посылкой штатно проходит путь до доставки.
- В разделенном заказе одна посылка доставлена, а другая все еще находится в пути.
- Одно и то же событие принимается повторно без дублирования побочных эффектов.
- Более старое сканирование движения поступает после доставки.
- Неизвестный перевозчик или статус попадает в очередь проверки.
- Этикетка заменяется без создания дополнительного обязательства по выполнению.
- Заменяющее отправление подменяет исходную посылку согласно утвержденному правилу.
- OMS недоступна после принятия события.
- Процесс перезапускается между записью в OMS и подтверждением этой записи.
- Один и тот же отображаемый номер заказа существует в двух магазинах без сопоставления между арендаторами.
Запускайте решение, когда для каждого принятого события существует отслеживаемый результат обработки, неоднозначные совпадения не могут автоматически обновлять заказы, а операторы могут безопасно повторно запускать неудачные задания. Это более полезные критерии приемки, чем простая демонстрация успешного API-запроса.
Часто задаваемые вопросы
Можно ли напрямую связать трек-номера с заказами?
Для строго однопосылочного процесса прямой связи на начальном этапе может быть достаточно. Тем не менее используйте внутренний идентификатор отправления между заказом и назначением отслеживания. Это обеспечит путь миграции для разделенных отправлений, перемаркировки и замен без изменения смысла записи заказа.
Следует ли интеграции использовать вебхуки или опрос?
Используйте механизм доставки, который поддерживается провайдером и совместим с вашей инфраструктурой. Вебхуки могут сократить повторное получение данных, а опрос может поддерживать процессы на основе получения и сверку, если они доступны. Ни один из подходов не отменяет необходимости надежного хранения, обработки дубликатов и восстановления.
Что делать, если событие отслеживания не соответствует ни одному заказу?
Сохраните его в очереди несопоставленных событий и проверьте запись регистрации, контекст арендатора, идентификатор перевозчика и время создания отправления. Не создавайте заказ и не прикрепляйте событие автоматически к предположительно подходящему клиенту. Повторно обработайте его после исправления сопоставления.
Уведомления о доставке должны отправляться из OMS или системы отслеживания?
Выберите одного владельца для каждого типа уведомления и триггера. Если две системы могут отправить одно и то же сообщение, отключите один путь или используйте общий надежный журнал уведомлений. Также определите, относится ли сообщение к одной посылке или ко всему заказу, особенно при разделенном выполнении.
Означает ли статус исключения, что заказ не выполнен?
Нет. Исключение — это наблюдение, требующее интерпретации, а не обязательно окончательный результат. Сохраняйте причину, отслеживайте последующие события и используйте политику эскалации, чтобы определить, когда должна вмешаться операционная команда.
Источники
- 17TRACK Tracking API — официальная информация о продукте и отправная точка для интеграции API.
- Документация API 17TRACK — справочник по реализации контракта конкретного провайдера; перед развертыванием проверьте применимые интерфейсы и требования к учетной записи.
- RFC 9110, раздел 9.2.2: идемпотентные методы — семантика HTTP, поддерживающая различие между идемпотентностью метода и защитой приложения от дубликатов.


