DomůBlogAPI pro sledování námořní přepravy: Události kontejnerů, údaje o ETA a kritéria výběru

API pro sledování námořní přepravy: Události kontejnerů, údaje o ETA a kritéria výběru

17TRACK

API pro sledování námořní přepravy by mělo propojovat pohyb kontejnerů, přepravní milníky a aktualizace ETA se zásilkou, kterou váš tým spravuje. Pro zasílatele, dovozce a integrační týmy spočívá rozhodovací test v tom, zda dokáže spolehlivě identifikovat správnou cestu kontejneru, rozlišit skutečné události od předpovědí a poskytnout dostatek kontextu pro podporu provozních rozhodnutí. Obecný stav zásilky nebo nevysvětlené datum příjezdu pro řízení námořní přepravy nestačí.

Data o událostech kontejnerů a ETA v API pro sledování námořní přepravy a jejich výběr

Tato příručka vysvětluje, jaká data požadovat, jak interpretovat události kontejnerů a odhady příjezdu a jak vyhodnotit integraci před převedením provozu do produkce nebo přidělením rozpočtu na nákup.

Začněte modelem zásilky, nikoli obrazovkou sledování

Sledování námořní přepravy zahrnuje několik souvisejících objektů: obchodní zásilku, její přepravní dokumenty, jeden či více kontejnerů a přepravní úseky, které je přepravují. Tyto vztahy jsou důležité, protože jedna rezervace může zahrnovat více kontejnerů, zatímco jeden kontejner může projít několika plavidly, terminály a pozemními úseky.

Užitečná integrace musí tyto vztahy zachovat, nikoli vše zjednodušit do jediného stavu. Pokud se dva kontejnery v rámci stejné zásilky pohybují odlišně, systém by měl operátorovi umožnit tento rozdíl zobrazit, místo aby prezentoval zdánlivě úplný milník na úrovni zásilky.

Před vyhodnocením API určete reference, které vaše firma skutečně obdrží:

  • Číslo kontejneru: Identifikuje zařízení, ale mělo by být spojeno s příslušnou zásilkou nebo cestou, protože kontejnery se opakovaně používají.
  • Reference rezervace dopravce: Může propojit požadavek na sledování s rezervací v závislosti na požadavcích zdrojového systému na vyhledávání.
  • Reference přepravního dokumentu: Může identifikovat zásilku na úrovni námořního dopravce. Ověřte, zda API přijímá reference dokumentů, které má váš tým k dispozici.
  • Interní ID zásilky: Propojuje externí záznamy sledování s vaším systémem řízení přepravy, ERP nebo softwarem pro zasílatele.

Nepředpokládejte, že referenci house bill vystavenou zasílatelem lze použít všude, kde je vyžadována reference dokumentu námořního dopravce. Otestujte přesné identifikátory dostupné ve vašich pracovních postupech rezervací a dokumentace.

Které události kontejneru by mělo API poskytovat?

Standardy Track & Trace organizace Digital Container Shipping Association představují užitečnou referenci pro diskusi o datech námořních zásilek. DCSA rozlišuje události zásilky, přepravy a zařízení. Tyto kategorie pomáhají oddělit administrativní postup, pohyb přepravy a manipulaci s fyzickým kontejnerem.

Dodavatel nemusí používat vámi preferované názvy polí, aby byl užitečný, měl by však vysvětlit, jak jeho model událostí odpovídá provozním milníkům, které potřebujete.

Události zařízení: co se stalo s kontejnerem

Mezi relevantní milníky zařízení mohou patřit vjezd do terminálu, naložení, vyložení, výjezd z terminálu a pohyb prázdného kontejneru. Dostupnost závisí na cestě, zdroji a produktu. Požadujte vzorové záznamy a nepředpokládejte, že každá událost je dostupná na každém terminálu.

Tyto rozdíly mají praktické důsledky. Příjezd plavidla nedokazuje, že konkrétní kontejner byl vyložen. Vyložení nedokazuje, že kontejner byl uvolněn nebo je připraven k vyzvednutí. Záznam o výjezdu z terminálu také vyžaduje místo a kontext: výjezd z překladiště není stejný obchodní výsledek jako vyzvednutí z konečného dovozního terminálu.

Události přepravy: kde se nachází plavidlo nebo přepravní úsek

