API de urmărire a transportului maritim: evenimente ale containerelor, date ETA și criterii de selecție

Un API de urmărire a transportului maritim ar trebui să conecteze mișcările containerelor, etapele transportului și actualizările ETA la expedierea gestionată de echipa dumneavoastră. Pentru expeditorii de mărfuri, importatori și echipele de integrare, criteriul de selecție este dacă acesta poate identifica în mod fiabil călătoria corectă a containerului, poate distinge evenimentele reale de prognoze și poate oferi suficient context pentru a susține deciziile operaționale. Un statut generic al expedierii sau o dată de sosire neexplicată nu sunt suficiente pentru gestionarea transportului maritim.

Acest ghid explică ce date trebuie solicitate, cum trebuie interpretate evenimentele containerelor și estimările de sosire și cum trebuie evaluată o integrare înainte de direcționarea traficului de producție sau alocarea bugetului pentru achiziții.

Începeți cu modelul expedierii, nu cu ecranul de urmărire

Urmărirea transportului maritim implică mai multe obiecte asociate: o expediere comercială, documentele sale de transport, unul sau mai multe containere și segmentele de transport care le transportă. Aceste relații sunt importante deoarece o singură rezervare poate implica mai multe containere, iar un container poate trece prin mai multe nave, terminale și segmente terestre.

O integrare utilă trebuie să păstreze aceste relații, nu să aplatizeze totul într-un singur statut. Dacă două containere din cadrul aceleiași expedieri se deplasează diferit, sistemul ar trebui să permită operatorului să vadă diferența, în loc să prezinte o etapă aparent completă la nivelul expedierii.

Înainte de evaluarea unui API, identificați referințele pe care le primește efectiv compania dumneavoastră:

• Numărul containerului: Identifică echipamentul, dar ar trebui asociat cu expedierea sau călătoria relevantă, deoarece containerele sunt reutilizate.
• Referința rezervării transportatorului: Poate conecta solicitarea de urmărire la o rezervare, în funcție de cerințele de căutare ale sistemului sursă.
• Referința documentului de transport: Poate identifica expedierea la nivelul transportatorului maritim. Confirmați dacă API-ul acceptă referințele documentelor deținute de echipa dumneavoastră.
• ID-ul intern al expedierii: Conectează înregistrările externe de urmărire la sistemul dumneavoastră de gestionare a transportului, ERP sau software-ul de expediere.

Nu presupuneți că o referință de conosament house emisă de un expeditor poate fi utilizată oriunde este necesară o referință de document a transportatorului maritim. Testați identificatorii exacți disponibili în fluxurile dumneavoastră de rezervare și documentare.

Ce evenimente ale containerului ar trebui să ofere un API?

Standardele Track & Trace ale Digital Container Shipping Association oferă un punct de referință util pentru discutarea datelor despre expedierile maritime. DCSA diferențiază evenimentele expedierii, ale transportului și ale echipamentului. Aceste categorii ajută la separarea progresului administrativ, a deplasării transportului și a manipulării containerului fizic.

Un furnizor nu trebuie să utilizeze denumirile de câmpuri preferate de dumneavoastră pentru a fi util, dar ar trebui să explice cum se corelează modelul său de evenimente cu etapele operaționale de care aveți nevoie.

Evenimentele echipamentului: ce s-a întâmplat cu containerul

Etapele relevante ale echipamentului pot include intrarea în terminal, încărcarea, descărcarea, ieșirea din terminal și deplasarea containerelor goale. Disponibilitatea depinde de călătorie, sursă și produs. Solicitați înregistrări de exemplu, în loc să presupuneți că fiecare eveniment este disponibil în fiecare terminal.

Aceste distincții au consecințe practice. Sosirea navei nu dovedește că un anumit container a fost descărcat. Descărcarea nu dovedește că containerul a fost eliberat sau că este pregătit pentru ridicare. O înregistrare de ieșire din terminal necesită, de asemenea, locație și context: ieșirea dintr-o facilitate de transbordare nu are același rezultat comercial ca ridicarea din terminalul final de import.

Evenimentele transportului: poziția navei sau a segmentului de transport

Evenimentele de sosire și plecare descriu activitatea de transport. Pentru a le interpreta, sistemul dumneavoastră are nevoie de locația asociată, modul de transport și segmentul de transport. Atunci când sunt disponibile, identificatorii navei și ai voiajului ajută la diferențierea plecării planificate de o altă deplasare care deservește aceleași porturi.

