API za sledenje pomorskemu tovornemu prometu: dogodki zabojnikov, podatki o predvidenem času prihoda (ETA) in merila za izbiro

API za sledenje pomorskemu tovornemu prometu mora povezati premike zabojnikov, transportne mejnike in posodobitve predvidenega časa prihoda (ETA) s pošiljko, ki jo upravlja vaša ekipa. Za špediterje, uvoznike in integracijske ekipe je merilo izbire, ali lahko zanesljivo prepozna pravo pot zabojnika, razlikuje dejanske dogodke od napovedi ter zagotovi dovolj konteksta za podporo operativnim odločitvam. Splošno stanje pošiljke ali nepojasnjen datum prihoda ne zadostujeta za upravljanje pomorskega tovornega prometa.

Ta vodnik pojasnjuje, katere podatke zahtevati, kako razlagati dogodke zabojnikov in ocene prihodov ter kako oceniti integracijo, preden ji zaupate promet v produkciji ali namenite sredstva za nabavo.

Začnite z modelom pošiljke, ne z zaslonom za sledenje

Sledenje pomorskemu tovornemu prometu vključuje več povezanih objektov: komercialno pošiljko, njene transportne dokumente, enega ali več zabojnikov ter transportne odseke, ki jih prevažajo. Ti odnosi so pomembni, saj lahko ena rezervacija vključuje več zabojnikov, zabojnik pa se lahko premika prek več plovil, terminalov in kopenskih odsekov.

Uporabna integracija mora te odnose ohraniti, namesto da vse splošči v eno samo stanje. Če se dva zabojnika v okviru iste pošiljke premikata različno, mora sistem operaterju omogočiti vpogled v razliko, namesto da prikaže navidezno popoln mejnik na ravni pošiljke.

Pred ocenjevanjem API-ja določite reference, ki jih vaše podjetje dejansko prejema:

• Številka zabojnika: Identificira opremo, vendar mora biti povezana z ustrezno pošiljko ali potjo, saj se zabojniki ponovno uporabljajo.
• Referenca rezervacije pri prevozniku: Zahtevo za sledenje lahko poveže z rezervacijo, odvisno od zahtev izvornega sistema za iskanje.
• Referenca transportnega dokumenta: Pošiljko lahko identificira na ravni pomorskega prevoznika. Preverite, ali API sprejema reference dokumentov, ki jih ima vaša ekipa.
• Interni ID pošiljke: Zunanje zapise sledenja poveže z vašim sistemom za upravljanje transporta, ERP-sistemom ali špeditersko programsko opremo.

Ne predvidevajte, da je referenco hišnega konosamenta, ki jo izda špediter, mogoče uporabiti povsod, kjer je zahtevana referenca dokumenta pomorskega prevoznika. Preizkusite natančne identifikatorje, ki so na voljo v vaših delovnih tokovih rezervacij in dokumentacije.

Katere dogodke zabojnikov mora API izpostaviti?

Standardi Track & Trace organizacije Digital Container Shipping Association so uporabna referenca za razpravo o podatkih pomorskih pošiljk. DCSA razlikuje med dogodki pošiljke, transporta in opreme. Te kategorije pomagajo ločiti administrativni napredek, premikanje transporta in ravnanje s fizičnim zabojnikom.

Ponudniku ni treba uporabljati vaših prednostnih imen polj, da bi bil uporaben, vendar mora pojasniti, kako se njegov model dogodkov preslika na operativne mejnike, ki jih potrebujete.

Dogodki opreme: kaj se je zgodilo z zabojnikom

Ustrezni mejniki opreme lahko vključujejo vstop skozi vrata, nakladanje, razkladanje, izstop skozi vrata in premike praznega zabojnika. Razpoložljivost je odvisna od poti, vira in izdelka. Zahtevajte vzorčne zapise, namesto da predvidevate, da je vsak dogodek na voljo na vsakem terminalu.

Te razlike imajo praktične posledice. Prihod plovila ne dokazuje, da je bil določen zabojnik raztovorjen. Raztovarjanje ne dokazuje, da je zabojnik sproščen ali pripravljen za prevzem. Zapis o izstopu skozi vrata prav tako potrebuje lokacijo in kontekst: izstop iz pretovornega objekta ni enak poslovni rezultat kot prevzem na končnem uvoznem terminalu.

Transportni dogodki: položaj plovila ali transportnega odseka

Dogodki prihoda in odhoda opisujejo transportno dejavnost. Za njihovo razlago vaš sistem potrebuje povezano lokacijo, način transporta in odsek. Kjer so na voljo, identifikatorji plovila in plovbe pomagajo razlikovati načrtovano plovbo od drugega premika med istimi pristanišči.

