Skip to main content
HomeBlogGidsenWelke velden in de Tracking API-respons vormen een complete tijdlijn voor het volgen van een zending?

Welke velden in de Tracking API-respons vormen een complete tijdlijn voor het volgen van een zending?

17TRACK

Een volledige tijdlijn voor het volgen van een zending vereist meer dan alleen een actuele status. Bewaar voor elk trackingevent een zending-ID, een tijdstempel van het event, de eventbeschrijving of code van de vervoerder, een genormaliseerde status indien beschikbaar, en de locatie van het event wanneer die is opgegeven. Voeg context over de vervoerder en het trackingnummer toe, evenals leverings- of uitzonderingsdetails en een manier om de volgorde en updates van events te behouden. De exacte veldnamen verschillen per API; het doel is om te reconstrueren wat er is gebeurd, wanneer, waar en met welk pakket.

Welke velden in een tracking-API-response vormen een volledige tracking van een zending

Voor een ontwikkelaar die een bestelpagina, supportdashboard of logistieke workflow bouwt, is het belangrijkste onderscheid dat tussen de samenvatting van de zending en de eventgeschiedenis. Een samenvatting beantwoordt de vraag: “Wat is de laatst bekende status?” Een tijdlijn beantwoordt de vraag: “Hoe heeft de zending die status bereikt?” Beide zijn nodig, maar ze mogen niet als uitwisselbaar worden beschouwd.

Begin met de identiteit van de zending, niet met de status

Elk event moet aan de juiste zending worden gekoppeld. Een trackingnummer is vaak het uitgangspunt, maar het mag niet de enige identifier in een intern datamodel zijn. Bewaar de zending-ID of trackingrecord-ID van de API als die wordt aangeleverd, samen met je eigen order- en pakket-ID's. Leg de identifier of naam van de vervoerder vast en, waar relevant, de bestemmings- of herkomstcontext die wordt gebruikt om de zending te identificeren.

Dit is belangrijk wanneer een order meerdere pakketten bevat, een trackingnummer wordt gecorrigeerd of een overdracht een andere vervoerder of een ander referentienummer introduceert. Als een API gerelateerde trackingnummers of details over een overdracht tussen vervoerders beschikbaar stelt, sla dan de relatie op in plaats van twee geschiedenissen samen te voegen alleen omdat ze bij dezelfde order horen. Eén order kan meerdere geldige tijdlijnen voor zendingen hebben.

Op eventniveau omvat een praktische identiteitsset de referentie van de zending, de vervoerder die verantwoordelijk is voor het event indien bekend, en een stabiele event-ID die door de API wordt verstrekt of voldoende brongegevens om een herhaald event te identificeren. Ga er niet van uit dat twee scans met dezelfde status duplicaten zijn: een pakket kan hetzelfde type scan op verschillende locaties of tijdstippen ontvangen.

De responsevelden die elk event bruikbaar maken

Veldnamen zoals event_time en status hieronder beschrijven datarollen, geen universeel schema voor tracking-API's. Koppel ze aan de daadwerkelijke response die door je provider wordt gedocumenteerd.

  • Tijdstip van het event: Het tijdstip waarop de vervoerder zegt dat het event heeft plaatsgevonden. Bewaar de oorspronkelijke waarde en de bijbehorende tijdzone-informatie wanneer die wordt verstrekt. Dit is normaal gesproken de primaire tijdstempel voor een tijdlijn die aan klanten wordt getoond.
  • Eventbeschrijving of vervoerderscode: De oorspronkelijke scantekst of machineleesbare eventcode. Door de bronwaarde te behouden, blijft een genormaliseerd label controleerbaar en kunnen supportteams onbekende scans onderzoeken.
  • Genormaliseerde status: Een categorie op provider- of applicatieniveau, zoals onderweg, uit voor bezorging, bezorgd of uitzondering. Gebruik deze om events te groeperen, maar laat de oorspronkelijke scandetails er niet door vervangen.
  • Locatie: De faciliteit, stad, regio, het land of andere locatievelden die de vervoerder daadwerkelijk aanlevert. Toon alleen de precisie die in de response aanwezig is; maak van een scan op landniveau geen geïmpliceerde locatie op straatniveau.
  • Context van vervoerder en tracking: De identifier van de vervoerder, het trackingnummer en elk gerelateerd nummer dat nodig is om een overdracht uit te leggen of pakketten van elkaar te onderscheiden.
  • Eventmetadata: Een bron-event-ID, volgnummer of andere providerreferentie, indien beschikbaar. Deze velden kunnen helpen bij deduplicatie, correcties en een stabiele volgorde.

Ook wanneer sommige optionele velden ontbreken, kan er nog steeds een bruikbare tijdlijn worden opgebouwd. Een geldig event “bezorgd” kan bijvoorbeeld geen openbare bezorglocatie bevatten. De applicatie moet het bevestigde event tonen zonder een locatie of ontvanger te verzinnen.

