Ako pripojiť údaje o sledovaní zásielok k OMS: mapovanie objednávok a pravidlá synchronizácie
Ak chcete pripojiť údaje o sledovaní zásielok k systému správy objednávok (OMS), priraďte každý sledovaný balík k internému záznamu zásielky a potom túto zásielku prepojte s jej objednávkou a riadkami plnenia. Aktualizácie sledovania prijímajte prostredníctvom podporovaného rozhrania poskytovateľa, zachovajte pôvodné udalosti a uplatňujte explicitné pravidlá pre duplicity, oneskorené aktualizácie, stav zásielky a dokončenie objednávky. Nepoužívajte samotné sledovacie číslo ako identifikátor objednávky ani nedovoľte, aby jediná udalosť doručenia automaticky uzavrela objednávku s viacerými balíkmi.
Táto príručka je určená integračným inžinierom a tímom prevádzky elektronického obchodu, ktorí toto prepojenie implementujú. Odporúčaný návrh oddeľuje pozorovania prepravcu od obchodných rozhodnutí: údaje o sledovaní opisujú cestu balíka, zatiaľ čo OMS rozhoduje, čo táto cesta znamená pre plnenie, komunikáciu so zákazníkom a uzavretie objednávky.
Určite, ktorý systém vlastní jednotlivé záznamy
Pred vytvorením API prepojenia sa dohodnite na vlastníctve so správcom OMS, tímom plnenia a tímom zákazníckych služieb. Inak môže technicky úspešná integrácia stále prepísať platné obchodné údaje.
- OMS: Vlastní objednávky, riadky objednávok, požadované množstvá, zrušenia a pravidlá dokončenia objednávok.
- Systém plnenia: Vlastní záznamy zásielok alebo balíkov, ktoré vytvára, vrátane pridelenia balenia a priradenia štítkov. Môže ísť o samotný OMS alebo samostatný skladový systém.
- Poskytovateľ sledovania: Poskytuje pozorovania sledovania a klasifikácie stavov definované poskytovateľom.
- Integračná vrstva: Vlastní krížové odkazy identifikátorov, spracovanie udalostí, normalizáciu, spracovanie opakovaní a auditné záznamy synchronizácie.
Považujte tieto hranice za odporúčania, nie za predpoklady o vašom softvéri. Zdokumentujte výnimky. Ak napríklad sklad môže nahradiť prepravný štítok, integrácia potrebuje explicitnú aktualizáciu z tohto systému namiesto hádania, že novo zaznamenané číslo nahrádza staré.
Vytvorte mapovanie objednávky na balík ešte pred synchronizáciou stavov
Praktický vzťah je objednávka → plnenie → balík → priradenie sledovania. Váš OMS môže používať iné názvy alebo niektoré z týchto záznamov kombinovať. Zachovajte tieto vzťahy, aj keď sa štruktúra databázy líši.
Objednávka môže mať viacero plnení a plnenie môže obsahovať viacero balíkov. Balík môže tiež získať náhradné priradenie sledovania alebo prepojený identifikátor doručenia na poslednej míli. Tieto identifikátory nesmú vytvárať ďalšie objednané množstvá.
| Záznam | Odporúčané polia | Účel |
|---|---|---|
| Objednávka | ID tenanta alebo obchodu, nemenné ID objednávky OMS | Oddeľuje obchodníkov a zabraňuje závislosti od zobrazovaných čísel objednávok. |
| Plnenie | ID plnenia, ID objednávky, ID a množstvá pridelených riadkov | Identifikuje zakúpené položky, ktoré sa plnia. |
| Balík | Interné ID balíka, ID plnenia, pridelenie položiek balíka, ak je dostupné | Poskytuje stabilnú identitu nezávislú od sledovacích štítkov. |
| Priradenie sledovania | ID priradenia, ID balíka, účet poskytovateľa, identifikátor prepravcu, sledovacie číslo, obdobie platnosti | Prepája prichádzajúce pozorovania sledovania so správnym balíkom a životným cyklom priradenia. |
Priraďujte aktualizácie prostredníctvom uloženého krížového odkazu
Pri vytvorení zásielky uložte jej interné ID ešte pred registráciou na sledovanie. Uložte každé ID záznamu sledovania pridelené poskytovateľom, ktoré vráti zdokumentovaný registračný proces. Ak poskytovateľ podporuje referenciu obchodníka, použite nepriehľadnú internú referenciu a mapovanie uchovávajte lokálne.
Pri prichádzajúcich aktualizáciách najprv vyhľadajte uložené ID záznamu poskytovateľa v správnom účte poskytovateľa a tenantovi. Ak tento identifikátor nie je dostupný, použite zdokumentovanú kombináciu sledovacieho čísla, identity prepravcu, kontextu účtu a histórie priradení. Považujte to za stratégiu vyhľadávania, nie za záruku, že táto kombinácia je globálne jedinečná.
Nepriraďujte podľa mena zákazníka, e-mailovej adresy ani nezúženého zobrazovaného čísla objednávky. Sledovacie čísla uchovávajte ako reťazce, aby sa zachovali úvodné nuly. Neodstraňujte znaky ani nemeňte veľkosť písmen, pokiaľ to príslušná zmluva s prepravcom alebo poskytovateľom nepovoľuje.
Ak vyhľadávanie nevráti žiadnu zhodu alebo vráti viacero možných zhôd, umiestnite aktualizáciu do karantény na preskúmanie. Nevyriešená udalosť je bezpečnejšia než sebavedomá aktualizácia objednávky nesprávneho zákazníka.
Spracúvajte rozdelené objednávky bez vymýšľania pridelenia balíkov
Zvážte príklad objednávky obsahujúcej tri jednotky. Balík A nesie dve jednotky a balík B jednu. Doručenie balíka A znamená, že existuje dôkaz o doručení dvoch jednotiek; neznamená to doručenie celej objednávky.
Ak systém plnenia zaznamenáva iba to, že oba balíky patria k rovnakému plneniu, nevymýšľajte pridelenie na úrovni jednotiek. Stále môžete vypočítať, či boli doručené všetky požadované balíky, ale vykazovanie doručenia na úrovni položiek by malo zostať nedostupné alebo výslovne neisté, kým nebudú k dispozícii údaje o pridelení.
Pripojte API sledovania prostredníctvom odolnej prijímacej vrstvy
Použite kanál, ktorý oddeľuje komunikáciu s poskytovateľom od zápisov do OMS:
Vytvorenie zásielky → registrácia sledovania → prichádzajúca aktualizácia alebo plánované získanie → trvalé uloženie udalosti → mapovanie a normalizácia → aktualizácia OMS → zosúladenie
Pre implementáciu 17TRACK sú relevantným východiskom produktová stránka Tracking API a oficiálna dokumentácia API. Pred implementáciou adaptéra overte príslušné registračné rozhranie, identifikátory prepravcov, možnosti doručovania aktualizácií, požiadavky na autentifikáciu, definície stavov a limity účtu. Dátový model v tejto príručke je odporúčaním pre integráciu, nie tvrdením, že 17TRACK používa tieto názvy polí alebo poskytuje natívny konektor pre váš OMS.
Ak vybraný poskytovateľ podporuje webhooky, autentifikujte prichádzajúce požiadavky pomocou jeho zdokumentovaného mechanizmu a prijaté správy trvalo uložte ešte pred potvrdením ich prijatia. Pomalé operácie OMS ponechajte mimo cesty požiadavky. Riaďte sa skutočnou zmluvou poskytovateľa o potvrdzovaní a opakovaní, namiesto predpokladu konkrétneho tela odpovede alebo časového limitu.
Ak je potrebné dotazovanie, ukladajte priebeh získavania tam, kde to API podporuje, kontrolujte súbežnosť a dodržiavajte zdokumentované limity frekvencie. Prijatie webhooku ani úspešná požiadavka na dotazovanie nedokazujú, že OMS bol aktualizovaný; tieto výsledky zaznamenávajte oddelene.
Definujte pravidlá synchronizácie, ktoré zvládnu opakovania a oneskorené udalosti
1. Zabezpečte idempotentné spracovanie
Spracovanie toho istého pozorovania dvakrát by nemalo duplikovať zásielku, dvakrát zvýšiť množstvá ani znova odoslať rovnaké upozornenie zákazníkovi. HTTP nerobí ľubovoľnú operáciu POST idempotentnou; integrácia musí implementovať ochranu proti duplicitám. RFC 9110 vysvetľuje idempotenciu metód HTTP.
Ak je zdokumentované a dostupné, použite stabilné ID udalosti poskytovateľa. V opačnom prípade definujte odtlačok z ID priradenia a relevantných polí udalosti, ako sú časová pečiatka udalosti, zdrojový stav a miesto. Zdokumentujte možnosť kolízií alebo zmien opisov udalostí. Pôvodné pozorovanie uchovajte aj vtedy, keď nevedie k ďalšej akcii v OMS.
Každý vedľajší účinok chráňte samostatne. Napríklad zápis stavu OMS a e-mailové upozornenie potrebujú vlastné kontroly deduplikácie. Použite transakčný outbox alebo ekvivalentný trvalý pracovný záznam, aby pád procesu nemohol zanechať prijatú udalosť bez naplánovanej aktualizácie.
2. Čas udalosti a čas prijatia ukladajte oddelene
Čas výskytu udalosti a čas, keď ju vaša integrácia prijala, odpovedajú na odlišné otázky. Uložte oba časy spolu s pôvodnou reprezentáciou časovej pečiatky a prípadným poskytnutým posunom časového pásma. Udalosti s neznámym časovým pásmom nepriraďujte potichu k časovému pásmu skladu.
Oneskorené skenovanie počas prepravy by malo za normálnych okolností obohatiť históriu bez nahradenia novšieho stavu doručenia. Samotné časové pečiatky však nestačia: poskytovateľ môže vydať opravu a udalosti môžu obsahovať neúplné časové údaje. Ak sú dostupné, používajte zdokumentované sekvenčné alebo revízne polia spolu s explicitnou politikou opráv.
3. Normalizujte stavy bez vymazania podrobností zdroja
Vytvorte malú internú slovnú zásobu, ktorej OMS rozumie, napríklad čaká na prijatie prepravcom, v preprave, doručovanie, doručené, výnimka a vracia sa. Namapujte do nej zdokumentované stavy poskytovateľa. Ide o navrhované interné kategórie, nie univerzálne definície prepravcov.
Ukladajte pôvodný kód stavu, opis, miesto udalosti, referenciu záznamu poskytovateľa a verziu pravidiel mapovania. Nenamapovaná hodnota by mala vytvoriť stav vyžadujúci preskúmanie, nie sa predvolene zmeniť na doručenú alebo neúspešnú. Vytvorenie štítku by sa nemalo považovať za dôkaz fyzického prijatia prepravcom, pokiaľ zdrojová udalosť takú interpretáciu výslovne nepodporuje.
4. Používajte pravidlá prechodov, nie jednoduché číselné poradie
Stavy zásielky netvoria vždy priamu postupnosť. Po výnimke môže nasledovať bežná preprava a pokus o doručenie nie je doručením. Pohyb pri vrátení sa môže začať po skoršej udalosti doručenia.
- Umožnite odstránenie výnimky, keď následné dôkazy podporujú obnovenie pohybu.
- Zabráňte tomu, aby bežné historické skenovanie potichu nahradilo stav doručenia.
- Umožnite zdokumentovanú opravu prostredníctvom riadenej revíznej cesty.
- Ak to OMS podporuje, sledujte pohyb pri vrátení oddelene od dokončenia odoslania.
- Nejednoznačné alebo protichodné dôkazy smerujte do prevádzkovej fronty.
Verzujte tieto pravidlá. Keď sa mapovanie zmení, rozhodnite, či sa uplatní iba na nové udalosti alebo či historické záznamy vyžadujú riadený prepočet.
Vypočítajte stav objednávky z požadovaných povinností plnenia
Stav balíka a stav objednávky by mali byť samostatné polia. Balík označený ako doručený poskytuje dôkaz pre tento balík; dokončenie objednávky závisí od zostávajúcich požadovaných množstiev a vašej obchodnej politiky.
Užitočným predvoleným pravidlom je označiť objednávku ako úplne doručenú iba vtedy, keď všetky množstvá vyžadujúce doručenie majú platný dôkaz doručenia na úrovni balíka a nezostávajú nevyriešené požadované pridelenia. Zrušené množstvá vylúčte podľa pravidiel zrušenia OMS. Digitálne položky, objednávky na vyzdvihnutie a iné povinnosti bez odoslania riešte prostredníctvom ich vlastných podmienok dokončenia.
Náhradné zásielky vyžadujú explicitné vzťahy. Ak je stratený balík nahradený, rozhodnite, či náhrada preberá pôvodnú povinnosť doručenia. Inak môže pôvodný balík blokovať dokončenie na neurčito alebo sa do plnenia môžu započítať oba balíky. Rozhodnutie zaznamenajte namiesto jeho odvodenia iba zo stavu sledovania.
Dokončenie doručenia udržiavajte oddelene od finančného uzavretia, oprávnenosti na vrátenie peňazí a riešenia sporov. Udalosť doručenia od prepravcu by nemala automaticky autorizovať refundáciu ani uzavrieť zákaznícku reklamáciu.
Obnovte sa po zlyhaniach bez straty auditnej stopy
Dočasné zlyhania opakujte s ohraničeným oneskorením a podľa zdokumentovaných pokynov na opakovanie. Dočasné zlyhania pripojenia oddeľte od neplatných identifikátorov, vypršaných poverení, chýb oprávnení a nekompatibility schémy. Posledné uvedené vyžadujú nápravu, nie nekonečné opakovanie.
Udržiavajte frontu neúspešnej práce obsahujúcu príslušného tenanta, balík, referenciu udalosti, pokus o operáciu, klasifikáciu chyby a ďalšiu akciu. Zaznamenajte dostatok kontextu na vyšetrovanie bez kopírovania nepotrebných údajov zákazníkov alebo poverení do logov.
Okrem bežnej cesty aktualizácie vykonávajte aj zosúladenie. Kontrolujte aktívne zásielky so zastaranými informáciami o sledovaní, prijaté udalosti, ktorých zápisy do OMS zlyhali, nezhodné pozorovania a rozdiely medzi vypočítaným stavom integrácie a OMS. Frekvenciu kontrol voľte podľa záväzkov doručenia, limitov API a prevádzkového rizika, nie podľa ľubovoľného univerzálneho harmonogramu.
Priraďte vlastníctvo: inžinierstvo rieši prijímanie a zlyhania zápisov; prevádzka plnenia rieši chýbajúce vzťahy balíkov; zákaznícke služby kontrolujú výnimky vyžadujúce komunikáciu so zákazníkom. Fronta bez zodpovedného vlastníka je iba úložisko.
Pred spustením otestujte mapovanie a obchodné pravidlá
Použite kontrolované testovacie dáta a obmedzené nasadenie do produkcie. Nasledujúce prípady otestujte voči histórii udalostí aj výslednému záznamu OMS:
- Jednobalíková objednávka normálne postupuje až k doručeniu.
- Rozdelená objednávka má jeden doručený balík a jeden stále v pohybe.
- Tá istá udalosť je prijatá opakovane bez duplicitných vedľajších účinkov.
- Staršie skenovanie počas prepravy príde po doručení.
- Neznámy prepravca alebo stav vstúpi do fronty na kontrolu.
- Štítok je nahradený bez vytvorenia ďalšej povinnosti plnenia.
- Náhradná zásielka podľa schváleného pravidla nahradí pôvodný balík.
- OMS nie je dostupný po prijatí udalosti.
- Proces sa reštartuje medzi zápisom do OMS a jeho potvrdením.
- Rovnaké zobrazované číslo objednávky existuje v dvoch obchodoch bez párovania medzi tenantmi.
Spustite systém vtedy, keď má každá prijatá udalosť sledovateľný výsledok spracovania, nejednoznačné zhody nemôžu automaticky aktualizovať objednávky a operátori môžu bezpečne znovu spustiť neúspešnú prácu. Ide o užitočnejšie akceptačné kritériá než iba preukázanie úspešnosti požiadavky API.
Často kladené otázky
Môžem pripojiť sledovacie čísla priamo k objednávkam?
Pri striktne jednobalíkovom procese môže byť priame prepojenie spočiatku postačujúce. Aj tak však použite internú identitu zásielky medzi objednávkou a priradením sledovania. Poskytne migračnú cestu pre rozdelené zásielky, opätovné označenie a náhrady bez zmeny významu záznamu objednávky.
Mala by integrácia používať webhooky alebo dotazovanie?
Použite mechanizmus doručovania podporovaný poskytovateľom a kompatibilný s vašou infraštruktúrou. Webhooky môžu obmedziť opakované získavanie údajov, zatiaľ čo dotazovanie môže podporovať pracovné postupy založené na získavaní údajov a zosúladenie, ak je dostupné. Ani jeden prístup neodstraňuje potrebu trvalého ukladania, spracovania duplicít a obnovy.
Čo sa má stať, keď udalosť sledovania nemá zodpovedajúcu objednávku?
Uložte ju do fronty nezhodných udalostí a preskúmajte registračný záznam, kontext tenanta, identitu prepravcu a čas vytvorenia zásielky. Nevytvárajte objednávku ani nepripájajte udalosť automaticky k pravdepodobnému zákazníkovi. Po oprave mapovania ju spracujte znova.
Mali by upozornenia o doručení odosielať OMS alebo systém sledovania?
Pre každý typ upozornenia a spúšťač vyberte jedného vlastníka. Ak môžu rovnakú správu odosielať dva systémy, jednu cestu deaktivujte alebo zdieľajte trvalú evidenciu upozornení. Rozhodnite tiež, či sa správa týka jedného balíka alebo celej objednávky, najmä pri rozdelenom plnení.
Znamená stav výnimky, že objednávka zlyhala?
Nie. Výnimka je pozorovanie vyžadujúce interpretáciu, nie nevyhnutne trvalý výsledok. Zachovajte dôvod, sledujte následné udalosti a pomocou eskalačnej politiky rozhodnite, kedy má zasiahnuť prevádzka.
Zdroje
- 17TRACK Tracking API — oficiálna referencia produktu a východisko pre integráciu API.
- Dokumentácia 17TRACK API — implementačná referencia pre zmluvu špecifickú pre poskytovateľa; pred nasadením overte príslušné rozhrania a požiadavky účtu.
- RFC 9110, oddiel 9.2.2: Idempotentné metódy — sémantika HTTP podporujúca rozlíšenie medzi idempotenciou metód a ochranou aplikácie pred duplicitami.


