API za praćenje pomorskog transporta: događaji kontejnera, podaci o vremenu dolaska (ETA) i kriterijumi za izbor

API za praćenje pomorskog transporta treba da poveže kretanje kontejnera, transportne prekretnice i ažuriranja ETA sa pošiljkom kojom upravlja vaš tim. Za špeditere, uvoznike i integracione timove, kriterijum izbora jeste da li može pouzdano da identifikuje odgovarajuće putovanje kontejnera, razlikuje stvarne događaje od prognoza i pruži dovoljno konteksta za podršku operativnim odlukama. Opšti status pošiljke ili neobjašnjen datum dolaska nisu dovoljni za upravljanje pomorskim transportom.

Ovaj vodič objašnjava koje podatke treba zatražiti, kako tumačiti događaje kontejnera i procene dolaska i kako proceniti integraciju pre nego što joj poverite produkcijski saobraćaj ili budžet za nabavku.

Počnite od modela pošiljke, a ne od ekrana za praćenje

Praćenje pomorskog transporta obuhvata nekoliko povezanih objekata: komercijalnu pošiljku, njena transportna dokumenta, jedan ili više kontejnera i transportne deonice koje ih prevoze. Ovi odnosi su važni jer jedna rezervacija može obuhvatati više kontejnera, dok se jedan kontejner može kretati kroz nekoliko brodova, terminala i kopnenih deonica.

Bolja korisnička iskustva i više ponovljenih kupovina uz brendirano praćenje i automatizovana obaveštenja. Isprobajte besplatno

Korisna integracija mora da očuva te odnose umesto da sve svodi na jedan status. Ako se dva kontejnera u okviru iste pošiljke kreću različito, sistem treba da omogući operateru da vidi razliku, umesto da prikaže naizgled potpunu prekretnicu na nivou pošiljke.

Pre procene API-ja identifikujte reference koje vaše poslovanje zaista prima:

Povežite se sa više od 3.500 prevoznika širom sveta putem jednog API-ja za jednostavno, precizno i pouzdano praćenje paketa. Isprobajte besplatno

• Broj kontejnera: Identifikuje opremu, ali treba da bude povezan sa odgovarajućom pošiljkom ili putovanjem jer se kontejneri ponovo koriste.
• Referenca rezervacije kod prevoznika: Može povezati zahtev za praćenje sa rezervacijom, u zavisnosti od zahteva izvornog sistema za pretragu.
• Referenca transportnog dokumenta: Može identifikovati pošiljku na nivou pomorskog prevoznika. Proverite da li API prihvata reference dokumenata koje vaš tim poseduje.
• Interni ID pošiljke: Povezuje spoljne zapise praćenja sa vašim sistemom za upravljanje transportom, ERP-om ili softverom za špediciju.

Ne pretpostavljajte da se referenca kućnog tovarnog lista koju je izdao špediter može koristiti svuda gde je potrebna referenca dokumenta pomorskog prevoznika. Testirajte tačne identifikatore dostupne u vašim tokovima rezervacija i dokumenata.

Koje događaje kontejnera API treba da izloži?

Standardi Digital Container Shipping Association za Track & Trace predstavljaju korisnu referencu za razgovor o podacima pomorskih pošiljaka. DCSA razlikuje događaje pošiljke, transporta i opreme. Ove kategorije pomažu da se odvoje administrativni napredak, kretanje transporta i rukovanje fizičkim kontejnerom.

Dobavljač ne mora da koristi vaše omiljene nazive polja da bi bio koristan, ali treba da objasni kako se njegov model događaja mapira na operativne prekretnice koje su vam potrebne.

Događaji opreme: šta se dogodilo kontejneru

Relevantne prekretnice opreme mogu obuhvatati ulazak kroz kapiju, utovar, iskrcavanje, izlazak kroz kapiju i kretanje praznog kontejnera. Dostupnost zavisi od putovanja, izvora i proizvoda. Zahtevajte uzorke zapisa umesto da pretpostavljate da je svaki događaj dostupan na svakom terminalu.

Ove razlike imaju praktične posledice. Dolazak broda ne dokazuje da je određeni kontejner iskrcan. Iskrcavanje ne dokazuje da je kontejner oslobođen ili spreman za preuzimanje. Zapis o izlasku kroz kapiju takođe zahteva lokaciju i kontekst: izlazak iz objekta za pretovar nije isti poslovni ishod kao preuzimanje sa konačnog uvoznog terminala.

Transportni događaji: gde se nalaze brod ili transportna deonica

Događaji dolaska i odlaska opisuju transportnu aktivnost. Za njihovo tumačenje sistemu su potrebni povezana lokacija, način transporta i deonica. Kada su dostupni, identifikatori broda i putovanja pomažu da se razlikuje planirano putovanje od drugog kretanja između istih luka.

