DomovBlogAPI na sledovanie námornej prepravy: udalosti kontajnerov, údaje ETA a kritériá výberu

API na sledovanie námornej prepravy: udalosti kontajnerov, údaje ETA a kritériá výberu

17TRACK

API na sledovanie námornej prepravy by malo prepájať pohyb kontajnerov, prepravné míľniky a aktualizácie ETA so zásielkou, ktorú spravuje váš tím. Pre špeditérov, dovozcov a integračné tímy je rozhodujúcim testom to, či dokáže spoľahlivo identifikovať správnu cestu kontajnera, rozlíšiť skutočné udalosti od predpovedí a poskytnúť dostatok kontextu na podporu operatívnych rozhodnutí. Všeobecný stav zásielky alebo nevysvetlený dátum príchodu nestačí na riadenie námornej prepravy.

Údaje API na sledovanie námornej prepravy, udalostí kontajnerov a ETA

Táto príručka vysvetľuje, aké údaje požadovať, ako interpretovať udalosti kontajnera a odhady príchodu a ako vyhodnotiť integráciu pred nasadením produkčnej prevádzky alebo vyčlenením rozpočtu na nákup.

Začnite modelom zásielky, nie obrazovkou sledovania

Sledovanie námornej prepravy zahŕňa niekoľko súvisiacich objektov: obchodnú zásielku, jej prepravné dokumenty, jeden alebo viac kontajnerov a prepravné úseky, ktoré ich prepravujú. Tieto vzťahy sú dôležité, pretože jedna rezervácia môže zahŕňať viacero kontajnerov, zatiaľ čo kontajner môže prechádzať cez niekoľko plavidiel, terminálov a vnútrozemských úsekov.

Užitočná integrácia musí zachovať tieto vzťahy namiesto toho, aby všetko zjednodušila na jeden stav. Ak sa dva kontajnery v rámci rovnakej zásielky pohybujú odlišne, systém by mal operátorovi umožniť tento rozdiel vidieť, a nie zobrazovať zdanlivo úplný míľnik na úrovni zásielky.

Pred vyhodnotením API identifikujte referencie, ktoré vaša firma v skutočnosti prijíma:

  • Číslo kontajnera: Identifikuje zariadenie, ale malo by byť priradené k príslušnej zásielke alebo ceste, pretože kontajnery sa opätovne používajú.
  • Referencia rezervácie u dopravcu: Môže prepojiť požiadavku na sledovanie s rezerváciou v závislosti od požiadaviek zdrojového systému na vyhľadávanie.
  • Referencia prepravného dokumentu: Môže identifikovať zásielku na úrovni námorného dopravcu. Overte, či API prijíma referencie dokumentov, ktoré má váš tím k dispozícii.
  • Interné ID zásielky: Prepája externé záznamy sledovania s vaším systémom riadenia dopravy, ERP alebo špedičným softvérom.

Nepredpokladajte, že referencia house bill vystavená špeditérom sa dá použiť všade tam, kde sa vyžaduje referencia dokumentu námorného dopravcu. Otestujte presné identifikátory dostupné vo vašich pracovných postupoch rezervácií a dokumentov.

Ktoré udalosti kontajnera by malo API poskytovať?

Štandardy Track & Trace organizácie Digital Container Shipping Association poskytujú užitočnú referenciu na diskusiu o údajoch námorných zásielok. DCSA rozlišuje udalosti zásielky, prepravy a zariadenia. Tieto kategórie pomáhajú oddeliť administratívny postup, pohyb prepravy a manipuláciu s fyzickým kontajnerom.

Dodávateľ nemusí používať vami preferované názvy polí, aby bol užitočný, mal by však vysvetliť, ako sa jeho model udalostí mapuje na operatívne míľniky, ktoré potrebujete.

Udalosti zariadenia: čo sa stalo s kontajnerom

Relevantné míľniky zariadenia môžu zahŕňať vstup do brány, naloženie, vyloženie, výstup z brány a pohyb prázdneho kontajnera. Dostupnosť závisí od cesty, zdroja a produktu. Vyžadujte vzorové záznamy namiesto predpokladu, že každá udalosť je dostupná na každom termináli.

Tieto rozdiely majú praktické dôsledky. Príchod plavidla nedokazuje, že konkrétny kontajner bol vyložený. Vyloženie nedokazuje, že kontajner bol uvoľnený alebo je pripravený na vyzdvihnutie. Záznam o výstupe z brány tiež potrebuje miesto a kontext: výstup z brány prekladiskového zariadenia nie je rovnaký obchodný výsledok ako vyzdvihnutie z konečného dovozného terminálu.

Udalosti prepravy: kde sa nachádza plavidlo alebo prepravný úsek

