Welke gegevens moet een tracking-API retourneren? 12 velden naast de huidige status?
Een tracking-API moet meer retourneren dan alleen een label zoals “Onderweg”. Kijk naast de huidige status ook naar verzendings-ID's, de identiteit van de vervoerder, gedetailleerde statusinformatie, oorspronkelijke berichten van de vervoerder, gebeurtenisgeschiedenis, tijdstempels van gebeurtenissen, locaties, geschatte levertijden, uitzonderingen, overdrachten tussen vervoerders, leveringsdetails en metadata over de actualiteit van de gegevens. Samen helpen deze 12 gegevensgroepen ontwikkelaars betrouwbare workflows te bouwen en operationele teams voldoende context te geven om actie te ondernemen.

Dit is een aanbevolen responsecontract voor ontwikkelaars, technische inkopers en e-commerceoperationele teams—not een bewering dat elke vervoerder of API elk veld levert. Sommige waarden zullen terecht niet beschikbaar zijn. Een beter ontwerp maakt die hiaten expliciet in plaats van ze met aannames op te vullen.
Wat maakt trackinggegevens nuttig?
Een huidige status beantwoordt één beperkte vraag: wat is de samengevatte toestand van de zending? De status legt niet noodzakelijk uit wat er is gebeurd, wanneer het is gebeurd, of de informatie recent is of wat iemand vervolgens moet doen.
Twee zendingen kunnen bijvoorbeeld allebei “Onderweg” tonen, terwijl ze verschillende reacties vereisen. De ene kan een recente scan in een sorteercentrum hebben en geen gemeld probleem. De andere kan een onopgelost adresprobleem in de gebeurtenisgeschiedenis hebben. Een applicatie die alleen de hoofdstatus leest, kan dat onderscheid missen.
Beoordeel de response aan de hand van drie praktische taken: de zending aan de juiste bestelling koppelen, de voortgang nauwkeurig uitleggen en bepalen of actie gerechtvaardigd is. De volgende velden ondersteunen die taken. Veldnamen zijn illustratief; ze zijn geen universele standaard of schema van een specifieke provider.
12 velden om naast de huidige status te beoordelen
1. Verzendings- en tracking-ID's
De response moet de beschreven zending identificeren. Nuttige waarden zijn onder meer het ingediende trackingnummer, de trackingrecord-ID van de API en een klantreferentie die je systeem aan een fulfillment- of pakketrecord kan koppelen.
Ga er niet van uit dat één bestelling gelijkstaat aan één zending. Een bestelling kan over meerdere pakketten worden verdeeld en een vervanging kan een nieuwe zending creëren. Sla trackingrecords op pakket- of fulfillmentniveau op en koppel ze vervolgens aan de bestelling. Bewaar trackingnummers als strings, zodat opmaak en voorloopnullen niet verloren gaan.
2. Identiteit van de vervoerder
Zoek naast een leesbare vervoerdersnaam naar een stabiele vervoerders-ID. Waar beschikbaar moet de response onderscheid maken tussen een vervoerder die expliciet door je applicatie is aangeleverd en een vervoerder die via automatische detectie is geselecteerd.
De context van de vervoerder is belangrijk bij het interpreteren van een trackingnummer en de bijbehorende gebeurtenissen. Als de detectie onduidelijk is, moet je integratie dit kunnen oplossen in plaats van stilzwijgend een onzekere match als bevestigd weer te geven. Houd informatie op serviceniveau apart: een vervoerdersnaam alleen bewijst niet of een zending gebruikmaakt van een express-, post- of andere dienst.
3. Genormaliseerde statusdetails
Vraag naast de hoofdstatus om een gedocumenteerde detailcode of substatus. Een brede categorie kan een zending als uitzondering beschrijven, terwijl het detail een bezorgpoging, een adresprobleem of een douaneblokkade identificeert.
Gebruik stabiele codes voor bedrijfslogica en leesbare labels voor presentatie. Controleer hoe de provider vervoerdersgebeurtenissen naar deze codes vertaalt, inclusief de verwerking van onbekende of niet-gemapte gebeurtenissen. Een genormaliseerd label maakt verschillende vervoerdersfeeds eenvoudiger te verwerken, maar mag geen onderscheid uitwissen dat je supportteam nodig heeft.
4. Oorspronkelijke berichten en codes van de vervoerder
Bewaar de oorspronkelijke gebeurtenisbeschrijving en vervoerdersgebeurteniscode wanneer deze worden aangeleverd. Deze waarden geven supportmedewerkers context die in een genormaliseerde status kan ontbreken, vooral wanneer een vervoerder een specifieke operationele formulering gebruikt.
Houd oorspronkelijke tekst gescheiden van vertaalde of herschreven beschrijvingen. Anders kan een uitleg voor klanten worden aangezien voor de exacte bewoording van de vervoerder. Behandel tekst van vervoerders als niet-vertrouwde invoer wanneer je deze weergeeft: escapen de tekst op de juiste manier en render deze niet als uitvoerbare HTML.
5. Geschiedenis van trackinggebeurtenissen
Een bruikbare response moet de tijdlijn van de zending tonen, niet alleen de meest recente gebeurtenis. Elke gebeurtenis moet idealiter een ID, status of code, beschrijving, tijdstempel en beschikbare locatie-informatie bevatten.
Controleer of de API de volledige geschiedenis, een beperkt tijdsvenster of gepagineerde resultaten retourneert. Bepaal ook hoe correcties en dubbele waarnemingen worden weergegeven. Je applicatie mag niet aannemen dat het eerste item altijd het nieuwste is, tenzij het responsecontract die volgorde expliciet garandeert.
6. Tijdstempels van gebeurtenissen en tijdzone-informatie
Het tijdstip waarop een gebeurtenis plaatsvond verschilt van het tijdstip waarop de API deze ontving of retourneerde. Bewaar beide wanneer ze beschikbaar zijn. Dit onderscheid helpt verklaren waarom een nieuw ontvangen update iets kan beschrijven dat eerder is gebeurd.
Vraag tijdstempels op met expliciete UTC-offsets of UTC-notatie. RFC 3339 definieert een tijdstempelformaat dat geschikt is voor internetprotocollen, inclusief numerieke tijdsverschillen. Als een bron alleen lokale tijd zonder bekende offset levert, behoud die onzekerheid dan in plaats van deze stilzwijgend als UTC te behandelen. Suggereer nooit precisie tot op de seconde wanneer de onderliggende bron alleen een datum levert.
7. Locaties van gebeurtenissen en geografische gegevens van de zending
Zoek naar gestructureerde locatiecomponenten zoals plaats, regio, land en postcode wanneer deze worden aangeleverd. Bewaar ook een onbewerkte locatiestring als het omzetten ervan naar gestructureerde velden betekenis kan verliezen.
Een scanlocatie is niet noodzakelijk de actuele positie van het pakket. Evenmin is de laatst gemelde faciliteit bewijs dat het pakket zich daar nog bevindt. Klantgerichte pagina's moeten dit beschrijven als de laatst gemelde locatie. Leid geen coördinaten of exact afleveradres af uit onvolledige scantekst.
8. Geschatte leverdatum of -periode
Een veld voor geschatte levering moet aangeven of het één datum of een periode bevat, wie de schatting heeft opgesteld en wanneer deze voor het laatst is bijgewerkt. Een schatting van de vervoerder en een afzonderlijk berekende voorspelling moeten van elkaar te onderscheiden blijven.
Zet een schatting die alleen een datum bevat niet om in een precies aankomsttijdstip. Je integratie moet ook herziene of ingetrokken schattingen kunnen verwerken zonder een verouderde belofte op de trackingpagina te laten staan. Als er geen schatting bestaat, toon dan dat deze niet beschikbaar is in plaats van er een te berekenen op basis van een niet-ondersteunde aanname.
9. Reden voor uitzondering en vereiste actie
Informatie over uitzonderingen moet het probleem uitleggen en, wanneer de bron dit ondersteunt, een actie, verantwoordelijke partij of deadline aangeven. Een algemene vertragingsmelding verschilt operationeel van een verzoek om informatie van de ontvanger.
Houd gemelde feiten gescheiden van beslissingen in je eigen workflow. Je bedrijf kan bijvoorbeeld na een ingestelde periode zonder update een supporttaak openen. Dat is een interne escalatieregel en geen bewijs dat de vervoerder het pakket als verloren heeft verklaard. Genereer geen betalingsinstructies of verzoeken om gevoelige informatie op basis van onduidelijke trackingtekst.
10. Overdrachten tussen vervoerders en gerelateerde trackingnummers
Wanneer een zending tussen vervoerders wisselt, omvatten nuttige gegevens de volgende vervoerder, een gekoppeld trackingnummer en de relatie tussen de oorspronkelijke en daaropvolgende records. Dit kan helpen de continuïteit te behouden wanneer het bezorgtraject een andere identificatie gebruikt.
Behandel een gemelde overdracht als een relatie in plaats van de oorspronkelijke vervoerder te overschrijven. Voeg records niet samen alleen omdat hun bestemmingen of trackingnummers op elkaar lijken. Als de relatie niet wordt aangeleverd of anderszins bevestigd, laat deze dan onopgelost in plaats van een doorlopende reis te verzinnen.
11. Leveringsresultaat en verwijzingen naar bewijs
Wanneer een levering wordt gemeld, moet de response het geregistreerde leveringstijdstip en alle beschikbare leveringsdetails bevatten, zoals een beschrijving van een veilige plek of de categorie van de ontvanger. Een verwijzing naar een leveringsbewijs kan ook nuttig zijn wanneer de vervoerder en dienst dit beschikbaar maken.
Een status “Bezorgd” mag niet worden behandeld als bewijs dat de beoogde ontvanger het pakket persoonlijk heeft aangenomen. Handtekeningen, foto's, namen en precieze locaties kunnen persoonsgegevens bevatten. Beperk de toegang, vermijd het tonen van deze gegevens op openbare trackingpagina's en controleer eventuele autorisatie- of vervalvereisten voor links naar bewijs.
12. Actualiteit, ophaalstatus en metadata van de response
Vraag voldoende metadata op om de nieuwste gebeurtenis van de zending te onderscheiden van de meest recente succesvolle gegevensophaling. Nuttige waarden zijn onder meer de laatste succesvolle controle, de laatste mislukte poging, het tijdstip waarop de response is gegenereerd en of de geretourneerde gegevens uit de cache komen of gedeeltelijk zijn.
Een succesvolle API-aanvraag stelt op zichzelf niet vast dat de vervoerder een nieuwe scan heeft gepubliceerd. HTTP-responsesemantiek beschrijft het resultaat van de aanvraag; de voortgang van de zending staat in de applicatiegegevens. Bewaar ophaalfouten afzonderlijk van verzendingsuitzonderingen, zodat een tijdelijk verbindingsprobleem geen valse leveringsmelding wordt.
Ontbrekende gegevens hebben een vastgestelde betekenis nodig
De aanwezigheid van een veld vormt slechts een deel van het contract. Je team moet ook begrijpen wat een ontbrekende waarde betekent. Een leveringsschatting kan niet beschikbaar zijn bij de bron, nog niet zijn opgehaald of na levering niet van toepassing zijn. Die situaties mogen niet automatisch tot hetzelfde klantbericht leiden.
- Onbekend: De waarde is nog niet vastgesteld.
- Niet aangeleverd: De bron heeft de waarde niet verstrekt in de opgehaalde gegevens.
- Niet van toepassing: Het veld is niet van toepassing op dit record of deze status.
- Ophalen mislukt: Het systeem kon de relevante gegevens niet ophalen.
Dit zijn aanbevolen onderscheidingen, geen verplichte letterlijke waarden. Welke weergave je ook kiest, documenteer deze. Vermijd tijdelijke datums, lege objecten die op geldige records lijken en standaardcoördinaten die voor echte locaties kunnen worden aangezien.
De response testen voordat je integreert
Beoordeel daadwerkelijke payloads van de vervoerders, diensten en verzendroutes die je bedrijf gebruikt. Een schema kan een optioneel veld vermelden zonder te garanderen dat elke onderliggende bron dit invult. Gebruik voor een 17TRACK-integratie de officiële Tracking API-documentatie om het responsecontract te controleren, in plaats van de conceptuele veldnamen in deze handleiding te behandelen als direct bruikbare parameters.
- Stel een representatieve steekproef samen. Neem nieuw geregistreerde zendingen, actieve zendingen, bezorgpogingen, voltooide leveringen en beschikbare overdrachtsgevallen op.
- Traceer velden terug naar gebeurtenissen. Controleer of de weergegeven status, de nieuwste gebeurtenis en de leveringsdetails een consistent record beschrijven. Onderzoek afwijkingen in plaats van ze te verbergen.
- Test vertraagde en herhaalde updates. Verwerk dezelfde payload opnieuw en ontvang een oudere gebeurtenis na een nieuwere. Controleer dat geen van beide gevallen dubbele meldingen veroorzaakt of de weergegeven status onjuist terugdraait.
- Test ontbrekende en onjuist gevormde waarden. Neem ontbrekende schattingen, onbekende locaties, onbekende statuscodes en onvolledige tijdstempels op. De applicatie moet bruikbaar blijven zonder vervangende waarden te verzinnen.
- Scheid transportfouten van trackingresultaten. Een authenticatiefout, time-out of onjuist gevormde response hoort in een foutpad voor de integratie terecht te komen, niet in een workflow voor verzendingsuitzonderingen.
- Valideer de klantweergave. Controleer dat interne referenties, onbewerkte diagnostische details en persoonsgegevens niet uitlekken naar openbare pagina's of meldingen.
Controleer voor updates op basis van webhooks ook bezorgings-ID's, authenticatie, retrygedrag en replayverwerking in de documentatie van de provider. Dit zijn integratievereisten en geen feiten over de zending. Je ontvanger moet herhaalde leveringen veilig verwerken en mag niet aannemen dat de volgorde van ontvangst gelijk is aan de volgorde van gebeurtenissen.
Het acceptatiecriterium moet praktisch zijn: kan je applicatie de zending uitleggen zonder niet-ondersteunde beweringen te doen, en kan je operationele team de volgende gerechtvaardigde actie bepalen? Een kleinere, goed gedefinieerde payload kan nuttiger zijn dan een grotere response vol onverklaarde optionele waarden.
Veelgestelde vragen
Moeten alle 12 gegevensgroepen voor elke zending zijn ingevuld?
Nee. Leveringsbewijs, trackingnummers van volgende vervoerders en geschatte leverdatums zijn mogelijk niet beschikbaar of niet van toepassing. Vereis duidelijke velddefinities en voorspelbaar gedrag bij ontbrekende waarden in plaats van universele invulling. Controleer de belangrijkste velden aan de hand van je daadwerkelijke verzendmix.
Moeten we de onbewerkte response opslaan of alleen genormaliseerde velden?
Sla genormaliseerde velden op voor applicatielogica. Het bewaren van relevante bronpayloads kan ook helpen bij foutopsporing en het verwerken van mappingwijzigingen, afhankelijk van je vereisten op het gebied van privacy, beveiliging, contracten en bewaartermijnen. Beperk de toegang en bewaar geen gevoelige inhoud alleen omdat deze in een response voorkomt.
Welke tijdstempel moet de nieuwste gebeurtenis bepalen?
Gebruik de gedocumenteerde chronologie van gebeurtenissen en de regels voor de volgorde van de provider, rekening houdend met tijdzones en correcties. De ontvangsttijd geeft aan wanneer je systeem van een gebeurtenis op de hoogte raakte, niet noodzakelijk wanneer deze plaatsvond. Als tijdstempels onvolledig of tegenstrijdig zijn, behoud dan de onduidelijkheid in plaats van een precieze volgorde te claimen.
Kan een tracking-API bevestigen dat een pakket verloren is?
Behandel een verlies alleen als door de vervoerder gemeld wanneer de bron die interpretatie expliciet ondersteunt. Een lange periode zonder scans kan volgens je operationele regels aanleiding geven tot onderzoek, maar stilte alleen bewijst geen verlies. Houd “verouderde tracking” en “als verloren gemeld” als afzonderlijke concepten.
Is een status “Bezorgd” voldoende om een klantklacht te sluiten?
Niet automatisch. De status bevestigt het gemelde trackingresultaat, maar lost een geschil van de ontvanger mogelijk niet op. Beoordeel de beschikbare leveringsdetails, het account van de klant en je supportproces. Behandel een statuslabel niet als vervanging voor het onderzoeken van tegenstrijdige informatie.
Bronnen
- 17TRACK Tracking API-documentatie — de productspecifieke referentie voor het controleren van de gedocumenteerde velden en het gedrag van een integratie; de 12 bovenstaande groepen zijn redactionele aanbevelingen en geen reproductie van het schema.
- RFC 3339: Date and Time on the Internet: Timestamps — weergave van tijdstempels en conventies voor tijdsverschillen.
- RFC 9110: HTTP Semantics — semantiek van HTTP-responses, onderscheiden van bedrijfsstatus op verzendingsniveau.


