Skip to main content
DomůBlogPrůvodciJak propojit data o sledování zásilek s Oms: Mapování objednávek a pravidla synchronizace

Jak propojit data o sledování zásilek s Oms: Mapování objednávek a pravidla synchronizace

17TRACK

Chcete-li připojit data o sledování zásilek k systému pro správu objednávek (OMS), namapujte každý sledovaný balík na interní záznam zásilky a poté tuto zásilku propojte s její objednávkou a řádky plnění. Přijímejte aktualizace sledování prostřednictvím rozhraní podporovaného poskytovatelem, zachovávejte původní události a používejte explicitní pravidla pro duplicity, opožděné aktualizace, stav zásilky a dokončení objednávky. Nepoužívejte samotné sledovací číslo jako identifikátor objednávky a nedovolte, aby jediná událost doručení automaticky uzavřela objednávku s více balíky.

Jak připojit data o sledování zásilek k OMS objednávce

Tato příručka je určena integračním inženýrům a týmům e-commerce provozu, které toto propojení implementují. Doporučený návrh odděluje pozorování přepravce od obchodních rozhodnutí: data sledování popisují cestu balíku, zatímco OMS rozhoduje, co tato cesta znamená pro plnění, komunikaci se zákazníkem a uzavření objednávky.

Určete, který systém vlastní jednotlivé záznamy

Před vytvořením připojení API se dohodněte na vlastnictví se správcem OMS, týmem plnění a týmem zákaznických služeb. Jinak může technicky úspěšná integrace stále přepisovat platná obchodní data.

  • OMS: Vlastní objednávky, řádky objednávek, požadovaná množství, zrušení a pravidla pro dokončení objednávek.
  • Systém plnění: Vlastní záznamy zásilek nebo balíků, které vytváří, včetně přidělení balení a přiřazení štítků. Může jít o samotný OMS nebo samostatný skladový systém.
  • Poskytovatel sledování: Poskytuje pozorování sledování a případné klasifikace stavů definované poskytovatelem.
  • Integrační vrstva: Vlastní křížové odkazy identifikátorů, zpracování událostí, normalizaci, zpracování opakování a auditní záznamy synchronizace.

Považujte tyto hranice za doporučení, nikoli za předpoklady o vašem softwaru. Dokumentujte výjimky. Pokud například sklad může nahradit přepravní štítek, integrace potřebuje explicitní aktualizaci z tohoto systému, místo aby předpokládala, že nově zjištěné číslo nahrazuje staré.

Vytvořte mapování objednávky na balík před synchronizací stavů

Praktický vztah je objednávka → plnění → balík → přiřazení sledování. Váš OMS může používat jiné názvy nebo některé z těchto záznamů kombinovat. Zachovejte vztahy, i když se struktura databáze liší.

Objednávka může mít několik plnění a plnění může obsahovat několik balíků. Balík může také získat náhradní přiřazení sledování nebo propojený identifikátor posledního úseku doručení. Tyto identifikátory by neměly vytvářet další objednaná množství.

ZáznamDoporučená poleÚčel
ObjednávkaID tenanta nebo obchodu, neměnné ID objednávky OMSOdděluje obchodníky a zabraňuje závislosti na zobrazovaných číslech objednávek.
PlněníID plnění, ID objednávky, ID a množství přidělených řádkůUrčuje, které zakoupené položky jsou plněny.
BalíkInterní ID balíku, ID plnění, přidělení balíku, pokud jsou k dispoziciPoskytuje stabilní identitu nezávislou na sledovacích štítcích.
Přiřazení sledováníID přiřazení, ID balíku, účet poskytovatele, identifikátor přepravce, sledovací číslo, období platnostiPropojuje příchozí pozorování sledování se správným balíkem a životním cyklem přiřazení.

Porovnávejte aktualizace prostřednictvím uloženého křížového odkazu

Při vytvoření zásilky uložte její interní ID ještě před registrací ke sledování. Uložte také ID sledovacího záznamu vydané poskytovatelem, které vrátí zdokumentovaný registrační proces. Pokud poskytovatel podporuje referenci obchodníka, použijte neprůhlednou interní referenci a mapování uchovávejte lokálně.