Události příjezdu a odjezdu popisují přepravní činnost. Pro jejich interpretaci potřebuje váš systém související místo, způsob přepravy a úsek. Pokud jsou k dispozici, identifikátory plavidla a plavby pomáhají odlišit zamýšlenou plavbu od jiného pohybu mezi stejnými přístavy.

U zásilek s překládáním zachovejte mezilehlé zastávky. Zjednodušení itineráře na původ a cíl může skrýt zmeškané spojení nebo změnu trasy. Provozní časová osa by měla umožnit zjistit, který úsek byl dokončen a který je stále pouze odhadovaný.

Události zásilky: administrativní postup není fyzický pohyb

Události týkající se dokumentů a zpracování zásilky mohou být užitečné pro pracovní postupy zasílatelů, ale měly by zůstat odlišitelné od pohybu kontejneru. Dokumentační milník nepotvrzuje, že se náklad fyzicky pohyboval, a událost pohybu nepotvrzuje splnění všech obchodních nebo regulačních požadavků.

U každé události požadujte typ události, relevantní objekt, místo, časové razítko události, informace o časovém pásmu, zdroj a označení, zda je událost plánovaná, odhadovaná nebo skutečná. Požádejte také o stabilní identifikátor události a chování při opravách, aby opakované aktualizace nevytvářely duplicitní milníky.

Data ETA potřebují cíl, význam a historii

ETA je odhadovaný čas příjezdu na určené místo. Sama o sobě nepředstavuje slib, že náklad bude k dispozici k vyzvednutí. API pro sledování námořní přepravy by mělo explicitně uvádět cílový milník, místo aby vracelo nejednoznačné pole označené pouze eta.

Odhad příjezdu může například označovat návštěvu přístavu, terminál, vnitrozemské zařízení nebo jiný definovaný cíl. Než jej použijete k plánování kamionů nebo příslibu dostupnosti zásob, přesně určete, co toto časové razítko představuje.

Oddělte zdroj odhadu od jeho stavu

Odhad poskytnutý dopravcem a predikce vytvořená poskytovatelem jsou odlišné datové produkty. Ani jeden by neměl být prezentován jako skutečný příjezd. Zjistěte, zda odpověď uvádí původ odhadu, čas jeho výpočtu nebo zveřejnění a místo či událost, kterou předpovídá.

Pokud poskytovatel nabízí prediktivní ETA, vyžádejte si jeho metodiku a přístup k validaci. Užitečné otázky zahrnují: který milník se predikuje, jak dlouho před příjezdem se měří přesnost a zda se výsledky liší podle tras, které používáte. Obecné tvrzení o přesnosti se obtížně uplatňuje, pokud není specifikována cílová událost a měřicí období.

Uchovávejte změny ETA místo jejich přepisování

Nejnovější ETA podporuje dnešní plánování; historie změn vysvětluje, co se změnilo. Uložte předchozí odhad, nový odhad, související milník, zdroj a čas, kdy váš systém změnu obdržel.

Tato historie umožňuje provoznímu týmu odlišit významné zpoždění od opravy formátování nebo změny nesouvisející návštěvy přístavu. Podporuje také zpětné vyhodnocení, aniž by předstírala, že konečný odhad byl znám již dříve během cesty.

Časová pásma vyžadují výslovné testování. Pokud je k dispozici, zachovejte zdrojové časové razítko a jeho posun, časová razítka normalizujte pro výpočty a podle potřeby zobrazujte místní provozní čas. Pokud zdroj poskytuje pouze datum, nepřevádějte je tiše na přesný příslib příjezdu o půlnoci.

Vyhodnocujte pokrytí na úrovni událostí

To, že se dopravce objevuje na seznamu pokrytí, samo o sobě nepotvrzuje dostupnost každého milníku kontejneru. Pokrytí je třeba testovat vůči dopravcům, trasám, referencím zásilek a provozním událostem, které jsou pro vaši firmu důležité.