Pri pretovornem tovoru ohranite vmesne postanke. Če načrt poti zmanjšate na izvor in cilj, lahko skrijete zamujeno povezavo ali spremembo poti. Operativna časovnica mora omogočati vpogled v to, kateri odsek je zaključen in kateri je še vedno ocenjen.

Dogodki pošiljke: administrativni napredek ni fizično premikanje

Dogodki obdelave dokumentov in pošiljk so lahko uporabni za špediterske delovne tokove, vendar morajo ostati ločeni od premikanja zabojnika. Dokumentacijski mejnik ne potrjuje, da se je tovor fizično premaknil, dogodek premika pa ne potrjuje, da so izpolnjene vse komercialne ali regulativne zahteve.

Za vsak dogodek zahtevajte vrsto dogodka, ustrezni objekt, lokacijo, časovni žig dogodka, podatke o časovnem pasu, vir in navedbo, ali je dogodek načrtovan, ocenjen ali dejanski. Zahtevajte tudi stabilen identifikator dogodka in način obravnave popravkov, da ponavljajoče se posodobitve ne ustvarijo podvojenih mejnikov.

Podatki ETA potrebujejo cilj, pomen in zgodovino

ETA je ocenjeni čas prihoda na določeno točko. Sama po sebi ni obljuba, da bo tovor na voljo za prevzem. API za sledenje pomorskemu tovornemu prometu mora izrecno navesti ciljni mejnik, namesto da vrne dvoumno polje, označeno samo kot eta.

Ocena prihoda se lahko na primer nanaša na postanek v pristanišču, terminal, kopenski objekt ali drug opredeljen cilj. Preden jo uporabite za načrtovanje tovornjakov ali obljubo razpoložljivosti zaloge, natančno določite, kaj ta časovni žig predstavlja.

Ločite vir ocene od njenega stanja

Ocena, ki jo zagotovi prevoznik, in napoved, ki jo ustvari ponudnik, sta različna podatkovna izdelka. Nobena ne sme biti predstavljena kot dejanski prihod. Preverite, ali odgovor identificira izvor ocene, čas njenega izračuna ali objave ter lokacijo ali dogodek, ki ga napoveduje.

Če ponudnik ponuja napovedni ETA, zahtevajte njegovo metodologijo in pristop k preverjanju. Koristna vprašanja vključujejo, kateri mejnik je napovedan, kako dolgo pred prihodom se meri uspešnost ter ali se rezultati razlikujejo med vašimi transportnimi koridorji. Splošno trditev o natančnosti je težko uporabiti, če ciljni dogodek in merilno obdobje nista določena.

Ohranite spremembe ETA, namesto da jih prepišete

Najnovejši ETA podpira današnje načrtovanje; zgodovina sprememb pojasnjuje, kaj se je spremenilo. Shranite prejšnjo oceno, novo oceno, povezani mejnik, vir in čas, ko je vaš sistem prejel spremembo.

Ta zgodovina operativni ekipi omogoča razlikovanje med pomembno zamudo, popravkom oblikovanja ali spremembo nepovezanega postanka v pristanišču. Omogoča tudi naknadno ocenjevanje, ne da bi se pretvarjali, da je bila končna ocena znana že prej na poti.

Časovne pasove je treba izrecno preizkusiti. Ohranite izvorni časovni žig in njegov odmik, kjer sta zagotovljena, normalizirajte časovne žige za izračune in po potrebi prikažite lokalni operativni čas. Če vir zagotavlja samo datum, ga ne pretvorite tiho v natančno obljubo prihoda ob polnoči.

Ocenjujte pokritost na ravni dogodkov

Prisotnost prevoznika na seznamu pokritosti sama po sebi ne dokazuje, da je na voljo vsak mejnik zabojnika. Pokritost je treba preizkusiti glede na prevoznike, transportne koridorje, reference pošiljk in operativne dogodke, ki so pomembni za vaše podjetje.

Izdelajte ocenjevalno matriko z dejanskimi zahtevami. Za vsako reprezentativno pošiljko preverite, ali lahko API razreši referenco, vrne pravilen načrt poti, izpostavi zahtevane mejnike in ohrani posodobitve skozi del poti, ki ga upravljate.

• Neposredni pomorski premiki: Ali lahko prepoznate odhod iz izvora, prihod na cilj in ustrezne dogodke ravnanja z zabojnikom?
• Pretovorni premiki: Ali so vmesni odseki vidni in ali je mogoče zabojnike, ki se premikajo ločeno, še naprej razlikovati?
• Kopenski odseki: Če jih vaša storitev vključuje, ali API zagotavlja ustrezne mejnike za železnico, barže ali tovornjake oziroma se vidnost konča v pristanišču?
• Izjeme: Kako so predstavljeni manjkajoči dogodki, spremenjene poti, neusklajene reference in prekinitve vira?
• Zaključene pošiljke: Ali lahko vaša ekipa pridobi dovolj zgodovinskih podatkov za preiskavo spora s stranko ali uskladitev operativnega zapisa?

