API voor het volgen van zeevracht: containerevenementen, ETA-gegevens en selectiecriteria

Een API voor het volgen van zeevracht moet containerbewegingen, transportmijlpalen en ETA-updates koppelen aan de zending die je team beheert. Voor expediteurs, importeurs en integratieteams is de belangrijkste selectiecriterium of de API betrouwbaar de juiste containerreis kan identificeren, daadwerkelijke gebeurtenissen van voorspellingen kan onderscheiden en voldoende context kan bieden om operationele beslissingen te ondersteunen. Een algemene verzendstatus of een onverklaarde aankomstdatum is niet voldoende voor het beheren van zeevracht.

Deze handleiding legt uit welke gegevens je moet opvragen, hoe je containergebeurtenissen en aankomstschattingen interpreteert en hoe je een integratie evalueert voordat je productieverkeer of inkoopbudget eraan toewijst.

Begin met het zendingmodel, niet met het tracking-scherm

Het volgen van zeevracht omvat verschillende gerelateerde objecten: een commerciële zending, de bijbehorende transportdocumenten, één of meer containers en de transporttrajecten waarin deze worden vervoerd. Deze relaties zijn belangrijk omdat één boeking meerdere containers kan omvatten, terwijl een container door verschillende schepen, terminals en binnenlandse trajecten kan worden vervoerd.

Een bruikbare integratie moet deze relaties behouden in plaats van alles samen te voegen tot één status. Als twee containers binnen dezelfde zending verschillend bewegen, moet het systeem een operator het verschil laten zien in plaats van een ogenschijnlijk complete mijlpaal op zendingniveau te tonen.

Breng voordat je een API evalueert in kaart welke referenties je bedrijf daadwerkelijk ontvangt:

• Containernummer: Identificeert het materieel, maar moet worden gekoppeld aan de relevante zending of reis omdat containers opnieuw worden gebruikt.
• Boekingsreferentie van de vervoerder: Kan het trackingverzoek koppelen aan een boeking, afhankelijk van de zoekvereisten van het bronsysteem.
• Referentie van het transportdocument: Kan de zending op het niveau van de zeevervoerder identificeren. Controleer of de API de documentreferenties accepteert die je team in bezit heeft.
• Interne zending-ID: Koppelt externe trackinggegevens aan je transportmanagementsysteem, ERP of expeditiesoftware.

Ga er niet van uit dat een door een expediteur uitgegeven house bill-referentie overal kan worden gebruikt waar een documentreferentie van een zeevervoerder vereist is. Test de exacte identificatoren die beschikbaar zijn in je boekings- en documentprocessen.

Welke containergebeurtenissen moet een API beschikbaar maken?

De Track & Trace-standaarden van de Digital Container Shipping Association bieden een nuttige referentie voor het bespreken van gegevens over zeezendingen. DCSA maakt onderscheid tussen zending-, transport- en materieelgebeurtenissen. Deze categorieën helpen administratieve voortgang, de verplaatsing van het transport en de behandeling van de fysieke container van elkaar te scheiden.

Een leverancier hoeft niet jouw voorkeursnamen voor velden te gebruiken om nuttig te zijn, maar moet wel uitleggen hoe zijn gebeurtenismodel aansluit op de operationele mijlpalen die je nodig hebt.

Materieelgebeurtenissen: wat er met de container is gebeurd

Relevante mijlpalen voor materieel kunnen bestaan uit gate-in, laden, lossen, gate-out en verplaatsingen van lege containers. De beschikbaarheid hangt af van de reis, de bron en het product. Vraag om voorbeeldrecords in plaats van aan te nemen dat elke gebeurtenis bij elke terminal beschikbaar is.

Deze onderscheidingen hebben praktische gevolgen. De aankomst van een schip bewijst niet dat een specifieke container is gelost. Het lossen bewijst niet dat de container is vrijgegeven of klaar is voor afhaling. Een gate-out-record heeft ook locatie en context nodig: gate-out bij een overslagfaciliteit is niet hetzelfde bedrijfsresultaat als afhaling bij de uiteindelijke importterminal.

Transportgebeurtenissen: waar het schip of transporttraject zich bevindt

Aankomst- en vertrekgebeurtenissen beschrijven transportactiviteiten. Om deze te interpreteren heeft je systeem de bijbehorende locatie, transportmodus en het traject nodig. Waar beschikbaar helpen scheeps- en reisidentificatoren om de bedoelde vaart te onderscheiden van een andere beweging tussen dezelfde havens.

Bewaar voor vracht met overslag de tussenstops. Door de route te beperken tot vertrekpunt en bestemming kan een gemiste aansluiting of een gewijzigde route worden verhuld. Een operationele tijdlijn moet zichtbaar maken welk traject is voltooid en welk traject nog wordt geschat.