Pentru mărfurile transbordate, păstrați opririle intermediare. Reducerea itinerarului la origine și destinație poate ascunde o conexiune ratată sau o modificare a rutei. O cronologie operațională ar trebui să permită vizualizarea segmentului finalizat și a celui care rămâne estimat.

Evenimentele expedierii: progresul administrativ nu reprezintă deplasarea fizică

Evenimentele privind documentele și procesarea expedierii pot fi utile pentru fluxurile de expediere, dar ar trebui să rămână distincte de deplasarea containerului. O etapă documentară nu stabilește faptul că marfa s-a deplasat fizic, iar un eveniment de deplasare nu stabilește faptul că toate cerințele comerciale sau de reglementare au fost îndeplinite.

Pentru fiecare eveniment, solicitați tipul evenimentului, obiectul relevant, locația, marca temporală a evenimentului, informațiile privind fusul orar, sursa și o indicație dacă evenimentul este planificat, estimat sau real. Solicitați, de asemenea, un identificator stabil al evenimentului și comportamentul la corectare, astfel încât actualizările repetate să nu creeze etape duplicate.

Datele ETA au nevoie de o destinație, un înțeles și un istoric

Un ETA este timpul estimat de sosire într-un punct specificat. Nu reprezintă în mod implicit o promisiune că marfa va fi disponibilă pentru ridicare. Un API de urmărire a transportului maritim ar trebui să precizeze clar etapa de destinație, în loc să returneze un câmp ambiguu denumit doar eta.

De exemplu, o estimare a sosirii se poate referi la o escală în port, un terminal, o facilitate terestră sau o altă destinație definită. Înainte de a o utiliza pentru programarea camioanelor sau pentru promisiuni privind disponibilitatea stocului, stabiliți exact ce reprezintă marca temporală.

Separați sursa estimării de statutul acesteia

O estimare furnizată de transportator și o predicție generată de furnizor sunt produse de date diferite. Niciuna nu ar trebui prezentată ca o sosire reală. Întrebați dacă răspunsul identifică originea estimării, momentul calculării sau publicării acesteia și locația sau evenimentul pe care îl prezice.

Dacă un furnizor oferă ETA predictiv, solicitați metodologia și abordarea de validare. Întrebările utile includ etapa care este prezisă, cu cât timp înainte de sosire este măsurată performanța și dacă rezultatele diferă între rutele utilizate. O afirmație generală privind precizia este dificil de aplicat atunci când evenimentul țintă și intervalul de măsurare nu sunt specificate.

Păstrați revizuirile ETA în loc să le suprascrieți

Cel mai recent ETA susține planificarea de astăzi; istoricul revizuirilor explică ce s-a schimbat. Stocați estimarea anterioară, estimarea nouă, etapa asociată, sursa și momentul în care sistemul dumneavoastră a primit modificarea.

Acest istoric permite echipei operaționale să distingă o întârziere semnificativă de o corectare de formatare sau de o modificare a unei escale fără legătură. De asemenea, permite evaluarea retrospectivă fără a pretinde că estimarea finală era cunoscută mai devreme în călătorie.

Fusurile orare necesită testare explicită. Păstrați marca temporală sursă și decalajul acesteia atunci când sunt furnizate, normalizați mărcile temporale pentru calcule și afișați ora operațională locală atunci când este adecvat. Dacă sursa oferă doar o dată, nu o convertiți în mod silențios într-o promisiune precisă de sosire la miezul nopții.

Evaluați acoperirea la nivel de eveniment

Faptul că un transportator apare pe o listă de acoperire nu stabilește, de unul singur, că fiecare etapă a containerului este disponibilă. Acoperirea trebuie testată în raport cu transportatorii, rutele, referințele expedierilor și evenimentele operaționale importante pentru compania dumneavoastră.

Construiți o matrice de evaluare cu cerințele reale. Pentru fiecare expediere reprezentativă, verificați dacă API-ul poate identifica referința, returna itinerarul corect, furniza etapele necesare și menține actualizările pe durata segmentului de călătorie pe care îl gestionați.

• Deplasări maritime directe: Puteți identifica plecarea de la origine, sosirea la destinație și evenimentele relevante de manipulare a containerului?
• Deplasări cu transbordare: Sunt vizibile segmentele intermediare și pot rămâne distincte containerele care se deplasează separat?
• Segmente terestre: Dacă serviciul dumneavoastră le include, API-ul oferă etape relevante pentru transportul feroviar, fluvial sau rutier sau vizibilitatea se încheie la port?
• Excepții: Cum sunt reprezentate evenimentele lipsă, rutele modificate, referințele care nu corespund și întreruperile sursei?
• Expedieri finalizate: Poate echipa dumneavoastră să recupereze suficiente date istorice pentru a investiga o dispută cu un client sau pentru a reconcilia o înregistrare operațională?

