Як підключити дані відстеження відправлень до 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 і повідомлення електронною поштою потребують власних засобів дедуплікації. Використовуйте транзакційний outbox або еквівалентний надійний запис роботи, щоб збій процесу не залишив прийняту подію без запланованого оновлення.
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, що підтверджує відмінність між ідемпотентністю методу та захистом від дублікатів на рівні застосунку.