Zendinggebeurtenissen: administratieve voortgang is geen fysieke verplaatsing

Document- en zendingverwerkingsgebeurtenissen kunnen nuttig zijn voor expeditieprocessen, maar moeten herkenbaar blijven als iets anders dan containerbeweging. Een documentmijlpaal bewijst niet dat de vracht fysiek is verplaatst, en een bewegingsgebeurtenis bewijst niet dat aan alle commerciële of wettelijke vereisten is voldaan.

Vraag voor elke gebeurtenis om het gebeurtenistype, het relevante object, de locatie, het tijdstip van de gebeurtenis, tijdzone-informatie, de bron en een aanduiding of de gebeurtenis gepland, geschat of daadwerkelijk is. Vraag ook om een stabiele gebeurtenis-ID en informatie over correcties, zodat herhaalde updates geen dubbele mijlpalen creëren.

ETA-gegevens hebben een bestemming, betekenis en geschiedenis nodig

Een ETA is een geschatte aankomsttijd op een bepaald punt. Het is niet automatisch een belofte dat de vracht beschikbaar zal zijn voor afhaling. Een API voor het volgen van zeevracht moet de bestemmingsmijlpaal expliciet maken in plaats van een onduidelijk veld te retourneren dat alleen eta heet.

Een aankomstschatting kan bijvoorbeeld betrekking hebben op een havenaanloop, een terminal, een binnenlandse faciliteit of een andere vastgelegde bestemming. Stel voordat je deze gebruikt om vrachtwagens in te plannen of voorraadbeschikbaarheid te beloven exact vast wat dit tijdstip vertegenwoordigt.

Scheid de bron van de schatting van de status

Een schatting van een vervoerder en een door een provider gegenereerde voorspelling zijn verschillende gegevensproducten. Geen van beide mag worden gepresenteerd als een daadwerkelijke aankomst. Vraag of het antwoord de oorsprong van de schatting, het tijdstip van berekening of publicatie en de locatie of gebeurtenis die wordt voorspeld identificeert.

Als een provider voorspellende ETA aanbiedt, vraag dan naar de methode en validatieaanpak. Nuttige vragen zijn onder meer welke mijlpaal wordt voorspeld, hoe lang vóór aankomst de prestaties worden gemeten en of de resultaten verschillen per route die je gebruikt. Een algemene nauwkeurigheidsclaim is moeilijk toe te passen wanneer de doelgebeurtenis en het meetvenster niet zijn gespecificeerd.

Bewaar ETA-aanpassingen in plaats van ze te overschrijven

De meest recente ETA ondersteunt de planning van vandaag; de wijzigingsgeschiedenis legt uit wat er is veranderd. Sla de vorige schatting, de nieuwe schatting, de bijbehorende mijlpaal, de bron en het tijdstip waarop je systeem de wijziging heeft ontvangen op.

Dankzij deze geschiedenis kan een operationeel team een aanzienlijke vertraging onderscheiden van een formatteringscorrectie of een wijziging van een niet-gerelateerde havenaanloop. Ook ondersteunt dit evaluaties achteraf zonder te doen alsof de definitieve schatting al eerder in de reis bekend was.

Tijdzones moeten expliciet worden getest. Bewaar het tijdstempel van de bron en de offset wanneer die worden verstrekt, normaliseer tijdstempels voor berekeningen en toon waar passend de lokale operationele tijd. Als de bron alleen een datum verstrekt, zet deze dan niet stilzwijgend om in een precieze aankomstbelofte om middernacht.

Evalueer de dekking op gebeurtenisniveau

Dat een vervoerder op een dekkingslijst staat, bewijst op zichzelf niet dat elke containermijlpaal beschikbaar is. De dekking moet worden getest aan de hand van de vervoerders, routes, zendreferenties en operationele gebeurtenissen die voor jouw bedrijf belangrijk zijn.

Maak een evaluatiematrix met je werkelijke vereisten. Controleer voor elke representatieve zending of de API de referentie kan oplossen, de juiste route kan retourneren, de vereiste mijlpalen beschikbaar kan maken en updates kan blijven leveren gedurende het deel van de reis dat je beheert.

• Rechtstreekse zeetransporten: Kun je vertrek uit de oorsprong, aankomst op de bestemming en relevante gebeurtenissen rond de containerbehandeling identificeren?
• Transporten met overslag: Zijn tussenliggende trajecten zichtbaar en blijven containers die afzonderlijk bewegen van elkaar te onderscheiden?
• Binnenlandse trajecten: Als je service deze omvat, levert de API dan relevante mijlpalen voor spoor, binnenvaart of vrachtwagens, of eindigt de zichtbaarheid in de haven?
• Uitzonderingen: Hoe worden ontbrekende gebeurtenissen, gewijzigde routes, niet-overeenkomende referenties en onderbrekingen bij de bron weergegeven?
• Voltooide zendingen: Kan je team voldoende historische gegevens ophalen om een klantgeschil te onderzoeken of een operationeel record te controleren?