U příchozích aktualizací nejprve vyhledejte uložené ID záznamu poskytovatele v rámci správného účtu poskytovatele a tenanta. Pokud tento identifikátor není k dispozici, použijte zdokumentovanou kombinaci sledovacího čísla, identity přepravce, kontextu účtu a historie přiřazení. Považujte to za strategii vyhledávání, nikoli za záruku, že je tato kombinace globálně jedinečná.

Nevyhledávejte podle jména zákazníka, e-mailové adresy ani neomezeného zobrazovaného čísla objednávky. Uchovávejte sledovací čísla jako řetězce, aby zůstaly zachovány úvodní nuly. Neodstraňujte znaky ani neměňte velikost písmen, pokud to příslušná smlouva s přepravcem nebo poskytovatelem nepovoluje.

Pokud vyhledávání nevrátí žádnou shodu nebo několik možných shod, izolujte aktualizaci k prošetření. Nevyřešená událost je bezpečnější než sebejistá aktualizace objednávky nesprávného zákazníka.

Řešte rozdělené objednávky bez vymýšlení přidělení balíků

Zvažte názornou objednávku obsahující tři jednotky. Balík A obsahuje dvě jednotky a balík B jednu. Doručení balíku A znamená, že existuje důkaz o doručení dvou jednotek; neznamená to, že byla doručena celá objednávka.

Pokud systém plnění zaznamenává pouze to, že oba balíky patří ke stejnému plnění, nevymýšlejte přidělení na úrovni jednotek. Stále můžete vypočítat, zda byly doručeny všechny požadované balíky, ale vykazování doručení na úrovni položek by mělo zůstat nedostupné nebo výslovně nejisté, dokud nebudou k dispozici údaje o přidělení.

Připojte API sledování prostřednictvím odolné ingestní vrstvy

Použijte proces, který odděluje komunikaci s poskytovatelem od zápisů do OMS:

Vytvoření zásilky → registrace sledování → příchozí aktualizace nebo plánované načtení → trvalé uložení události → mapování a normalizace → aktualizace OMS → rekonciliace

Pro implementaci 17TRACK jsou relevantními výchozími body stránka produktu Tracking API a oficiální dokumentace API. Před implementací adaptéru ověřte příslušné registrační rozhraní, identifikátory přepravců, možnosti doručování aktualizací, požadavky na autentizaci, definice stavů a limity účtu. Datový model v této příručce je integračním doporučením, nikoli tvrzením, že 17TRACK používá tato názvy polí nebo poskytuje nativní konektor pro váš OMS.

Pokud váš vybraný poskytovatel podporuje webhooky, autentizujte příchozí požadavky pomocí jeho zdokumentovaného mechanismu a přijaté zprávy trvale uložte ještě před jejich potvrzením. Pomalé operace OMS držte mimo cestu požadavku. Řiďte se skutečnou smlouvou poskytovatele o potvrzování a opakování, místo abyste předpokládali konkrétní tělo odpovědi nebo časový limit.

Pokud je vyžadováno dotazování, ukládejte průběh načítání tam, kde to API podporuje, řiďte souběžnost a dodržujte zdokumentované limity rychlosti. Přijetí webhooku ani úspěšný požadavek na dotazování nedokazují, že byl OMS aktualizován; tyto výsledky zaznamenávejte odděleně.

Definujte pravidla synchronizace, která odolají opakováním a opožděným událostem

1. Zajistěte idempotentní zpracování

Zpracování stejného pozorování dvakrát by nemělo duplikovat zásilku, dvakrát zvýšit množství ani znovu odeslat stejné oznámení zákazníkovi. HTTP nečiní libovolnou operaci POST idempotentní; integrace musí implementovat ochranu proti duplicitám. RFC 9110 vysvětluje idempotenci metod HTTP.

Pokud je zdokumentováno a dostupné stabilní ID události poskytovatele, použijte je. Jinak definujte otisk z ID přiřazení a relevantních polí události, jako je časové razítko události, zdrojový stav a umístění. Dokumentujte možnost kolizí nebo změněných popisů událostí. Nezpracované pozorování uchovávejte i tehdy, když nevede k další akci OMS.

Chraňte každý vedlejší účinek samostatně. Například zápis stavu OMS a e-mailové oznámení potřebují vlastní kontroly deduplikace. Použijte transakční outbox nebo rovnocenný trvalý pracovní záznam, aby pád procesu nemohl zanechat přijatou událost bez naplánované aktualizace.