Houd de tijd van het event gescheiden van de verwerkingstijd

Trackingsystemen kunnen verschillende tijdstempels beschikbaar stellen: wanneer een scan plaatsvond, wanneer een vervoerder deze publiceerde, wanneer een API-provider deze registreerde en wanneer je applicatie deze ontving. Deze beantwoorden verschillende vragen. Sorteer de weergegeven reis hoofdzakelijk op basis van het tijdstip waarop het event plaatsvond wanneer dat tijdstip betrouwbaar is; gebruik de ontvangsttijd om uit te leggen wanneer je systeem van het event op de hoogte raakte en om laat binnenkomende updates te detecteren.

Laat binnenkomende gegevens komen vaak genoeg voor om er in het ontwerp rekening mee te houden. Een vervoerder kan een eerdere scan publiceren nadat een latere scan al zichtbaar is. Als de applicatie elke nieuwe API-response simpelweg onderaan de pagina toevoegt, kan de resulterende tijdlijn chronologisch onjuist zijn. Vergelijk events met de opgeslagen geschiedenis en orden ze daarna volgens een gedocumenteerde regel. Als twee events hetzelfde tijdstip hebben, kan een bronvolgnummer of event-ID als tie-breaker dienen. Houd anders een deterministische interne volgorde aan zonder te beweren dat de bron een volgorde heeft vastgesteld.

Tijdzoneverwerking verdient bijzondere aandacht. Een tijdstempel met tijdzone kan voor opslag worden genormaliseerd terwijl de oorspronkelijke tijdstempel beschikbaar blijft voor weergave of onderzoek. Een tijdstempel zonder vermelde offset mag niet stilzwijgend als UTC worden geïnterpreteerd. Voor integraties die internettijdstempels accepteren of produceren, is RFC 3339 een nuttige referentie voor de weergave van tijdstempels; deze vertelt op zichzelf niet welke tijdzone een vervoerder bedoelde wanneer die in de gegevens ontbreekt.

Scheid de actuele status van de volledige geschiedenis

Veel trackingresponses bevatten zowel een actuele verzendstatus als een lijst met historische events. De actuele status is nuttig voor een compacte orderkaart, filters en meldingen. De geschiedenis is de bron voor de volgorde van scans. Maak geen nieuw historisch event aan telkens wanneer je een ongewijzigde actuele status opvraagt en verwijder oudere events niet alleen omdat het object met de actuele status volledig is.

Ga er ook niet van uit dat het laatste item in een array de nieuwste scan is. Controleer de ordeningsregels van de provider en sorteer of vergelijk dienovereenkomstig. Een response kan slechts een deel van de geschiedenis bevatten, of een integratie kan extra pagina's moeten ophalen. Als de API paginering of een geschiedenisl limiet documenteert, volg dan dat mechanisme voordat je de weergegeven reis als volledig beschrijft. Wanneer geschiedenis niet beschikbaar is, label de weergave dan als de ontvangen events in plaats van te suggereren dat er geen eerdere scans hebben plaatsgevonden.

Voor een robuuste interne representatie sla je de ruwe response of de bronvelden die nodig zijn om je interpretatie te reproduceren op naast een genormaliseerd eventrecord. Het behouden van bronwaarden is vooral waardevol wanneer een mapping verandert: je kunt oude events opnieuw verwerken zonder een vervoerder te vragen gegevens opnieuw te creëren die mogelijk niet meer kunnen worden opgehaald.

Modelleer mijlpalen, uitzonderingen en leveringsbewijs zorgvuldig

Een statuslabel is niet altijd een mijlpaal. “Onderweg” kan meerdere scans samenvatten, terwijl “uit voor bezorging” en “bezorgd” doorgaans afzonderlijke fasen vertegenwoordigen. Bouw mijlpalen op basis van gedocumenteerde eventbetekenissen in plaats van aan te nemen dat elke vervoerder identieke bewoordingen gebruikt. Als een status dubbelzinnig is, toon dan de oorspronkelijke beschrijving en voeg geen sterkere bewering toe.

Uitzonderingsevents hebben zowel een categorie als de details van de vervoerder nodig, wanneer die beschikbaar zijn. “Bezorging geprobeerd” vertelt een ander verhaal dan “In afwachting van inklaring”, ook al groepeert een applicatie beide onder een status die aandacht vereist. Bewaar redenstekst, reden en informatie over de volgende actie als afzonderlijke velden als de response deze verstrekt. Een supportmedewerker kan dan onderscheid maken tussen een tijdelijke vertraging en een event waarvoor de ontvanger actie moet ondernemen.

Ga ook zorgvuldig om met de bevestiging van levering. Als de response een event “bezorgd” bevat, registreer dan de tijdstempel en beschikbare locatie- of ontvangergegevens. Als er informatie over een leveringsbewijs wordt verstrekt, bewaar dan het type bewijs en eventuele toegangsbeperkingen die door de provider zijn gedefinieerd. Leid uit een bezorgstatus alleen geen handtekening, foto of naam van een ontvanger af. Evenzo is een geschatte bezorgdatum een voorspelling en geen voltooid event; toon deze afzonderlijk van de historische tijdlijn.