Houd niet-beschikbare gegevens gescheiden van negatieve gebeurtenissen. Het ontbreken van een losrecord bewijst niet dat het lossen niet heeft plaatsgevonden. Een bruikbare integratie maakt onderscheid tussen een expliciete operationele status en een gebrek aan zichtbaarheid.

Het gedrag van de API is net zo belangrijk als de lijst met gebeurtenissen

Zelfs een uitgebreide gebeurtenisfeed kan moeilijk te beheren worden als het leveringsgedrag onduidelijk is. Evalueer hoe je applicatie updates ontvangt, correcties verwerkt en herstelt na een storing.

Polling, webhooks en herstel

Met polling kan je applicatie volgens een eigen schema updates opvragen. Met webhooks kan een provider updates naar een endpoint sturen dat je beheert. Geen van beide mechanismen garandeert op zichzelf actualiteit: een onmiddellijk geleverde webhook kan nog steeds een brongebeurtenis bevatten die laat is ontvangen.

Vraag waar beschikbaar om afzonderlijke definities van het tijdstip van de brongebeurtenis, het ontvangsttijdstip bij de provider en het meldingstijdstip. Bevestig bij webhooks de authenticatie of handtekeningverificatie, retries, gedrag bij dubbele levering en of mislukte meldingen opnieuw kunnen worden afgespeeld. Controleer bij polling paginering, snelheidslimieten, incrementeel ophalen en de verwerking van historische correcties.

Normalisatie zonder bewijs te verliezen

Genormaliseerde statussen maken workflows met meerdere vervoerders eenvoudiger, maar overmatige vereenvoudiging verwijdert nuttige context. Kies bij voorkeur een model waarmee je de genormaliseerde gebeurtenis kunt bewaren naast de oorspronkelijke bronbeschrijving of code, wanneer die beschikbaar is.

Bewaar onbewerkte binnenkomende records afzonderlijk van de bedrijfsregels die deze omzetten in dashboardstatussen. Zo kun je een mapping aanpassen zonder het oorspronkelijke bewijs te verliezen. Het maakt ook een klantgerichte status eenvoudiger te onderzoeken wanneer deze afwijkt van de interpretatie van een operationeel team.

Commerciële en governancecontroles

Vraag om een schriftelijke uitleg van de factureringseenheid. Een abonnement, gevolgde zending, container, API-verzoek en melding zijn geen uitwisselbare meeteenheden. Verduidelijk hoe retries, dubbele registraties, historische zoekopdrachten en opnieuw geactiveerde zendingen de kosten beïnvloeden in plaats van uit te gaan van een bepaald prijsmodel.

Bekijk ook gegevensbewaring, toegangsbeheer, het rouleren van inloggegevens, toegestaan downstreamgebruik, escalatie naar support en serviceverplichtingen. Behandel contractuele garanties afzonderlijk van productdemonstraties en marketingverklaringen.

Ga er niet van uit dat een algemene tracking-API aan de vereisten voor zeevracht voldoet

Een tracking-API moet worden geselecteerd op basis van het geverifieerde gegevensmodel, niet op basis van het categorielabel. Updates over pakketbezorging en zichtbaarheid van zeecontainers kunnen verschillende workflows ondersteunen, ook wanneer beide als het volgen van zendingen worden omschreven.

Als 17TRACK al op je shortlist voor integraties staat, gebruik dan de officiële Tracking API-pagina en de API-documentatie als startpunt voor een controle van de vereisten. Bevestig de exacte zeevaartreferenties, containergebeurtenissen, transporttrajecten en ETA-velden die je applicatie nodig heeft voordat je een algemene trackingintegratie als oplossing voor zeevracht beschouwt. Deze handleiding stelt die specifieke mogelijkheden voor zeevracht van 17TRACK niet vast.

Dezelfde acceptatienorm moet gelden voor elke kandidaat: toon de vereiste gegevens met representatieve zendingen en leg de beperkingen uit. Een bredere trackingworkflow voor vervoerders kan elders in je toeleveringsketen nuttig zijn zonder een gespecialiseerde feed voor containergebeurtenissen te vervangen.

Voer een proof of concept uit rond operationele beslissingen

De sterkste proof of concept begint met beslissingen die je team moet nemen, niet met een dashboarddemonstratie. Selecteer representatieve zendingen uit je eigen operatie, waaronder eenvoudige reizen en moeilijke gevallen die handmatig werk veroorzaken.