Nerazpoložljive podatke ločite od negativnih dogodkov. Odsotnost zapisa o raztovarjanju ne dokazuje, da do raztovarjanja ni prišlo. Uporabna integracija razlikuje med izrecnim operativnim stanjem in vrzeljo v vidnosti.

Obnašanje API-ja je enako pomembno kot seznam dogodkov

Tudi bogat vir dogodkov lahko postane težaven za upravljanje, če način dostave ni jasen. Ocenite, kako vaša aplikacija prejema posodobitve, obravnava popravke in se obnovi po izpadu.

Polling, spletni kavlji in obnova

Polling omogoča, da vaša aplikacija zahteva posodobitve po lastnem urniku. Spletni kavlji ponudniku omogočajo pošiljanje posodobitev na končno točko, ki jo upravljate. Noben mehanizem sam po sebi ne zagotavlja svežine: tudi takoj dostavljen spletni kavelj lahko vsebuje izvorni dogodek, prejet z zamudo.

Kjer je mogoče, zahtevajte ločene opredelitve časa izvornega dogodka, časa prejema pri ponudniku in časa obvestila. Pri spletnih kavljih potrdite preverjanje pristnosti ali podpisa, ponovne poskuse, vedenje pri podvojeni dostavi in možnost ponovne predvajanja neuspešnih obvestil. Pri pollingu preverite paginacijo, omejitve hitrosti, postopno pridobivanje in obravnavo zgodovinskih popravkov.

Normalizacija brez izgube dokazov

Normalizirana stanja olajšajo delovne tokove med prevozniki, vendar pretirano poenostavljanje odstrani uporaben kontekst. Prednost dajte modelu, ki omogoča ohranitev normaliziranega dogodka skupaj z izvirnim opisom ali kodo vira, kadar je na voljo.

Surove prejete zapise hranite ločeno od poslovnih pravil, ki jih pretvarjajo v stanja na nadzorni plošči. Tako lahko spremenite preslikavo, ne da bi izgubili izvirne dokaze. Prav tako je lažje raziskati stanje, namenjeno stranki, kadar se razlikuje od razlage operativne ekipe.

Komercialna in upravljavska preverjanja

Zahtevajte pisno razlago obračunske enote. Naročnina, sledena pošiljka, zabojnik, zahteva API-ja in obvestilo niso zamenljive mere. Pojasnite, kako ponovni poskusi, podvojene registracije, zgodovinska iskanja in ponovno aktivirane pošiljke vplivajo na stroške, namesto da bi predvidevali določen cenovni model.

Preglejte tudi hrambo podatkov, nadzor dostopa, menjavo poverilnic, dovoljeno nadaljnjo uporabo, stopnjevanje podpore in zaveze glede storitve. Pogodbena jamstva obravnavajte ločeno od predstavitev izdelka in trženjskih izjav.

Ne predvidevajte, da splošni API za sledenje izpolnjuje zahteve pomorskega tovornega prometa

API za sledenje je treba izbrati na podlagi preverjenega podatkovnega modela, ne njegove kategorijske oznake. Posodobitve dostave paketov in vidnost pomorskih zabojnikov lahko podpirajo različne delovne tokove, tudi če sta oba opisana kot sledenje pošiljkam.

Če je 17TRACK že na vašem ožjem seznamu integracij, uporabite njegovo uradno stran Tracking API in dokumentacijo API-ja kot izhodišče za preverjanje zahtev. Preden katero koli splošno integracijo za sledenje obravnavate kot rešitev za pomorski tovor, potrdite natančne pomorske reference, dogodke zabojnikov, transportne odseke in polja ETA, ki jih zahteva vaša aplikacija. Ta vodnik ne potrjuje teh zmogljivosti 17TRACK, specifičnih za pomorski promet.

Enak sprejemni standard mora veljati za vsakega kandidata: z reprezentativnimi pošiljkami dokažite zahtevane podatke in pojasnite omejitve. Širši delovni tok sledenja prevoznikov je lahko uporaben drugje v vaši dobavni verigi, ne da bi nadomestil specializiran vir dogodkov zabojnikov.

Izvedite preverjanje koncepta, osredotočeno na operativne odločitve

Najboljše preverjanje koncepta se začne z odločitvami, ki jih mora sprejemati vaša ekipa, ne s predstavitvijo nadzorne plošče. Izberite reprezentativne pošiljke iz lastnega poslovanja, vključno s preprostimi plovbami in zahtevnimi primeri, ki povzročajo ročno delo.