Păstrați datele indisponibile separat de evenimentele negative. Lipsa unei înregistrări de descărcare nu dovedește că descărcarea nu a avut loc. O integrare utilă diferențiază un statut operațional explicit de o lipsă de vizibilitate.

Comportamentul API-ului este la fel de important ca lista de evenimente

Chiar și un flux bogat de evenimente poate deveni dificil de operat dacă modul de livrare nu este clar. Evaluați modul în care aplicația primește actualizările, gestionează corecțiile și se recuperează după o întrerupere.

Sondare, webhook-uri și recuperare

Sondarea permite aplicației să solicite actualizări conform propriului program. Webhook-urile permit unui furnizor să trimită actualizări către un endpoint operat de dumneavoastră. Niciun mecanism nu stabilește singur actualitatea datelor: un webhook livrat imediat poate conține în continuare un eveniment sursă primit cu întârziere.

Solicitați definiții separate pentru momentul evenimentului sursă, momentul primirii de către furnizor și momentul notificării, atunci când sunt disponibile. Pentru webhook-uri, confirmați autentificarea sau verificarea semnăturii, reîncercările, comportamentul livrărilor duplicate și posibilitatea de retransmitere a notificărilor eșuate. Pentru sondare, verificați paginarea, limitele de rată, recuperarea incrementală și modul de tratare a corecțiilor istorice.

Normalizare fără pierderea dovezilor

Stările normalizate facilitează fluxurile între transportatori, dar simplificarea excesivă elimină contextul util. Preferați un model care vă permite să păstrați evenimentul normalizat împreună cu descrierea sau codul original al sursei, atunci când acestea sunt disponibile.

Stocați înregistrările brute primite separat de regulile de afaceri care le transformă în stări afișate în tabloul de bord. Astfel puteți revizui o mapare fără a pierde dovezile originale. De asemenea, un statut destinat clienților poate fi investigat mai ușor atunci când diferă de interpretarea echipei operaționale.

Verificări comerciale și de guvernanță

Solicitați o explicație scrisă a unității de facturare. Un abonament, o expediere urmărită, un container, o solicitare API și o notificare nu sunt unități interschimbabile. Clarificați modul în care reîncercările, înregistrările duplicate, căutările istorice și expedierile reactivate afectează costurile, în loc să presupuneți un anumit model de tarifare.

Analizați, de asemenea, păstrarea datelor, controalele de acces, rotația acreditărilor, utilizarea permisă în aval, escaladarea către serviciul de asistență și angajamentele privind serviciul. Tratați garanțiile contractuale separat de demonstrațiile produsului și declarațiile de marketing.

Nu presupuneți că un API general de urmărire îndeplinește cerințele transportului maritim

Un API de urmărire ar trebui selectat pe baza modelului său de date verificat, nu a categoriei în care este încadrat. Actualizările privind livrarea coletelor și vizibilitatea containerelor maritime pot deservi fluxuri diferite, chiar dacă ambele sunt descrise drept urmărirea expedierilor.

Dacă 17TRACK se află deja pe lista scurtă pentru integrare, utilizați pagina oficială Tracking API și documentația API ca puncte de pornire pentru verificarea cerințelor. Confirmați referințele maritime exacte, evenimentele containerelor, segmentele de transport și câmpurile ETA necesare aplicației dumneavoastră înainte de a considera orice integrare generală de urmărire o soluție pentru transport maritim. Acest ghid nu stabilește aceste capabilități specifice transportului maritim pentru 17TRACK.

Același standard de acceptare ar trebui aplicat oricărui candidat: demonstrați datele necesare cu expedieri reprezentative și explicați limitările acestuia. Un flux mai larg de urmărire a transportatorilor poate fi util în alte zone ale lanțului dumneavoastră de aprovizionare fără a înlocui un flux specializat de evenimente ale containerelor.

Rulați o dovadă de concept în jurul deciziilor operaționale

Cea mai solidă dovadă de concept pornește de la deciziile pe care echipa dumneavoastră trebuie să le ia, nu de la o demonstrație a tabloului de bord. Selectați expedieri reprezentative din propria activitate, inclusiv voiaje simple și cazurile dificile care generează muncă manuală.