Sestavte hodnoticí matici podle skutečných požadavků. U každé reprezentativní zásilky ověřte, zda API dokáže rozpoznat referenci, vrátit správný itinerář, poskytnout požadované milníky a udržovat aktualizace po část cesty, kterou spravujete.

  • Přímé námořní přepravy: Dokážete identifikovat odjezd z místa původu, příjezd do cíle a relevantní události týkající se manipulace s kontejnerem?
  • Přepravy s překládáním: Jsou viditelné mezilehlé úseky a lze odlišit kontejnery pohybující se samostatně?
  • Pozemní úseky: Pokud je vaše služba zahrnuje, poskytuje API relevantní milníky železniční, říční nebo kamionové přepravy, nebo viditelnost končí v přístavu?
  • Výjimky: Jak jsou reprezentovány chybějící události, změněné trasy, nespárované reference a přerušení zdroje?
  • Dokončené zásilky: Může váš tým načíst dostatek historických dat k prošetření sporu se zákazníkem nebo odsouhlasení provozního záznamu?

Nedostupná data uchovávejte odděleně od negativních událostí. Absence záznamu o vyložení nedokazuje, že k vyložení nedošlo. Užitečná integrace rozlišuje explicitní provozní stav od mezery ve viditelnosti.

Chování API je stejně důležité jako seznam událostí

I bohatý zdroj událostí může být obtížně provozovatelný, pokud není jasné chování doručování. Vyhodnoťte, jak vaše aplikace přijímá aktualizace, zpracovává opravy a obnovuje provoz po výpadku.

Polling, webhooky a obnova

Polling umožňuje aplikaci vyžadovat aktualizace podle vlastního rozvrhu. Webhooky umožňují poskytovateli odesílat aktualizace na koncový bod, který provozujete. Žádný z těchto mechanismů sám o sobě nezaručuje aktuálnost: i webhook doručený okamžitě může obsahovat zdrojovou událost přijatou se zpožděním.

Pokud je to možné, vyžádejte si samostatné definice času zdrojové události, času přijetí poskytovatelem a času oznámení. U webhooků ověřte autentizaci nebo ověření podpisu, opakované pokusy, chování při duplicitním doručení a možnost znovu přehrát neúspěšná oznámení. U pollingu zkontrolujte stránkování, limity rychlosti, inkrementální načítání a zpracování historických oprav.

Normalizace bez ztráty důkazů

Normalizované stavy usnadňují pracovní postupy napříč dopravci, ale nadměrné zjednodušení odstraňuje užitečný kontext. Upřednostněte model, který umožňuje zachovat normalizovanou událost spolu s původním popisem nebo kódem zdroje, pokud je k dispozici.

Ukládejte nezpracované příchozí záznamy odděleně od obchodních pravidel, která je převádějí na stavy řídicího panelu. To vám umožní upravit mapování bez ztráty původních důkazů. Usnadní také šetření stavu zobrazeného zákazníkovi, pokud se liší od interpretace provozního týmu.

Obchodní a správní kontroly

Vyžádejte si písemné vysvětlení účtovací jednotky. Předplatné, sledovaná zásilka, kontejner, požadavek API a oznámení nejsou zaměnitelné veličiny. Ujasněte si, jak poplatky ovlivňují opakované pokusy, duplicitní registrace, historická vyhledávání a znovu aktivované zásilky, místo abyste předpokládali konkrétní cenový model.

Prověřte také uchovávání dat, řízení přístupu, rotaci přihlašovacích údajů, povolené následné použití, eskalaci podpory a závazky úrovně služeb. Smluvní záruky posuzujte odděleně od produktových demonstrací a marketingových tvrzení.

Nepředpokládejte, že obecné API pro sledování splňuje požadavky námořní přepravy

API pro sledování by mělo být vybráno podle ověřeného datového modelu, nikoli podle označení kategorie. Aktualizace doručování balíků a viditelnost námořních kontejnerů mohou sloužit odlišným pracovním postupům, i když jsou obě popsány jako sledování zásilek.

Pokud je 17TRACK již na vašem užším seznamu integrací, použijte jeho oficiální stránku Tracking API a dokumentaci API jako výchozí body pro kontrolu požadavků. Předtím, než budete jakoukoli obecnou integraci sledování považovat za řešení pro námořní přepravu, potvrďte přesné reference námořní přepravy, události kontejnerů, přepravní úseky a pole ETA požadovaná vaší aplikací. Tato příručka nepotvrzuje tyto specifické schopnosti 17TRACK pro námořní přepravu.

Stejný akceptační standard by měl platit pro každého kandidáta: předveďte požadovaná data na reprezentativních zásilkách a vysvětlete omezení. Širší pracovní postup sledování dopravců může být jinde ve vašem dodavatelském řetězci užitečný, aniž by nahrazoval specializovaný zdroj událostí kontejneru.