1. Definieer acceptatiecriteria. Specificeer vóór het testen de vereiste referenties, gebeurtenissen, locaties, tijdstempelbetekenissen en aanvaardbare verwerking van ontbrekende gegevens.
2. Valideer de identiteit. Bevestig dat elk resultaat bij de bedoelde zending en containerreis hoort. Neem hergebruikt materieel en boekingen met meerdere containers op wanneer dat relevant is.
3. Vergelijk met bronrecords. Controleer geretourneerde mijlpalen aan de hand van toegankelijke records van vervoerders of terminals en houd rekening met verschillen in updatetiming.
4. Test wijzigingen en storingen. Test dubbele meldingen, gebeurtenissen in de verkeerde volgorde, gecorrigeerde tijdstempels, niet-beschikbare bronnen en uitval van endpoints.
5. Speel een bedrijfsworkflow na. Controleer of de gegevens de beoogde actie ondersteunen, zoals het beoordelen van een gemiste aansluiting of het bijwerken van een schatting van binnenkomende voorraad.
6. Beoordeel onopgeloste hiaten. Leg vast of elk hiaat afkomstig is van de onderliggende bron, de verwerking door de provider of je integratie. Spreek herstelmaatregelen af voordat je het gebruik uitbreidt.

Bewaar voor ETA-tests elke voorspelling zoals die binnenkomt en vergelijk deze met de uiteindelijke daadwerkelijke gebeurtenis voor dezelfde mijlpaal. Beoordeel een voorspelling van aankomst in de haven niet aan de hand van ontvangst in het magazijn en combineer voorspellingen die met zeer verschillende aanlooptijden zijn gemaakt niet tot één onverklaarde score.

De selectieregel is eenvoudig: kies de integratie die aantoonbaar je vereiste beslissingen ondersteunt met traceerbare gebeurtenissen, begrijpelijke schattingen en herstelbaar leveringsgedrag. Als planning van afhaling ook terminalbeschikbaarheid, vrijgavestatus of afspraken vereist, controleer die invoer dan afzonderlijk in plaats van deze af te leiden uit de aankomst van het schip.

FAQ

Kan ik een zeezending volgen met alleen een containernummer?

Dat hangt af van de gegevensbron en de API. Voor sommige workflows kan ook een vervoerders-ID, boekingsreferentie of referentie van een transportdocument nodig zijn. Omdat materieel opnieuw wordt gebruikt, moet je bevestigen dat de geretourneerde gebeurtenissen bij de bedoelde reis horen in plaats van alleen op het containernummer te vertrouwen.

Betekent een daadwerkelijke aankomst van het schip dat mijn container klaar is voor afhaling?

Nee. Aankomst van het schip, het lossen van de container, beschikbaarheid van de vracht en toestemming om deze op te halen zijn afzonderlijke operationele feiten. Afhankelijk van de zending kan voor afhaling ook vrijgave-informatie en een terminalafspraak nodig zijn. Controleer de relevante voorwaarden bij de partijen die daarvoor verantwoordelijk zijn.

Vervangt AIS-scheepstracking het volgen van containers?

Nee. AIS heeft betrekking op identificatie en bewegingsinformatie van schepen; het stelt op zichzelf niet vast of een individuele container is geladen, gelost, vrijgegeven of via de gate is uitgeleverd. Scheepsbewegingen kunnen context bieden, maar de koppeling van de container aan de reis moet nog steeds worden bevestigd.

Hoe vaak moet een API voor het volgen van zeevracht worden bijgewerkt?

Er bestaat geen enkel interval dat voor elke workflow nuttig is. Stel vereisten vast op basis van hoe snel je team moet handelen nadat relevante broninformatie beschikbaar komt. Meet de bronlatentie afzonderlijk van de leveringslatentie van de API en bevestig wat er gebeurt wanneer de bron geen nieuwe gebeurtenis publiceert.

Kunnen trackinggebeurtenissen demurrage- of detentionkosten berekenen?

Gebeurtenissen kunnen de tijdlijn ondersteunen, maar stellen geen volledige kostenberekening vast. Je hebt ook de toepasselijke contractvoorwaarden, regels voor vrije tijd, kalenderverwerking en gezaghebbende begin- en eindvoorwaarden nodig. Leid betaalbare bedragen niet alleen af uit algemene mijlpalen.

Bronnen

• DCSA: Track & Trace-standaarden — Referentiekader voor zending-, transport- en materieelgebeurtenissen in containervervoer.
• DCSA: repository met OpenAPI-specificaties — Technische referentie voor DCSA-API-definities en gebeurtenisstructuren. Controleer de toepasselijke specificatieversie bij het ontwerpen van een integratie.
• Internationale Maritieme Organisatie: Automatic Identification Systems — Achtergrondinformatie over AIS en de scheepsinformatie die het verstrekt.
• 17TRACK: Tracking API en officiële API-documentatie — Startpunten voor het valideren van productgeschiktheid; vormen hier geen bewijs voor ondersteuning van gebeurtenissen rond oceaancontainers of voorspellende ETA.