2. Ukládejte čas události a čas přijetí odděleně

Čas výskytu události a čas, kdy ji vaše integrace přijala, odpovídají na různé otázky. Uložte oba údaje spolu s původní reprezentací časového razítka a případným poskytnutým posunem časového pásma. Události s neznámým časovým pásmem tiše nepřiřazujte časové pásmo skladu.

Opožděně doručený sken zásilky v přepravě by měl obvykle obohatit historii, aniž by nahradil novější stav doručeno. Samotná časová razítka však nestačí: poskytovatel může vydat opravu a události mohou mít neúplné časové údaje. Pokud jsou k dispozici, používejte zdokumentovaná pole pořadí nebo revize spolu s explicitními pravidly oprav.

3. Normalizujte stavy, aniž byste vymazali podrobnosti zdroje

Vytvořte malý interní slovník, kterému OMS rozumí, například čeká na přijetí přepravcem, v přepravě, doručování, doručeno, výjimka a vrací se. Namapujte do něj zdokumentované stavy poskytovatele. Jde o navrhované interní kategorie, nikoli univerzální definice přepravců.

Ukládejte původní kód stavu, popis, místo události, referenci záznamu poskytovatele a verzi mapovacího pravidla. Nenamapovaná hodnota by měla vytvořit podmínku vyžadující kontrolu, nikoli se automaticky nastavit na doručeno nebo neúspěšně. Vytvoření štítku by nemělo být považováno za důkaz fyzického převzetí přepravcem, pokud zdrojová událost tuto interpretaci výslovně nepodporuje.

4. Používejte pravidla přechodů, nikoli jednoduché číselné pořadí

Stavy zásilky netvoří vždy přímou posloupnost. Po výjimce může následovat běžná přeprava a pokus o doručení není doručením. Pohyb zpět může začít po dřívější události doručení.

  • Umožněte zrušení výjimky, když následné důkazy podporují obnovený pohyb.
  • Zabraňte tomu, aby běžný historický sken tiše nahradil stav doručeno.
  • Umožněte zdokumentovanou opravu prostřednictvím řízené revizní cesty.
  • Pokud to OMS podporuje, sledujte pohyb zpět odděleně od dokončení odchozí zásilky.
  • Nejednoznačné nebo protichůdné důkazy směrujte do provozní fronty.

Tato pravidla verzujte. Když se mapování změní, rozhodněte, zda se vztahuje pouze na nové události, nebo zda historické záznamy vyžadují řízený přepočet.

Vypočítejte stav objednávky z požadovaných povinností plnění

Stav balíku a stav objednávky by měly být oddělená pole. Balík označený jako doručený poskytuje důkaz pro daný balík; dokončení objednávky závisí na zbývajících požadovaných množstvích a vaší obchodní politice.

Užitečným výchozím pravidlem je označit objednávku jako plně doručenou pouze tehdy, když mají všechna množství vyžadující doručení platný důkaz doručení na úrovni balíků a nezůstávají nevyřešená povinná přidělení. Zrušená množství vylučujte podle pravidel zrušení OMS. Digitální položky, objednávky s osobním odběrem a jiné povinnosti bez přepravy řešte vlastními podmínkami dokončení.

Náhradní zásilky vyžadují explicitní vztahy. Pokud je ztracený balík nahrazen, rozhodněte, zda náhrada nahrazuje původní povinnost doručení. Jinak může původní balík blokovat dokončení bez omezení nebo se do plnění mohou započítat oba balíky. Rozhodnutí zaznamenejte, místo abyste je odvozovali pouze ze stavu sledování.

Dokončení doručení udržujte oddělené od finančního uzavření, způsobilosti k vrácení peněz a řešení sporů. Událost doručení od přepravce by neměla automaticky autorizovat refundaci ani vyřešit zákaznickou reklamaci.

Obnovujte po selháních bez ztráty auditní stopy

Přechodná selhání opakujte s omezeným exponenciálním prodlením a podle zdokumentovaných pokynů k opakování. Oddělujte dočasná selhání připojení od neplatných identifikátorů, prošlých přihlašovacích údajů, chyb oprávnění a nekompatibility schématu. Tyto poslední případy vyžadují nápravné opatření, nikoli nekonečné opakování.