Kod tereta u pretovaru sačuvajte međustanice. Svođenje rute na polazište i odredište može sakriti propuštenu vezu ili promenu rute. Operativna vremenska linija treba da omogući uvid u to koja je deonica završena, a koja se još procenjuje.

Događaji pošiljke: administrativni napredak nije fizičko kretanje

Događaji obrade dokumenata i pošiljke mogu biti korisni za špediterske tokove, ali moraju ostati razdvojeni od kretanja kontejnera. Administrativna prekretnica ne potvrđuje da se teret fizički pomerio, a događaj kretanja ne potvrđuje da su ispunjeni svi komercijalni ili regulatorni zahtevi.

Za svaki događaj zatražite tip događaja, relevantni objekat, lokaciju, vremensku oznaku događaja, informacije o vremenskoj zoni, izvor i pokazatelj da li je događaj planiran, procenjen ili stvaran. Zatražite i stabilan identifikator događaja i ponašanje pri ispravkama kako ponovljena ažuriranja ne bi stvarala duple prekretnice.

ETA podacima su potrebni odredište, značenje i istorija

ETA je procenjeno vreme dolaska na određenu tačku. Ono samo po sebi nije obećanje da će teret biti dostupan za preuzimanje. API za praćenje pomorskog transporta treba jasno da navede odredišnu prekretnicu, umesto da vraća neodređeno polje označeno samo kao eta.

Na primer, procena dolaska može se odnositi na uplovljavanje u luku, terminal, kopneni objekat ili drugo definisano odredište. Pre nego što je upotrebite za zakazivanje kamiona ili obećanje dostupnosti zaliha, utvrdite šta tačno ta vremenska oznaka predstavlja.

Odvojite izvor procene od njenog statusa

Procena koju je dostavio prevoznik i predviđanje koje je generisao dobavljač predstavljaju različite proizvode podataka. Nijedno ne treba predstavljati kao stvarni dolazak. Pitajte da li odgovor identifikuje poreklo procene, vreme njenog izračunavanja ili objavljivanja i lokaciju ili događaj koji predviđa.

Ako dobavljač nudi prediktivni ETA, zatražite njegovu metodologiju i pristup validaciji. Korisna pitanja obuhvataju koja se prekretnica predviđa, koliko pre dolaska se meri učinak i da li se rezultati razlikuju na rutama koje koristite. Opštu tvrdnju o preciznosti teško je primeniti kada ciljni događaj i period merenja nisu navedeni.

Čuvajte izmene ETA umesto da ih prepisujete

Najnoviji ETA podržava današnje planiranje, a istorija izmena objašnjava šta se promenilo. Sačuvajte prethodnu procenu, novu procenu, povezanu prekretnicu, izvor i vreme kada je vaš sistem primio izmenu.

Ova istorija omogućava operativnom timu da razlikuje značajno kašnjenje od ispravke formata ili promene nepovezanog uplovljavanja u luku. Takođe podržava naknadnu procenu bez pretvaranja da je konačna procena bila poznata ranije tokom putovanja.

Vremenske zone zahtevaju izričito testiranje. Sačuvajte izvornu vremensku oznaku i njen pomak kada su dostavljeni, normalizujte vremenske oznake za izračunavanje i prikazujte lokalno operativno vreme kada je to odgovarajuće. Ako izvor pruža samo datum, nemojte ga tiho pretvarati u precizno obećanje dolaska u ponoć.

Procenjujte pokrivenost na nivou događaja

Prisustvo prevoznika na listi pokrivenosti samo po sebi ne potvrđuje da je dostupna svaka prekretnica kontejnera. Pokrivenost treba testirati u odnosu na prevoznike, rute, reference pošiljaka i operativne događaje važne za vaše poslovanje.

Napravite matricu procene sa stvarnim zahtevima. Za svaku reprezentativnu pošiljku proverite da li API može da razreši referencu, vrati ispravnu rutu, izloži potrebne prekretnice i održava ažuriranja kroz deo putovanja kojim upravljate.

• Direktna pomorska kretanja: Možete li identifikovati polazak iz izvora, dolazak na odredište i relevantne događaje rukovanja kontejnerom?
• Pretovarna kretanja: Da li su međudeonice vidljive i mogu li kontejneri koji se kreću odvojeno ostati razdvojeni?
• Kopnene deonice: Ako ih vaša usluga obuhvata, da li API pruža relevantne železničke, baržne ili kamionske prekretnice ili vidljivost prestaje u luci?
• Izuzeci: Kako se predstavljaju nedostajući događaji, promenjene rute, nepovezane reference i prekidi izvora?
• Završene pošiljke: Može li vaš tim da preuzme dovoljno istorijskih podataka za ispitivanje spora sa korisnikom ili usklađivanje operativnog zapisa?