Udalosti príchodu a odchodu opisujú činnosť prepravy. Na ich interpretáciu potrebuje váš systém súvisiace miesto, druh prepravy a úsek. Ak sú k dispozícii, identifikátory plavidla a plavby pomáhajú rozlíšiť zamýšľanú plavbu od iného pohybu obsluhujúceho rovnaké prístavy.

Pri tranzitnom náklade zachovajte medzizastávky. Redukcia itinerára na pôvod a cieľ môže skryť zmeškané spojenie alebo zmenu trasy. Operatívna časová os by mala umožniť vidieť, ktorý úsek bol dokončený a ktorý zostáva odhadovaný.

Udalosti zásielky: administratívny postup nie je fyzický pohyb

Udalosti súvisiace s dokumentmi a spracovaním zásielky môžu byť užitočné pre špedičné pracovné postupy, mali by však zostať odlíšiteľné od pohybu kontajnera. Míľnik dokumentácie nepotvrdzuje, že sa náklad fyzicky pohol, a udalosť pohybu nepotvrdzuje splnenie všetkých obchodných alebo regulačných požiadaviek.

Pri každej udalosti požadujte typ udalosti, relevantný objekt, miesto, časovú pečiatku udalosti, informácie o časovom pásme, zdroj a údaj o tom, či je udalosť plánovaná, odhadovaná alebo skutočná. Vyžiadajte si aj stabilný identifikátor udalosti a správanie pri opravách, aby opakované aktualizácie nevytvárali duplicitné míľniky.

Údaje ETA potrebujú cieľ, význam a históriu

ETA je odhadovaný čas príchodu na konkrétne miesto. Sám osebe nepredstavuje prísľub, že náklad bude k dispozícii na vyzdvihnutie. API na sledovanie námornej prepravy by malo jasne uvádzať cieľový míľnik namiesto vrátenia nejednoznačného poľa označeného iba eta.

Odhad príchodu sa napríklad môže vzťahovať na zastavenie v prístave, terminál, vnútrozemské zariadenie alebo iný definovaný cieľ. Pred použitím na plánovanie nákladných vozidiel alebo prisľúbenie dostupnosti zásob presne určte, čo daná časová pečiatka predstavuje.

Oddeľte zdroj odhadu od jeho stavu

Odhad poskytnutý dopravcom a predpoveď vytvorená poskytovateľom sú odlišné dátové produkty. Ani jeden by nemal byť prezentovaný ako skutočný príchod. Zistite, či odpoveď identifikuje pôvod odhadu, čas jeho výpočtu alebo zverejnenia a miesto alebo udalosť, ktorú predpovedá.

Ak poskytovateľ ponúka prediktívne ETA, vyžiadajte si jeho metodiku a spôsob overovania. Užitočné otázky zahŕňajú, ktorý míľnik sa predpovedá, ako dlho pred príchodom sa meria výkonnosť a či sa výsledky líšia medzi trasami, ktoré používate. Všeobecné tvrdenie o presnosti sa ťažko uplatňuje, ak cieľová udalosť a obdobie merania nie sú špecifikované.

Uchovávajte revízie ETA namiesto ich prepisovania

Najnovšie ETA podporuje dnešné plánovanie; história revízií vysvetľuje, čo sa zmenilo. Uložte predchádzajúci odhad, nový odhad, súvisiaci míľnik, zdroj a čas, keď váš systém zmenu prijal.

Táto história umožňuje operačnému tímu rozlíšiť významné oneskorenie od opravy formátovania alebo zmeny nesúvisiaceho zastavenia v prístave. Podporuje tiež spätné vyhodnotenie bez predstierania, že konečný odhad bol známy už skôr počas cesty.

Časové pásma si zaslúžia výslovné testovanie. Ak je k dispozícii, zachovajte zdrojovú časovú pečiatku a jej posun, časové pečiatky normalizujte na účely výpočtov a v prípade potreby zobrazujte miestny operatívny čas. Ak zdroj poskytuje iba dátum, ticho ho neprevádzajte na presný prísľub príchodu o polnoci.

Vyhodnocujte pokrytie na úrovni udalostí

To, že sa dopravca nachádza na zozname pokrytia, samo osebe nepotvrdzuje dostupnosť každého míľnika kontajnera. Pokrytie treba testovať voči dopravcom, trasám, referenciám zásielok a operatívnym udalostiam, ktoré sú pre vašu firmu dôležité.