Een praktische mappingworkflow voor ontwikkelaars

  1. Bestudeer een echte response en de documentatie ervan. Identificeer het object op verzendingsniveau, de eventarray, tijdstempelformaten, statuswoordenschat en gedocumenteerde limieten of paginering. Ga er niet van uit dat voorbeeldveldnamen in een artikel overeenkomen met een productieschema.
  2. Definieer één intern eventmodel. Neem de identiteit van de zending, de bronvervoerder, het tijdstip van optreden, de oorspronkelijke statustekst of -code, de genormaliseerde categorie, de optionele locatie, de bron-eventidentifier en de ontvangsttijd op. Maak optionele velden nullable in plaats van ze met aannames te vullen.
  3. Schrijf expliciete mappingregels. Leg vast hoe elk bronveld een intern veld wordt en welke bronwaarde elke genormaliseerde status ondersteunt. Houd onbekende codes zichtbaar voor beoordeling in plaats van ze in een onnauwkeurige mijlpaal te dwingen.
  4. Vergelijk herhaalde responses. Gebruik een gedocumenteerde event-ID wanneer die beschikbaar is. Definieer anders een voorzichtige matchingsregel met stabiele bronwaarden en test deze met meerdere scans die legitiem dezelfde status hebben.
  5. Test moeilijke trajecten. Neem meerdere pakketten, late scans, gelijke tijdstempels, overdrachten tussen vervoerders, bezorgpogingen, ontbrekende locaties, gewijzigde schattingen en een bezorgd event met beperkte bevestigingsdetails op.
  6. Controleer wat de UI belooft. De tijdlijn moet waargenomen events onderscheiden van voorspellingen, onzekerheid behouden en voorkomen dat een onvolledige geschiedenis als volledig verslag van de zending wordt gepresenteerd.

Gebruik voor een integratie met de 17TRACK Tracking API de officiële API-documentatie om de daadwerkelijke responsstructuur en veldbetekenissen te bevestigen voordat je deze mapping implementeert. De veldrollen in deze handleiding zijn een implementatiechecklist en geen bewering dat 17TRACK velden met precies deze namen retourneert of dat elke vervoerder elk detail verstrekt.

Wanneer geldt een tijdlijn als volledig?

Een tijdlijn is voor je applicatie volledig wanneer elk weergegeven event aan het juiste pakket is gekoppeld, het bronevent en de bijbehorende tijd behouden blijven, bekende events consistent worden geordend en status, locatie, uitzonderingen en leveringsbevestiging alleen worden weergegeven voor zover de response dit ondersteunt. Operationele volledigheid vereist ook dat de grens van de gegevens bekend is: of de API de volledige beschikbare geschiedenis, een beperkt tijdvenster of alleen events van een bepaalde vervoerder of trackingrecord heeft geretourneerd.

De beste acceptatietest is niet het aantal ingevulde velden. Het gaat erom of een klant of supportmedewerker de reis kan lezen zonder te worden misleid. Als de applicatie kan beantwoorden wat er is gebeurd, wanneer het gebeurde, op welke zending het betrekking heeft en wat onzeker blijft, doen de responsevelden hun werk.

FAQ

Is een veld met de actuele status voldoende om een tijdlijn van een zending op te bouwen?

Nee. Een actuele status geeft een momentopname. Een tijdlijn heeft historische eventrecords nodig met tijdstempels en de context die nodig is om elk record aan de juiste zending te koppelen.

Moet ik de scant tekst van de vervoerder of alleen genormaliseerde statussen tonen?

Bewaar beide wanneer de API ze verstrekt. Genormaliseerde statussen maken de reis gemakkelijker scanbaar; oorspronkelijke beschrijvingen behouden details en helpen ongebruikelijke of vervoerderspecifieke events te verklaren.

Welke tijdstempel moet de volgorde van events bepalen?

Gebruik het tijdstip waarop het event plaatsvond wanneer de betekenis en tijdzone daarvan voldoende duidelijk zijn. Bewaar de ontvangsttijd van de API afzonderlijk en definieer een stabiele tie-breaker voor events met identieke of onzekere tijdstippen.

Wat als een trackingevent geen locatie heeft?

Toon het event zonder locatie. Ontbrekende locatiegegevens maken het event niet ongeldig, maar rechtvaardigen niet dat je een faciliteit, stad of bezorgadres afleidt.

Hoe kan ik bepalen of de API de volledige reis heeft geretourneerd?

Controleer de documentatie van de provider op het bereik van de geschiedenis, paginering en responslimieten en verifieer vervolgens hoe je integratie aanvullende events ophaalt. Als het bereik niet kan worden bevestigd, beschrijf de tijdlijn dan als de events die voor je applicatie beschikbaar zijn.

Bronnen