Nedostupne podatke držite odvojeno od negativnih događaja. Nepostojanje zapisa o iskrcavanju ne dokazuje da se iskrcavanje nije dogodilo. Korisna integracija razlikuje izričit operativni status od praznine u vidljivosti.

Ponašanje API-ja važno je koliko i lista događaja

Čak i bogat tok događaja može postati težak za rad ako ponašanje isporuke nije jasno. Procenite kako vaša aplikacija prima ažuriranja, obrađuje ispravke i oporavlja se nakon prekida rada.

Polling, webhook-ovi i oporavak

Polling omogućava aplikaciji da zahteva ažuriranja prema sopstvenom rasporedu. Webhook-ovi omogućavaju dobavljaču da šalje ažuriranja na endpoint kojim upravljate. Nijedan mehanizam sam po sebi ne garantuje ažurnost: webhook isporučen odmah i dalje može sadržati izvorni događaj primljen sa zakašnjenjem.

Zatražite odvojene definicije vremena izvornog događaja, vremena prijema kod dobavljača i vremena obaveštavanja kada su dostupne. Kod webhook-ova potvrdite autentifikaciju ili proveru potpisa, ponovne pokušaje, ponašanje pri duploj isporuci i mogućnost ponovnog slanja neuspešnih obaveštenja. Kod polling-a proverite paginaciju, ograničenja brzine, inkrementalno preuzimanje i obradu istorijskih ispravki.

Normalizacija bez gubitka dokaza

Normalizovani statusi olakšavaju tokove između prevoznika, ali preterano pojednostavljivanje uklanja koristan kontekst. Dajte prednost modelu koji omogućava da uz normalizovani događaj zadržite originalni opis ili kod izvora kada su dostupni.

Sirove ulazne zapise čuvajte odvojeno od poslovnih pravila koja ih pretvaraju u statuse kontrolne table. Tako možete promeniti mapiranje bez gubitka prvobitnih dokaza. To takođe olakšava ispitivanje statusa namenjenog korisniku kada se razlikuje od tumačenja operativnog tima.

Komercijalne provere i upravljanje

Zatražite pisano objašnjenje obračunske jedinice. Pretplata, praćena pošiljka, kontejner, API zahtev i obaveštenje nisu međusobno zamenljive mere. Razjasnite kako ponovni pokušaji, duple registracije, istorijske pretrage i ponovo aktivirane pošiljke utiču na troškove, umesto da pretpostavite određeni model naplate.

Takođe proverite zadržavanje podataka, kontrole pristupa, rotaciju akreditiva, dozvoljenu dalju upotrebu, eskalaciju podrške i obaveze u vezi sa uslugom. Ugovorne garancije posmatrajte odvojeno od demonstracija proizvoda i marketinških izjava.

Ne pretpostavljajte da opšti API za praćenje ispunjava zahteve pomorskog transporta

API za praćenje treba izabrati na osnovu proverenog modela podataka, a ne naziva kategorije. Ažuriranja isporuke paketa i vidljivost pomorskih kontejnera mogu podržavati različite tokove, čak i kada se oba opisuju kao praćenje pošiljaka.

Ako je 17TRACK već na vašoj listi kandidata za integraciju, koristite zvaničnu stranicu Tracking API-ja i API dokumentaciju kao početne tačke za proveru zahteva. Potvrdite tačne pomorske reference, događaje kontejnera, transportne deonice i ETA polja koja vaša aplikacija zahteva pre nego što bilo koju opštu integraciju praćenja smatrate rešenjem za pomorski transport. Ovaj vodič ne potvrđuje te specifične pomorske mogućnosti za 17TRACK.

Isti standard prihvatanja treba primeniti na svakog kandidata: demonstrirati potrebne podatke na reprezentativnim pošiljkama i objasniti ograničenja. Širi tok praćenja prevoznika može biti koristan drugde u lancu snabdevanja, a da ne zameni specijalizovani tok događaja kontejnera.

Sprovedite dokaz koncepta usmeren na operativne odluke

Najbolji dokaz koncepta počinje od odluka koje vaš tim treba da donese, a ne od demonstracije kontrolne table. Izaberite reprezentativne pošiljke iz sopstvenog poslovanja, uključujući jednostavna putovanja i složene slučajeve koji stvaraju ručni rad.