Vytvorte hodnotiacu maticu so svojimi skutočnými požiadavkami. Pri každej reprezentatívnej zásielke skontrolujte, či API dokáže vyriešiť referenciu, vrátiť správny itinerár, poskytnúť požadované míľniky a udržiavať aktualizácie počas časti cesty, ktorú spravujete.

  • Priame námorné prepravy: Dokážete identifikovať odchod z pôvodu, príchod do cieľa a relevantné udalosti manipulácie s kontajnerom?
  • Tranzitné prepravy: Sú viditeľné medziprepravné úseky a možno zachovať rozlíšenie medzi kontajnermi, ktoré sa pohybujú samostatne?
  • Vnútrozemské úseky: Ak ich vaša služba zahŕňa, poskytuje API relevantné míľniky železničnej, riečnej alebo cestnej prepravy, alebo viditeľnosť končí v prístave?
  • Výnimky: Ako sú reprezentované chýbajúce udalosti, zmenené trasy, nespárované referencie a prerušenia zdroja?
  • Dokončené zásielky: Dokáže váš tím získať dostatok historických údajov na preskúmanie zákazníckeho sporu alebo zosúladenie operatívneho záznamu?

Nedostupné údaje uchovávajte oddelene od negatívnych udalostí. Absencia záznamu o vyložení nedokazuje, že k vyloženiu nedošlo. Užitočná integrácia rozlišuje explicitný operatívny stav od medzery vo viditeľnosti.

Správanie API je rovnako dôležité ako zoznam udalostí

Aj bohatý tok udalostí môže byť náročný na prevádzku, ak nie je jasné správanie doručovania. Vyhodnoťte, ako vaša aplikácia prijíma aktualizácie, spracúva opravy a obnovuje prevádzku po výpadku.

Polling, webhooky a obnova

Polling umožňuje aplikácii vyžadovať aktualizácie podľa vlastného harmonogramu. Webhooky umožňujú poskytovateľovi odosielať aktualizácie na koncový bod, ktorý prevádzkujete. Ani jeden mechanizmus sám osebe nezaručuje aktuálnosť: okamžite doručený webhook môže stále obsahovať zdrojovú udalosť prijatú neskoro.

Ak je to možné, vyžiadajte si samostatné definície času zdrojovej udalosti, času prijatia poskytovateľom a času oznámenia. Pri webhookoch potvrďte autentifikáciu alebo overenie podpisu, opakovanie pokusov, správanie pri duplicitnom doručení a možnosť opätovného prehrania neúspešných oznámení. Pri pollingu skontrolujte stránkovanie, limity požiadaviek, inkrementálne získavanie a spracovanie historických opráv.

Normalizácia bez straty dôkazov

Normalizované stavy uľahčujú pracovné postupy naprieč dopravcami, nadmerné zjednodušenie však odstraňuje užitočný kontext. Uprednostnite model, ktorý umožňuje zachovať normalizovanú udalosť spolu s pôvodným opisom alebo kódom zdroja, ak je k dispozícii.

Ukladajte nespracované prijaté záznamy oddelene od obchodných pravidiel, ktoré ich premieňajú na stavy v informačnom paneli. To vám umožní upraviť mapovanie bez straty pôvodných dôkazov. Zároveň to uľahčuje preskúmanie stavu zobrazeného zákazníkovi, keď sa líši od interpretácie operačného tímu.

Obchodné a riadiace kontroly

Vyžiadajte si písomné vysvetlenie účtovacej jednotky. Predplatné, sledovaná zásielka, kontajner, požiadavka API a oznámenie nie sú zameniteľné miery. Ujasnite si, ako poplatky ovplyvňujú opakované pokusy, duplicitné registrácie, historické vyhľadávania a znovu aktivované zásielky, namiesto predpokladu konkrétneho cenového modelu.

Preskúmajte tiež uchovávanie údajov, riadenie prístupu, rotáciu poverení, povolené následné použitie, eskaláciu podpory a záväzky týkajúce sa služieb. Zmluvné záruky posudzujte oddelene od produktových ukážok a marketingových vyhlásení.

Nepredpokladajte, že všeobecné API na sledovanie spĺňa požiadavky námornej prepravy

API na sledovanie by sa malo vyberať podľa overeného dátového modelu, nie podľa označenia kategórie. Aktualizácie doručenia balíkov a viditeľnosť námorných kontajnerov môžu slúžiť odlišným pracovným postupom, aj keď sa obe označujú ako sledovanie zásielok.

Ak je 17TRACK už na vašom užšom zozname integrácií, použite jeho oficiálnu stránku Tracking API a dokumentáciu API ako východiskové body na kontrolu požiadaviek. Predtým, než budete akúkoľvek všeobecnú integráciu sledovania považovať za riešenie námornej prepravy, potvrďte presné námorné referencie, udalosti kontajnerov, prepravné úseky a polia ETA požadované vašou aplikáciou. Táto príručka nepotvrdzuje tieto špecifické schopnosti 17TRACK v oblasti námornej prepravy.

Rovnaký akceptačný štandard by mal platiť pre každého kandidáta: preukážte požadované údaje na reprezentatívnych zásielkach a vysvetlite jeho obmedzenia. Širší pracovný postup sledovania dopravcov môže byť užitočný inde vo vašom dodávateľskom reťazci bez toho, aby nahradil špecializovaný tok udalostí kontajnerov.