1. Določite merila sprejemljivosti. Pred testiranjem določite zahtevane reference, dogodke, lokacije, semantiko časovnih žigov in sprejemljivo obravnavo manjkajočih podatkov.
2. Preverite identiteto. Potrdite, da vsak rezultat pripada nameravani pošiljki in poti zabojnika. Kjer je pomembno, vključite ponovno uporabljeno opremo in rezervacije z več zabojniki.
3. Primerjajte z izvornimi zapisi. Vrnjenje mejnikov primerjajte z dostopnimi zapisi prevoznika ali terminala ter upoštevajte razlike v času posodobitev.
4. Preizkusite spremembe in napake. Preverite podvojena obvestila, dogodke v napačnem vrstnem redu, popravljene časovne žige, nerazpoložljive vire in izpade končnih točk.
5. Ponovite poslovni delovni tok. Preverite, ali podatki podpirajo predvideno dejanje, na primer pregled zamujene povezave ali posodobitev ocene prihoda vhodne zaloge.
6. Preglejte nerešene vrzeli. Zabeležite, ali vsaka vrzel izvira iz osnovnega vira, obdelave ponudnika ali vaše integracije. Pred razširitvijo uporabe se dogovorite o odpravi.

Pri testiranju ETA ohranite vsako napoved ob njenem prihodu in jo primerjajte s poznejšim dejanskim dogodkom za isti mejnik. Napovedi prihoda v pristanišče ne ocenjujte glede na prejem v skladišču in napovedi, izdelanih z zelo različnimi časi vnaprejšnje napovedi, ne združujte v eno nepojasnjeno oceno.

Pravilo izbire je preprosto: izberite integracijo, ki dokazljivo podpira vaše zahtevane odločitve s sledljivimi dogodki, razumljivimi ocenami in obnovljivim načinom dostave. Če načrtovanje prevzema zahteva tudi razpoložljivost terminala, stanje sprostitve ali termine, te vnose preverite ločeno, namesto da bi jih sklepali iz prihoda plovila.

Pogosta vprašanja

Ali lahko pomorsko pošiljko spremljam samo s številko zabojnika?

To je odvisno od vira podatkov in API-ja. Nekateri delovni tokovi lahko zahtevajo tudi identifikator prevoznika, referenco rezervacije ali referenco transportnega dokumenta. Ker se oprema ponovno uporablja, potrdite, da vrnjeni dogodki pripadajo vaši nameravani poti, namesto da se zanašate samo na številko zabojnika.

Ali dejanski prihod plovila pomeni, da je moj zabojnik pripravljen za prevzem?

Ne. Prihod plovila, raztovarjanje zabojnika, razpoložljivost tovora in dovoljenje za prevzem so ločena operativna dejstva. Odvisno od pošiljke lahko prevzem zahteva tudi podatke o sprostitvi in termin na terminalu. Ustrezne pogoje preverite pri strankah, ki so zanje odgovorne.

Ali sledenje plovilom AIS nadomešča sledenje zabojnikom?

Ne. AIS se nanaša na identifikacijo plovila in podatke o njegovem premikanju; sam po sebi ne potrjuje nakladanja, raztovarjanja, sprostitve ali izhoda posameznega zabojnika skozi vrata. Premikanje plovila lahko zagotovi kontekst, vendar je povezavo zabojnika s plovbo še vedno treba potrditi.

Kako pogosto naj se API za sledenje pomorskemu prometu posodablja?

Za vsak delovni tok ni enega uporabnega intervala. Zahteve določite glede na to, kako hitro mora vaša ekipa ukrepati po tem, ko so na voljo ustrezne informacije iz vira. Zakasnitev vira merite ločeno od zakasnitve dostave API-ja in potrdite, kaj se zgodi, kadar vir ne objavi novega dogodka.

Ali lahko dogodki sledenja izračunajo stroške nadležnine ali zadržanja?

Dogodki lahko podprejo časovnico, vendar ne določajo celotnega izračuna stroškov. Potrebujete tudi veljavne pogodbene pogoje, pravila prostega časa, obravnavo koledarja ter verodostojne začetne in končne pogoje. Plačljivih zneskov ne izpeljujte samo iz splošnih mejnikov.

Viri

• DCSA: standardi Track & Trace — Referenčni okvir za dogodke pošiljk, transporta in opreme pri prevozu zabojnikov.
• DCSA: repozitorij specifikacij OpenAPI — Tehnična referenca za definicije API-ja DCSA in strukture dogodkov. Pri načrtovanju integracije preverite veljavno različico specifikacije.
• Mednarodna pomorska organizacija: samodejni identifikacijski sistemi — Ozadje o AIS in informacijah o plovilih, ki jih zagotavlja.
• 17TRACK: Tracking API in uradna dokumentacija API-ja — Izhodišči za preverjanje ustreznosti izdelka; tukaj nista dokaz za podporo dogodkom pomorskih zabojnikov ali napovednemu ETA.