1. Definiți criteriile de acceptare. Specificați referințele, evenimentele, locațiile, semnificația mărcilor temporale și gestionarea acceptabilă a datelor lipsă înainte de testare.
2. Validați identitatea. Confirmați că fiecare rezultat aparține expedierii și călătoriei containerului dorite. Includeți echipamente reutilizate și rezervări cu mai multe containere, atunci când este relevant.
3. Comparați cu înregistrările sursă. Verificați etapele returnate în raport cu înregistrările accesibile ale transportatorului sau terminalului, ținând cont de diferențele de moment al actualizării.
4. Testați revizuirile și erorile. Simulați notificări duplicate, evenimente în ordine greșită, mărci temporale corectate, surse indisponibile și întreruperi ale endpoint-urilor.
5. Reluați un flux de afaceri. Verificați dacă datele susțin acțiunea dorită, cum ar fi examinarea unei conexiuni întârziate sau actualizarea unei estimări privind stocul de intrare.
6. Analizați lacunele nerezolvate. Înregistrați dacă fiecare lacună provine din sursa de bază, din procesarea furnizorului sau din integrarea dumneavoastră. Conveniți asupra remedierii înainte de extinderea utilizării.

Pentru testarea ETA, păstrați fiecare prognoză pe măsură ce sosește și comparați-o cu evenimentul real ulterior pentru aceeași etapă. Nu evaluați o prognoză de sosire în port în raport cu recepția în depozit și nu combinați într-un singur scor neexplicat prognoze realizate la intervale de timp foarte diferite înainte de sosire.

Regula de selecție este simplă: alegeți integrarea care demonstrează că susține deciziile necesare prin evenimente trasabile, estimări ușor de înțeles și un comportament de livrare recuperabil. Dacă planificarea ridicării necesită și disponibilitatea terminalului, statutul eliberării sau programări, verificați separat aceste date, în loc să le deduceți din sosirea navei.

Întrebări frecvente

Pot urmări o expediere maritimă folosind doar numărul containerului?

Depinde de sursa de date și de API. Unele fluxuri pot necesita și un identificator al transportatorului, o referință de rezervare sau o referință a documentului de transport. Deoarece echipamentele sunt reutilizate, confirmați că evenimentele returnate aparțin călătoriei dorite, în loc să vă bazați doar pe numărul containerului.

Sosirea reală a navei înseamnă că containerul meu este pregătit pentru ridicare?

Nu. Sosirea navei, descărcarea containerului, disponibilitatea mărfii și permisiunea de ridicare sunt fapte operaționale separate. În funcție de expediere, ridicarea poate necesita și informații despre eliberare și o programare la terminal. Verificați condițiile relevante cu părțile responsabile pentru acestea.

Urmărirea navei prin AIS înlocuiește urmărirea containerului?

Nu. AIS se referă la identificarea și informațiile privind deplasarea navei; acesta nu stabilește de unul singur statutul încărcării, descărcării, eliberării sau ieșirii din terminal al unui container individual. Deplasarea navei poate oferi context, dar asocierea containerului cu voiajul trebuie în continuare confirmată.

Cât de frecvent ar trebui actualizat un API de urmărire maritimă?

Nu există un singur interval util pentru fiecare flux. Stabiliți cerințele în funcție de cât de repede trebuie să acționeze echipa după ce informațiile relevante ale sursei devin disponibile. Măsurați separat latența sursei și latența livrării API-ului și confirmați ce se întâmplă atunci când sursa nu publică un eveniment nou.

Pot evenimentele de urmărire calcula costurile de staționare sau detenție?

Evenimentele pot susține cronologia, dar nu stabilesc un calcul complet al costului. Aveți nevoie și de termenii contractuali aplicabili, regulile privind perioada gratuită, tratamentul calendaristic și condițiile autorizate de început și sfârșit. Nu derivați sumele de plată doar din etape generice.

Surse

• DCSA: standarde Track & Trace — Cadru de referință pentru evenimentele expedierii, transportului și echipamentului în transportul containerizat.
• DCSA: depozitul de specificații OpenAPI — Referință tehnică pentru definițiile API DCSA și structurile evenimentelor. Verificați versiunea aplicabilă a specificației atunci când proiectați o integrare.
• Organizația Maritimă Internațională: sisteme automate de identificare — Informații de bază despre AIS și informațiile despre nave pe care le furnizează.
• 17TRACK: Tracking API și documentația oficială API — Puncte de pornire pentru validarea compatibilității produsului; nu reprezintă aici dovezi privind suportul pentru evenimente ale containerelor maritime sau ETA predictiv.