Udržujte frontu neúspěšné práce obsahující dotčeného tenanta, balík, referenci události, pokus o operaci, klasifikaci chyby a další akci. Zaznamenávejte dostatek kontextu pro šetření, aniž byste do protokolů kopírovali nepotřebná zákaznická data nebo přihlašovací údaje.

Kromě běžné cesty aktualizací provádějte rekonciliaci. Kontrolujte aktivní zásilky se zastaralými informacemi o sledování, přijaté události, jejichž zápisy do OMS selhaly, nespárovaná pozorování a rozdíly mezi vypočteným stavem integrace a stavem OMS. Četnost kontrol zvolte podle závazků doručení, limitů API a provozního rizika, nikoli podle libovolného univerzálního rozvrhu.

Určete odpovědnost: inženýrství řeší příjem a selhání zápisů; provoz plnění řeší chybějící vztahy balíků; zákaznické služby kontrolují výjimky vyžadující komunikaci se zákazníkem. Fronta bez odpovědného vlastníka je pouze úložiště.

Před spuštěním otestujte mapování a obchodní pravidla

Používejte řízené testovací případy a omezené uvedení do produkce. Otestujte následující případy proti historii událostí i výslednému záznamu OMS:

  • Jednobalíková objednávka běžně postoupí k doručení.
  • Rozdělená objednávka má jeden doručený balík a jeden stále v pohybu.
  • Stejná událost je přijata opakovaně bez duplicitních vedlejších účinků.
  • Starší sken přepravy dorazí po doručení.
  • Neznámý přepravce nebo stav vstoupí do fronty ke kontrole.
  • Štítek je nahrazen bez vytvoření další povinnosti plnění.
  • Náhradní zásilka podle schváleného pravidla nahradí původní balík.
  • OMS je po přijetí události nedostupný.
  • Proces se restartuje mezi zápisem do OMS a jeho potvrzením.
  • Stejné zobrazované číslo objednávky existuje ve dvou obchodech bez párování mezi tenanty.

Spusťte systém, když má každá přijatá událost dohledatelný výsledek zpracování, nejednoznačné shody nemohou automaticky aktualizovat objednávky a operátoři mohou bezpečně znovu spustit neúspěšnou práci. Jde o užitečnější akceptační kritéria než pouhé prokázání úspěšného požadavku API.

Časté dotazy

Mohu připojit sledovací čísla přímo k objednávkám?

U přísně jednobalíkového procesu může být přímý vztah zpočátku dostačující. Přesto použijte interní identitu zásilky mezi objednávkou a přiřazením sledování. Poskytuje migrační cestu pro rozdělené zásilky, nové štítky a náhrady bez změny významu záznamu objednávky.

Má integrace používat webhooky, nebo dotazování?

Použijte způsob doručování podporovaný poskytovatelem a kompatibilní s vaší infrastrukturou. Webhooky mohou omezit opakované načítání, zatímco dotazování může podporovat procesy založené na načítání a dostupnou rekonciliaci. Žádný z přístupů neodstraňuje potřebu trvalého ukládání, zpracování duplicit a obnovy.

Co se má stát, když událost sledování nemá odpovídající objednávku?

Uložte ji do fronty nespárovaných událostí a prošetřete registrační záznam, kontext tenanta, identitu přepravce a čas vytvoření zásilky. Nevytvářejte automaticky objednávku ani nepřipojujte událost k pravděpodobnému zákazníkovi. Po opravě mapování ji zpracujte znovu.

Mají oznámení o doručení vycházet z OMS, nebo ze systému sledování?

Pro každý typ oznámení a spouštěč zvolte jednoho vlastníka. Pokud mohou stejnou zprávu odesílat dva systémy, jednu cestu zakažte nebo sdílejte trvalý registr oznámení. Rozhodněte také, zda se zpráva týká jednoho balíku nebo celé objednávky, zejména u rozděleného plnění.

Znamená stav výjimky, že objednávka selhala?

Ne. Výjimka je pozorování vyžadující interpretaci, nikoli nutně trvalý výsledek. Uchovávejte důvod, sledujte následné události a pomocí zásad eskalace rozhodněte, kdy má zasáhnout provoz.

Zdroje