Vykonajte proof of concept zameraný na operatívne rozhodnutia

Najlepší proof of concept začína rozhodnutiami, ktoré musí váš tím prijímať, nie ukážkou informačného panela. Vyberte reprezentatívne zásielky z vlastnej prevádzky vrátane jednoduchých plavieb aj náročných prípadov, ktoré vytvárajú manuálnu prácu.

  1. Definujte akceptačné kritériá. Pred testovaním špecifikujte požadované referencie, udalosti, miesta, význam časových pečiatok a prijateľné spracovanie chýbajúcich údajov.
  2. Overte identitu. Potvrďte, že každý výsledok patrí zamýšľanej zásielke a ceste kontajnera. Ak je to relevantné, zahrňte opätovne použité zariadenia a rezervácie s viacerými kontajnermi.
  3. Porovnajte so zdrojovými záznamami. Porovnajte vrátené míľniky s dostupnými záznamami dopravcu alebo terminálu a zohľadnite rozdiely v načasovaní aktualizácií.
  4. Testujte revízie a zlyhania. Otestujte duplicitné oznámenia, udalosti v nesprávnom poradí, opravené časové pečiatky, nedostupné zdroje a výpadky koncových bodov.
  5. Prehrajte obchodný pracovný postup. Overte, či údaje podporujú zamýšľané konanie, napríklad preskúmanie oneskoreného spojenia alebo aktualizáciu odhadu prichádzajúcich zásob.
  6. Preskúmajte nevyriešené medzery. Zaznamenajte, či každá medzera pochádza zo základného zdroja, spracovania poskytovateľa alebo vašej integrácie. Pred rozšírením používania sa dohodnite na náprave.

Pri testovaní ETA uchovajte každú predpoveď tak, ako prichádza, a porovnajte ju s následnou skutočnou udalosťou pre rovnaký míľnik. Nehodnoťte predpoveď príchodu do prístavu voči prijatiu v sklade ani nekombinujte predpovede vytvorené s veľmi odlišným predstihom do jedného nevysvetleného skóre.

Pravidlo výberu je jednoduché: vyberte integráciu, ktorá preukázateľne podporuje vaše požadované rozhodnutia pomocou sledovateľných udalostí, zrozumiteľných odhadov a obnoviteľného správania pri doručovaní. Ak plánovanie vyzdvihnutia vyžaduje aj dostupnosť terminálu, stav uvoľnenia alebo rezervácie, overte tieto vstupy samostatne namiesto ich odvodzovania z príchodu plavidla.

Často kladené otázky

Môžem sledovať námornú zásielku iba pomocou čísla kontajnera?

Závisí to od zdroja údajov a API. Niektoré pracovné postupy môžu vyžadovať aj identifikátor dopravcu, referenciu rezervácie alebo referenciu prepravného dokumentu. Keďže sa zariadenia opätovne používajú, potvrďte, že vrátené udalosti patria vašej zamýšľanej ceste, a nespoliehajte sa iba na číslo kontajnera.

Znamená skutočný príchod plavidla, že môj kontajner je pripravený na vyzdvihnutie?

Nie. Príchod plavidla, vyloženie kontajnera, dostupnosť nákladu a povolenie na vyzdvihnutie sú samostatné operatívne skutočnosti. V závislosti od zásielky môže vyzdvihnutie vyžadovať aj informácie o uvoľnení a rezerváciu termínu na termináli. Overte príslušné podmienky u strán, ktoré za ne zodpovedajú.

Nahrádza sledovanie plavidiel AIS sledovanie kontajnerov?

Nie. AIS sa týka identifikácie plavidla a informácií o jeho pohybe; samo osebe nepotvrdzuje stav naloženia, vyloženia, uvoľnenia alebo výstupu konkrétneho kontajnera z brány. Pohyb plavidla môže poskytnúť kontext, ale priradenie kontajnera k plavbe treba stále potvrdiť.

Ako často by sa malo API na sledovanie námornej prepravy aktualizovať?

Neexistuje jediný užitočný interval pre každý pracovný postup. Požiadavky nastavte podľa toho, ako rýchlo musí váš tím konať po sprístupnení relevantných zdrojových informácií. Latenciu zdroja merajte oddelene od latencie doručenia API a potvrďte, čo sa stane, keď zdroj nezverejní novú udalosť.

Môžu udalosti sledovania vypočítať poplatky za demurrage alebo detention?

Udalosti môžu podporiť časovú os, ale neurčujú úplný výpočet poplatku. Potrebujete aj príslušné zmluvné podmienky, pravidlá voľného času, zaobchádzanie s kalendárom a autoritatívne počiatočné a koncové podmienky. Splatné sumy neodvodzujte iba zo všeobecných míľnikov.

Zdroje

Loading