Proveďte proof of concept zaměřený na provozní rozhodnutí

Nejlepší proof of concept začíná rozhodnutími, která váš tým potřebuje učinit, nikoli ukázkou řídicího panelu. Vyberte reprezentativní zásilky z vlastního provozu včetně jednoduchých plaveb a obtížných případů, které vytvářejí manuální práci.

  1. Definujte akceptační kritéria. Před testováním specifikujte požadované reference, události, místa, význam časových razítek a přijatelné zpracování chybějících dat.
  2. Ověřte identitu. Potvrďte, že každý výsledek patří zamýšlené zásilce a cestě kontejneru. Pokud je to relevantní, zahrňte opakovaně použité zařízení a rezervace s více kontejnery.
  3. Porovnejte se zdrojovými záznamy. Ověřte vrácené milníky vůči dostupným záznamům dopravce nebo terminálu a zohledněte rozdíly v načasování aktualizací.
  4. Otestujte změny a selhání. Prověřte duplicitní oznámení, události mimo pořadí, opravená časová razítka, nedostupné zdroje a výpadky koncových bodů.
  5. Zopakujte obchodní pracovní postup. Ověřte, zda data podporují zamýšlenou akci, například posouzení zmeškaného spojení nebo aktualizaci odhadu příchozích zásob.
  6. Prověřte nevyřešené mezery. Zaznamenejte, zda každá mezera pochází ze základního zdroje, zpracování poskytovatele nebo vaší integrace. Před rozšířením používání se dohodněte na nápravě.

Při testování ETA uchovávejte každou předpověď tak, jak přichází, a porovnejte ji s konečnou skutečnou událostí stejného milníku. Nehodnoťte předpověď příjezdu do přístavu vůči převzetí ve skladu a neslučujte předpovědi vytvořené s velmi odlišným předstihem do jediného nevysvětleného skóre.

Pravidlo výběru je jednoduché: zvolte integraci, která prokazatelně podporuje požadovaná rozhodnutí pomocí dohledatelných událostí, srozumitelných odhadů a obnovitelného chování doručování. Pokud plánování vyzvednutí vyžaduje také dostupnost terminálu, stav uvolnění nebo objednané termíny, ověřte tyto vstupy samostatně, místo abyste je odvozovali z příjezdu plavidla.

Časté dotazy

Mohu sledovat námořní zásilku pouze pomocí čísla kontejneru?

Záleží na zdroji dat a API. Některé pracovní postupy mohou vyžadovat také identifikátor dopravce, referenci rezervace nebo referenci přepravního dokumentu. Protože se zařízení opakovaně používá, ověřte, že vrácené události patří zamýšlené cestě, a nespoléhejte pouze na číslo kontejneru.

Znamená skutečný příjezd plavidla, že je můj kontejner připraven k vyzvednutí?

Ne. Příjezd plavidla, vyložení kontejneru, dostupnost nákladu a povolení k vyzvednutí jsou samostatné provozní skutečnosti. V závislosti na zásilce může vyzvednutí vyžadovat také informace o uvolnění a termín na terminálu. Ověřte příslušné podmínky u stran, které za ně odpovídají.

Nahrazuje sledování plavidel AIS sledování kontejnerů?

Ne. AIS se týká identifikace plavidla a informací o jeho pohybu; samo o sobě nepotvrzuje stav naložení, vyložení, uvolnění nebo výjezdu konkrétního kontejneru z terminálu. Pohyb plavidla může poskytnout kontext, ale spojení kontejneru s plavbou je stále nutné potvrdit.

Jak často by se mělo API pro sledování námořní přepravy aktualizovat?

Neexistuje jediný užitečný interval pro každý pracovní postup. Požadavky nastavte podle toho, jak rychle musí váš tým jednat poté, co jsou relevantní informace ze zdroje dostupné. Měřte latenci zdroje odděleně od latence doručení API a ověřte, co se stane, když zdroj nezveřejní novou událost.

Mohou události sledování vypočítat poplatky za demurrage nebo detention?

Události mohou podpořit časovou osu, ale neurčují kompletní výpočet poplatku. Potřebujete také příslušné smluvní podmínky, pravidla volného času, zacházení s kalendářem a závazné počáteční a koncové podmínky. Neodvozujte splatné částky pouze z obecných milníků.

Zdroje

Loading