Как да свържете данните за проследяване на пратки с OMS: съпоставяне на поръчки и правила за синхронизация
За да свържете данните за проследяване на пратки със система за управление на поръчки (OMS), съпоставете всеки проследяван пакет с вътрешен запис за пратка, след което свържете тази пратка с нейната поръчка и редовете за изпълнение. Получавайте актуализации за проследяването чрез поддържания интерфейс на доставчика, запазвайте оригиналните събития и прилагайте ясни правила за дубликати, закъснели актуализации, статуса на пратката и завършването на поръчката. Не използвайте само номера за проследяване като идентификатор на поръчката и не позволявайте едно събитие за доставка автоматично да приключва поръчка с няколко пакета.
Това ръководство е предназначено за инженери по интеграция и екипи по операции в електронната търговия, които реализират такава връзка. Препоръчителният дизайн разделя наблюденията на превозвача от бизнес решенията: данните за проследяване описват пътуването на пакета, докато OMS определя какво означава това пътуване за изпълнението, комуникацията с клиента и приключването на поръчката.
Определете коя система притежава всеки запис
Преди да изградите API връзка, договорете собствеността с администратора на OMS, екипа по изпълнение и екипа за обслужване на клиенти. В противен случай технически успешната интеграция все пак може да презапише валидни бизнес данни.
- OMS: Притежава поръчките, редовете на поръчките, необходимите количества, анулациите и правилата за приключване на поръчките.
- Система за изпълнение: Притежава създадените от нея записи за пратки или пакети, включително разпределенията при опаковане и назначенията на етикети. Това може да е самата OMS или отделна складова система.
- Доставчик на проследяване: Предоставя наблюдения за проследяването и класификациите на статуси, определени от доставчика.
- Интеграционен слой: Притежава кръстосаните справки на идентификатори, обработката на събития, нормализацията, управлението на повторните опити и одитните записи за синхронизация.
Приемайте тези граници като препоръчителни, а не като предположения за вашия софтуер. Документирайте изключенията. Например, ако складът може да замени етикет за доставка, интеграцията трябва да получи изрична актуализация от тази система, вместо да предполага, че новонаблюдаваният номер заменя стария.
Изградете съпоставянето от поръчка към пакет, преди да синхронизирате статусите
Практическата връзка е поръчка → изпълнение → пакет → назначение за проследяване. Вашата OMS може да използва различни имена или да комбинира някои от тези записи. Запазете връзките, дори ако структурата на базата данни е различна.
Една поръчка може да има няколко изпълнения, а едно изпълнение може да съдържа няколко пакета. Пакетът може също да получи заменено назначение за проследяване или свързан идентификатор за последната миля. Тези идентификатори не трябва да създават допълнителни заявени количества.
| Запис | Препоръчителни полета | Предназначение |
|---|---|---|
| Поръчка | ID на клиент или магазин, неизменяем ID на поръчката в OMS | Разделя търговците и избягва зависимостта от видими номера на поръчки. |
| Изпълнение | ID на изпълнението, ID на поръчката, ID и количества на разпределените редове | Идентифицира закупените артикули, които се изпълняват. |
| Пакет | Вътрешен ID на пакета, ID на изпълнението, разпределения на пакета, когато са налични | Осигурява стабилна идентичност, независима от етикетите за проследяване. |
| Назначение за проследяване | ID на назначението, ID на пакета, акаунт на доставчика, идентификатор на превозвача, номер за проследяване, период на активност | Свързва входящите наблюдения за проследяване с правилния пакет и жизнения цикъл на назначението. |
Съпоставяйте актуализациите чрез съхранена кръстосана справка
Когато се създава пратка, запазете вътрешните ѝ идентификатори, преди да я регистрирате за проследяване. Съхранявайте всеки ID на запис за проследяване, предоставен от доставчика и върнат от документирания процес на регистрация. Ако доставчикът поддържа референция на търговеца, използвайте непрозрачна вътрешна референция и съхранявайте съпоставянето локално.
При входящи актуализации първо разрешете съхранения ID на записа на доставчика в рамките на правилния акаунт на доставчика и клиент. Ако този идентификатор не е наличен, използвайте документираната комбинация от номер за проследяване, самоличност на превозвача, контекст на акаунта и история на назначенията. Приемайте това като стратегия за търсене, а не като гаранция, че комбинацията е глобално уникална.
Не съпоставяйте по име на клиент, имейл адрес или неограничен видим номер на поръчка. Съхранявайте номерата за проследяване като низове, за да се запазят водещите нули. Не премахвайте символи и не променяйте регистъра, освен ако съответният договор с превозвача или доставчика не разрешава такава нормализация.
Ако търсенето не върне съвпадение или върне няколко възможни съвпадения, изолирайте актуализацията за проверка. Неразрешеното събитие е по-безопасно от уверена актуализация на поръчката на грешен клиент.
Обработвайте разделените поръчки, без да измисляте разпределения на пакетите
Да разгледаме примерна поръчка, съдържаща три единици. Пакет A съдържа две единици, а пакет B — една. Доставката на пакет A означава, че има доказателство за доставка на две единици; това не означава, че цялата поръчка е доставена.
Ако системата за изпълнение записва само, че двата пакета принадлежат към едно и също изпълнение, не измисляйте разпределения на ниво единица. Все пак можете да изчислите дали всички необходими пакети са доставени, но отчетността за доставката на ниво артикул трябва да остане недостъпна или изрично неопределена, докато не бъдат налични данни за разпределение.
Свържете API за проследяване чрез устойчив слой за приемане на данни
Използвайте конвейер, който отделя комуникацията с доставчика от записите в OMS:
Създаване на пратка → регистрация за проследяване → входяща актуализация или планирано извличане → устойчиво съхранение на събития → съпоставяне и нормализация → актуализация на OMS → сверяване
При реализация с 17TRACK страницата на продукта Tracking API и официалната API документация са подходящите начални точки. Потвърдете приложимия интерфейс за регистрация, идентификаторите на превозвачите, опциите за доставка на актуализации, изискванията за удостоверяване, дефинициите на статусите и ограниченията на акаунта, преди да реализирате адаптера. Моделът на данните в това ръководство е препоръка за интеграция, а не твърдение, че 17TRACK използва тези имена на полета или предоставя собствен конектор за вашата OMS.
Ако избраният доставчик поддържа webhooks, удостоверявайте входящите заявки чрез документирания му механизъм и устойчиво съхранявайте приетите съобщения, преди да ги потвърдите. Изпълнявайте бавните операции на OMS извън пътя на заявката. Следвайте действителния договор на доставчика за потвърждения и повторни опити, вместо да предполагате конкретно тяло на отговора или изчакване.
Ако е необходимо периодично извличане, съхранявайте напредъка там, където API го поддържа, контролирайте едновременността и спазвайте документираните ограничения за честота. Нито получаването на webhook, нито успешната заявка за извличане доказват, че OMS е актуализирана; записвайте тези резултати отделно.
Определете правила за синхронизация, устойчиви на повторни опити и закъснели събития
1. Направете обработката идемпотентна
Повторната обработка на едно и също наблюдение не трябва да дублира пратка, да увеличава количествата два пъти или да изпраща повторно същото известие до клиента. HTTP не прави произволна POST операция идемпотентна; интеграцията трябва да реализира защита от дубликати. RFC 9110 обяснява идемпотентността на HTTP методите.
Използвайте стабилен ID на събитие от доставчика, когато такъв е документиран и наличен. В противен случай определете отпечатък от ID на назначението и съответните полета на събитието, като времеви печат, статус от източника и местоположение. Документирайте възможността за колизии или променени описания на събитията. Съхранявайте необработеното наблюдение, дори когато не води до друга операция в OMS.
Защитавайте всеки страничен ефект отделно. Например записът на статус в OMS и известието по имейл се нуждаят от собствени контроли за дедупликация. Използвайте транзакционна изходяща опашка или еквивалентен устойчив запис на работа, така че сривът на процеса да не остави прието събитие без планирана актуализация.
2. Съхранявайте отделно времето на събитието и времето на получаването
Времето на настъпване на дадено събитие и времето, когато интеграцията го е получила, отговарят на различни въпроси. Съхранявайте и двете, заедно с оригиналното представяне на времевия печат и всяка предоставена часова отмествка. Не задавайте мълчаливо часовата зона на склада на събитие, чиято часова зона е неизвестна.
Закъсняло сканиране „в транзит“ обикновено трябва да обогати историята, без да заменя по-нов статус „доставено“. Самите времеви печати обаче не са достатъчни: доставчикът може да издаде корекция, а събитията може да имат непълна времева информация. Използвайте документирани полета за последователност или редакция, когато са налични, заедно с изрична политика за корекции.
3. Нормализирайте статусите, без да заличавате подробностите от източника
Създайте малък вътрешен речник, който OMS разбира, например очаква приемане от превозвача, в транзит, предадено за доставка, доставено, изключение и връщане. Съпоставете документираните статуси на доставчика с него. Това са предложени вътрешни категории, а не универсални дефиниции за превозвачите.
Съхранявайте оригиналния код на статуса, описанието, местоположението на събитието, референцията към записа на доставчика и версията на правилото за съпоставяне. Несъпоставена стойност трябва да създава условие за преглед, а не да се задава по подразбиране като доставено или неуспешно. Създаването на етикет не трябва да се приема за доказателство за физическо приемане от превозвача, освен ако събитието от източника изрично не подкрепя това тълкуване.
4. Използвайте правила за преходи, а не проста числова класация
Състоянията на пратките не винаги образуват права линия. Изключение може да бъде последвано от нормален транзит, а опитът за доставка не е доставка. Движението за връщане може да започне след по-ранно събитие за доставка.
- Позволявайте изключение да бъде премахнато, когато последващите доказателства показват възобновено движение.
- Предотвратявайте обикновено историческо сканиране да заменя незабелязано статус „доставено“.
- Позволявайте документирана корекция чрез контролиран път за редакция.
- Проследявайте движението за връщане отделно от завършването на изходящата доставка, когато OMS го поддържа.
- Насочвайте двусмислените или противоречиви доказателства към оперативна опашка.
Версионирайте тези правила. Когато дадено съпоставяне се промени, решете дали да се прилага само към нови събития или историческите записи изискват контролирано преизчисляване.
Изчислявайте статуса на поръчката според необходимите задължения за изпълнение
Статусът на пакета и статусът на поръчката трябва да бъдат отделни полета. Пакет, маркиран като доставен, предоставя доказателство за този пакет; завършването на поръчката зависи от оставащите необходими количества и вашата бизнес политика.
Полезно правило по подразбиране е поръчката да се маркира като напълно доставена само когато всички количества, изискващи доставка, имат валидно доказателство за доставка на ниво пакет и не остават нерешени задължителни разпределения. Изключвайте анулираните количества съгласно правилата за анулация на OMS. Обработвайте цифровите артикули, поръчките за получаване на място и другите задължения без доставка чрез собствени условия за завършване.
Заместващите пратки изискват изрични връзки. Ако изгубен пакет бъде заменен, решете дали заместващият пакет отменя първоначалното задължение за доставка. В противен случай оригиналният пакет може да блокира приключването за неопределено време или и двата пакета да бъдат отчетени за изпълнението. Запишете решението, вместо да го извеждате само от статуса на проследяването.
Поддържайте завършването на доставката отделно от финансовото приключване, допустимостта за възстановяване на сума и разрешаването на спорове. Събитие за доставка от превозвач не трябва автоматично да разрешава възстановяване на сума или да урежда претенция на клиента.
Възстановявайте се от повреди, без да губите одитната следа
Повтаряйте преходните неуспешни операции с ограничено експоненциално изчакване и всички документирани указания за повторни опити. Разделяйте временните проблеми с връзката от невалидните идентификатори, изтеклите идентификационни данни, грешките в разрешенията и несъвместимостите на схемата. Последните изискват коригиращи действия, а не безкрайни повторни опити.
Поддържайте опашка за неуспешна работа, съдържаща засегнатия клиент, пакета, референцията на събитието, опитната операция, класификацията на грешката и следващото действие. Регистрирайте достатъчно контекст за разследване, без да копирате ненужни клиентски данни или идентификационни данни в логовете.
Изпълнявайте сверяване в допълнение към нормалния път за актуализация. Преглеждайте активните пратки с остаряла информация за проследяване, приетите събития, чиито записи в OMS са неуспешни, несъпоставените наблюдения и разликите между изчисленото от интеграцията състояние и OMS. Избирайте честотата на преглед според ангажиментите за доставка, ограниченията на API и оперативния риск, вместо да прилагате произволен универсален график.
Определете отговорностите: инженерният екип обработва грешките при приемане и запис; операциите по изпълнение разрешават липсващите връзки с пакети; обслужването на клиенти преглежда изключенията, изискващи комуникация с клиента. Опашка без отговорен собственик е само място за съхранение.
Тествайте съпоставянето и бизнес правилата преди старта
Използвайте контролирани тестови данни и ограничено внедряване в продукция. Тествайте следните случаи както спрямо историята на събитията, така и спрямо получения запис в OMS:
- Поръчка с един пакет преминава нормално до доставка.
- Разделена поръчка има един доставен пакет и един, който все още се движи.
- Едно и също събитие се получава многократно без дублирани странични ефекти.
- По-старо транзитно сканиране пристига след доставката.
- Неизвестен превозвач или статус попада в опашката за преглед.
- Етикетът е заменен, без да се създава друго задължение за изпълнение.
- Заместваща пратка отменя оригиналния пакет съгласно одобрено правило.
- OMS не е достъпна, след като събитието е прието.
- Процесът се рестартира между записа в OMS и потвърждението му.
- Един и същ видим номер на поръчка съществува в два магазина без съпоставяне между клиенти.
Стартирайте, когато всяко прието събитие има проследим резултат от обработката, двусмислените съвпадения не могат автоматично да актуализират поръчки и операторите могат безопасно да повторят неуспешната работа. Това са по-полезни критерии за приемане от простото доказване, че API заявката е успешна.
Често задавани въпроси
Мога ли да свържа номерата за проследяване директно с поръчките?
При строго работен процес с един пакет директната връзка може първоначално да е достатъчна. Все пак използвайте вътрешна идентичност на пратката между поръчката и назначението за проследяване. Тя осигурява път за миграция при разделени пратки, повторно етикетиране и замени, без да променя значението на записа на поръчката.
Трябва ли интеграцията да използва webhooks или периодично извличане?
Използвайте механизма за доставка, поддържан от доставчика и съвместим с вашата инфраструктура. Webhooks могат да намалят повторното извличане, докато периодичното извличане може да поддържа работни процеси и сверяване, базирани на извличане, когато е налично. Нито един от двата подхода не отменя нуждата от устойчиво съхранение, обработка на дубликати и възстановяване.
Какво трябва да се случи, когато събитие за проследяване няма съвпадаща поръчка?
Съхранете го в опашка за несъпоставени събития и проверете регистрационния запис, контекста на клиента, самоличността на превозвача и момента на създаване на пратката. Не създавайте автоматично поръчка и не прикрепяйте събитието към правдоподобен клиент. Повторете обработката, след като съпоставянето бъде коригирано.
Известията за доставка трябва ли да идват от OMS или от системата за проследяване?
Изберете един собственик за всеки тип известие и задействащо събитие. Ако две системи могат да изпратят едно и също съобщение, деактивирайте единия път или споделете устойчив регистър на известията. Решете също дали съобщението се отнася до един пакет или до цялата поръчка, особено при разделено изпълнение.
Означава ли статусът „изключение“, че поръчката е неуспешна?
Не. Изключението е наблюдение, което изисква тълкуване, а не непременно постоянен резултат. Запазете причината, наблюдавайте последващите събития и използвайте политиката си за ескалация, за да решите кога операциите трябва да се намесят.
Източници
- 17TRACK Tracking API — официален продуктов справочник за началната точка на API интеграцията.
- 17TRACK API documentation — справочник за реализация на специфичния за доставчика договор; проверете приложимите интерфейси и изискванията за акаунта преди внедряване.
- RFC 9110, Section 9.2.2: Idempotent Methods — HTTP семантика, подкрепяща разграничението между идемпотентност на метода и защита на ниво приложение от дубликати.