1. Definišite kriterijume prihvatanja. Pre testiranja navedite potrebne reference, događaje, lokacije, značenje vremenskih oznaka i prihvatljiv način obrade nedostajućih podataka.
2. Potvrdite identitet. Proverite da svaki rezultat pripada namenjenoj pošiljci i putovanju kontejnera. Kada je relevantno, uključite ponovo korišćenu opremu i rezervacije sa više kontejnera.
3. Uporedite sa izvornim zapisima. Proverite vraćene prekretnice u odnosu na dostupne zapise prevoznika ili terminala, uzimajući u obzir razlike u vremenu ažuriranja.
4. Testirajte izmene i greške. Testirajte duplirana obaveštenja, događaje van redosleda, ispravljene vremenske oznake, nedostupne izvore i prekide rada endpointa.
5. Ponovite poslovni tok. Proverite da li podaci podržavaju planiranu radnju, kao što je pregled odložene veze ili ažuriranje procene dolaznih zaliha.
6. Pregledajte nerešene praznine. Zabeležite da li svaka praznina potiče od osnovnog izvora, obrade dobavljača ili vaše integracije. Dogovorite sanaciju pre proširenja upotrebe.

Za testiranje ETA-a sačuvajte svaku prognozu po prijemu i uporedite je sa konačnim stvarnim događajem za istu prekretnicu. Nemojte procenu dolaska u luku ocenjivati u odnosu na prijem u skladištu niti kombinovati prognoze izrađene sa veoma različitim vremenom najave u jednu neobjašnjenu ocenu.

Pravilo izbora je jednostavno: izaberite integraciju koja dokazivo podržava vaše potrebne odluke pomoću događaja koji se mogu pratiti, razumljivih procena i ponašanja isporuke koje se može oporaviti. Ako planiranje preuzimanja zahteva i dostupnost terminala, status oslobađanja ili termine, proverite te ulaze zasebno, umesto da ih zaključujete iz dolaska broda.

Česta pitanja

Da li mogu da pratim pomorsku pošiljku koristeći samo broj kontejnera?

To zavisi od izvora podataka i API-ja. Neki tokovi mogu zahtevati i identifikator prevoznika, referencu rezervacije ili referencu transportnog dokumenta. Pošto se oprema ponovo koristi, potvrdite da vraćeni događaji pripadaju vašem namenjenom putovanju, umesto da se oslanjate samo na broj kontejnera.

Da li stvarni dolazak broda znači da je moj kontejner spreman za preuzimanje?

Ne. Dolazak broda, iskrcavanje kontejnera, dostupnost tereta i dozvola za preuzimanje predstavljaju odvojene operativne činjenice. U zavisnosti od pošiljke, za preuzimanje mogu biti potrebne i informacije o oslobađanju i termin na terminalu. Proverite relevantne uslove sa stranama odgovornim za njih.

Da li AIS praćenje broda zamenjuje praćenje kontejnera?

Ne. AIS se odnosi na identifikaciju broda i informacije o njegovom kretanju; sam po sebi ne potvrđuje status utovara, iskrcavanja, oslobađanja ili izlaska kroz kapiju pojedinačnog kontejnera. Kretanje broda može pružiti kontekst, ali povezanost kontejnera sa putovanjem i dalje mora biti potvrđena.

Koliko često API za praćenje pomorskog transporta treba da se ažurira?

Ne postoji jedan koristan interval za svaki tok. Zahteve postavite prema tome koliko brzo vaš tim mora da reaguje nakon što relevantne informacije iz izvora postanu dostupne. Merite kašnjenje izvora odvojeno od kašnjenja isporuke API-ja i potvrdite šta se događa kada izvor ne objavi novi događaj.

Da li se događaji praćenja mogu koristiti za izračunavanje naknada za prekoračenje roka i zadržavanje?

Događaji mogu podržati vremensku liniju, ali ne uspostavljaju potpun obračun naknade. Potrebni su i važeći ugovorni uslovi, pravila besplatnog perioda, obračun kalendara i merodavni početni i završni uslovi. Ne izvodite iznose za plaćanje samo iz opštih prekretnica.

Izvori

• DCSA: Track & Trace standardi — Referentni okvir za događaje pošiljke, transporta i opreme u kontejnerskom transportu.
• DCSA: OpenAPI repozitorijum specifikacija — Tehnička referenca za DCSA API definicije i strukture događaja. Proverite važeću verziju specifikacije pri projektovanju integracije.
• Međunarodna pomorska organizacija: Automatski sistemi identifikacije — Osnovne informacije o AIS-u i podacima o brodu koje pruža.
• 17TRACK: Tracking API i zvanična API dokumentacija — Početne tačke za proveru pogodnosti proizvoda; ovde nisu dokaz podrške za događaje pomorskih kontejnera ili prediktivni ETA.