Skip to main content
HomeBlogGidsen6 controles om de nieuwste trackinggebeurtenissen van vervoerders te verifiëren die via uw API zijn gesynchroniseerd

6 controles om de nieuwste trackinggebeurtenissen van vervoerders te verifiëren die via uw API zijn gesynchroniseerd

17TRACK

Om te controleren of je API de nieuwste trackinggebeurtenissen van de vervoerder heeft gesynchroniseerd, controleer je de verzendidentiteit, tijdstempels van gebeurtenissen, details van gebeurtenissen, bezorgroute, volgorde van gebeurtenissen en actualiteit aan de hand van een onafhankelijke trackingweergave. Een geslaagd API-antwoord of een bevestiging van een webhook bevestigt slechts één onderdeel van die keten; op zichzelf bewijst het niet dat je applicatie de nieuwste gebeurtenis van de vervoerder heeft ontvangen.

6 controles om te verifiëren dat de nieuwste trackinggebeurtenissen van de vervoerder zijn gesynchroniseerd

Deze gids is bedoeld voor ontwikkelaars en operationele teams die verantwoordelijk zijn voor het verwerken van trackinggegevens in een orderbeheersysteem, klantgerichte pagina, supporttool of waarschuwingsworkflow. Het doel is vast te stellen waar een gebeurtenis verloren is gegaan of gewijzigd, en vervolgens te bepalen of je de verwerking opnieuw moet proberen, een mapping moet corrigeren of moet wachten op nieuwe informatie van de vervoerder.

Voordat je begint: bepaal wat ‘nieuwste’ betekent

Houd drie tijdstippen gescheiden: wanneer de vervoerder zegt dat een gebeurtenis heeft plaatsgevonden, wanneer je trackingprovider deze heeft ontvangen of beschikbaar heeft gemaakt en wanneer je applicatie deze heeft opgeslagen. Deze tijdstippen kunnen verschillen. Een vervoerder kan een scan na de fysieke gebeurtenis publiceren, terwijl je integratie deze nog later kan verwerken. De nieuwste gebeurtenis op basis van het tijdstip waarop deze plaatsvond, is daarom niet noodzakelijk het meest recent ontvangen record.

Kies een vergelijkingspunt voordat je onderzoek doet. Gebruik idealiter de trackingpagina van de vervoerder of een ander geautoriseerd record van de vervoerder voor dezelfde zending. Als dat niet beschikbaar is, vergelijk je applicatie dan met het huidige API-antwoord van de trackingprovider. Deze beperktere vergelijking kan aantonen of je applicatie overeenkomt met de provider; ze kan niet aantonen dat de provider al elke scan van de vervoerder heeft. Noteer wanneer je de vergelijking hebt uitgevoerd, zodat een latere update een eerder resultaat niet inconsistent laat lijken.

1. Bevestig dat beide systemen naar dezelfde zending verwijzen

Begin met het trackingnummer, de vervoerder en eventuele account- of verzendidentificatie die door je integratie wordt gebruikt. Trackingnummers alleen zijn mogelijk onvoldoende voor probleemoplossing: een nummer kan met een typefout zijn ingevoerd, aan de verkeerde vervoerder zijn gekoppeld of na het bewerken van een bestelling opnieuw zijn gebruikt in een intern record. Een bestelnummer en een trackingnummer dienen ook verschillende doelen. Eén bestelling kan meerdere pakketten bevatten, waardoor het controleren van de nieuwste status van de bestelling een verouderd pakket kan verbergen.

  • Zoek het exacte trackingnummer en de vervoerder die naar de tracking-API zijn verzonden.
  • Bevestig welk intern verzend- of pakketrecord het antwoord heeft ontvangen.
  • Controleer of de zending na registratie is vervangen, opgesplitst, geannuleerd of opnieuw gekoppeld.
  • Vergelijk de vervoerder en het nummer in het bronrecord met die in je applicatie.

Als de identificatiegegevens niet overeenkomen, behandel het verschil dan niet langer als een synchronisatievertraging. Corrigeer eerst de koppeling en herhaal daarna de vergelijking van de gebeurtenissen. Sla voldoende identificatiegegevens op in diagnostische logs om een zending te kunnen traceren zonder gevoelige accountgegevens in die logs te plaatsen.

2. Vergelijk tijdstippen van gebeurtenissen zonder hun betekenis te verliezen

Leg voor elke mogelijke nieuwste gebeurtenis het door de vervoerder gemelde tijdstip waarop deze plaatsvond vast, evenals de vermelde tijdzone of offset indien verstrekt, en de ontvangst- en opslagtijden van je applicatie. Zet tijdstempels om naar een gemeenschappelijke tijdsbasis voor vergelijking, maar bewaar de oorspronkelijke waarde. RFC 3339 definieert een internetformaat voor tijdstempels met expliciete offsetinformatie; het is een nuttige referentie bij het ontwerpen van je eigen tijdstempelvelden. Het garandeert niet dat een vervoerder of provider voor elke gebeurtenis een tijdzone verstrekt.

Een weergave met alleen de tijd, een aangenomen lokale tijdzone of een parser die stilzwijgend een offset verwijdert, kan een gebeurtenis naar een andere kalenderdag verplaatsen of in de verkeerde volgorde plaatsen. Wanneer de bron een dubbelzinnig lokaal tijdstip geeft, markeer de vergelijking dan als onzeker in plaats van een exact UTC-moment te verzinnen. Maak ook onderscheid tussen het tijdstip waarop een gebeurtenis plaatsvond en het tijdstip van het API-antwoord: een antwoord dat nu wordt opgehaald, kan terecht een gebeurtenis bevatten die eerder heeft plaatsgevonden.

Noteer het tijdstip waarop je de weergave van de vervoerder of provider hebt gecontroleerd. Als de bron na je API-aanvraag een nieuwe scan heeft gepubliceerd, bewijst een verschil tussen de twee weergaven niet dat de eerdere aanvraag is mislukt.

3. Controleer de payload van de gebeurtenis, niet alleen de hoofdstatus

Vergelijk de beschrijving, locatie, vervoerdersstatus of -code en alle relevante bezorgvelden van de nieuwste gebeurtenis met het upstream-record. Een genormaliseerde status zoals ‘onderweg’ kan meerdere verschillende scans samenvatten. Als je applicatie alleen de samenvatting opslaat, kan deze ongewijzigd lijken terwijl er wel een nieuwe gebeurtenis is binnengekomen.

Inspecteer het onbewerkte API-antwoord of de bewaarde webhook-body waar je regels voor gegevensverwerking dit toestaan. Volg de gebeurtenis vervolgens door parsing, veldmapping, persistentie en presentatie. Let op null-velden die door standaardwaarden worden overschreven, onverwachte statuscodes die in een algemene categorie terechtkomen, afgekorte tekst of een gebruikersinterface die alleen geselecteerde gebeurtenistypen weergeeft. Een verschil in statuslabel verschilt van een ontbrekende gebeurtenis: het wijst eerder op transformatie- of weergavelogica dan op aflevering.

Leid bezorging niet uitsluitend af uit een locatie of status die definitief klinkt. Bevestig de specifieke gebeurtenis en velden waarop je workflow steunt. Omgekeerd bewijst een ongewijzigde status op hoog niveau niet dat de synchronisatie is gestopt; een nieuw ontvangen scan kan naar dezelfde categorie worden gemapt. Je diagnostische record moet zowel de upstream-gebeurtenis als de aan gebruikers getoonde waarde bewaren.

4. Traceer hoe de gebeurtenis je applicatie heeft bereikt

Als je webhooks gebruikt, controleer dan het ontvangstlog voor de relevante zending en gebeurtenis. Controleer of je endpoint het verzoek heeft geaccepteerd, of het bericht de validatie heeft doorstaan en of de daaropvolgende verwerking is voltooid. Een succesvolle HTTP-respons van je endpoint bewijst niet dat een latere queue-worker de gebeurtenis heeft opgeslagen. Als de verwerking asynchroon verloopt, onderzoek dan zowel het binnenkomende verzoek als het resultaat van de taak.

Als je een API peilt, controleer dan het laatst voltooide verzoek, de verzendidentificatie in dat verzoek, het antwoord en eventuele paginering of ophaallogica die je integratie gebruikt. Een geslaagd verzoek kan nog steeds worden gevolgd door een mislukte databasebewerking of een verouderde cachelezing. Gebruik de toepasselijke documentatie van de provider om de werkelijke antwoordvelden, authenticatievereisten en afleveringsgedragingen voor je integratie te verifiëren, in plaats van ervan uit te gaan dat elke tracking-API hetzelfde contract volgt. Voor een 17TRACK-integratie zijn de relevante startpunten de Tracking API-pagina en de API-documentatie; bevestig het gedocumenteerde gedrag voor het endpoint en de methode die je gebruikt.

Maak gebeurtenisverwerking veilig om opnieuw uit te voeren. Een nieuwe poging mag geen dubbele scans creëren, niet herhaaldelijk dezelfde klantmelding versturen en geen nieuwere opgeslagen status vervangen door een oudere payload. De juiste sleutel voor duplicaten hangt af van de velden die je provider daadwerkelijk levert. Test de gekozen sleutel met verschillende gebeurtenissen die toevallig dezelfde status of hetzelfde tijdstempel hebben; deze gebeurtenissen mogen niet worden samengevoegd alleen omdat ze op elkaar lijken.

5. Controleer regels voor volgorde en statusovergangen

Sorteer de geregistreerde gebeurtenissen volgens een duidelijk gedefinieerde regel en inspecteer daarna het resultaat. Veel applicaties moeten onderscheid maken tussen de ‘laatste gebeurtenis die plaatsvond’ en de ‘laatste gebeurtenis die we hebben ontvangen’. Een vertraagde eerdere scan kan na een nieuwere scan binnenkomen. Als je database eenvoudigweg het laatst verwerkte bericht als de huidige verzendstatus instelt, kan die vertraagde scan de weergegeven status terugzetten.

Vergelijk je opgeslagen geschiedenis met de upstream-geschiedenis, niet alleen het ene statusveld. Vraag na of een nieuw ontvangen record is toegevoegd, als duplicaat is verwijderd of de huidige status mocht bijwerken. Controleer regels die bepaalde gebeurtenissen voorrang geven boven andere. Zo’n regel kan opzettelijk zijn, maar mag de onderliggende gebeurtenis niet verbergen of suggereren dat de vervoerder een mijlpaal heeft teruggedraaid wanneer de applicatie slechts laat een oudere scan heeft ontvangen.

Voer voor een praktische test een zending met meer dan één gebeurtenis opnieuw uit in een andere volgorde van aankomst in een niet-productieomgeving. Bevestig dat de gebeurtenissengeschiedenis intact blijft en dat de klantgerichte status je gedocumenteerde regel volgt. Hiermee ontdek je volgordefouten die een normale test met gebeurtenissen in de juiste volgorde niet aan het licht brengt.

6. Meet actualiteit en verwerk uitzonderingen

Vergelijk ten slotte wat elke laag op hetzelfde observatiemoment wist: de weergave van de vervoerder, het antwoord van de trackingprovider, het binnenkomende webhook- of pollresultaat, het databaserecord en de klantgerichte uitvoer. Markeer de eerste laag waar de verwachte gebeurtenis verdwijnt. Die grens is nuttiger dan een algemeen rapport dat ‘tracking vertraagd is’.

Meet zowel de ouderdom van de nieuwste door de vervoerder gemelde gebeurtenis als de tijd sinds je integratie voor het laatst succesvol gegevens heeft gecontroleerd of ontvangen. Ze beantwoorden verschillende vragen. Een pakket kan geen nieuwe scan van de vervoerder hebben, ook al is je integratie gezond; omgekeerd kan de vervoerder een nieuwe scan tonen terwijl je laatste geslaagde verzoek oud is. Gebruik waarschuwingsdrempels die aansluiten bij je eigen operationele vereisten en het gedrag dat je hebt waargenomen. Beloof klanten geen vast update-interval tenzij je afspraken met vervoerders en providers dit ondersteunen.

Maak een kleine reconciliatiequeue voor zendingen waarvan de records verschillen van de gekozen vergelijkingsbron. Neem identificatiegegevens, de ontbrekende of afwijkende gebeurtenis, relevante tijdstempels, de eerste falende laag en de volgende actie op. Een gebeurtenis die wel in het providerantwoord staat maar niet in je database, vereist bijvoorbeeld onderzoek naar de integratie. Een gebeurtenis die wel in je database staat maar ontbreekt op de trackingpagina, vereist controle van weergave of caching. Als de vervoerder zelf geen nieuwe scan toont, kan een extra API-aanvraag er geen maken.

De operationele test is eenvoudig: kun je dezelfde zending identificeren, de laatst bekende upstream-gebeurtenis vinden en die gebeurtenis helemaal tot aan de gebruikersweergave volgen zonder de betekenis ervan te wijzigen? Zo niet, dan beperken de zes controles het probleem tot een specifieke grens en geven ze je team een verdedigbare volgende stap.

Veelgestelde vragen

Betekent een succesvolle webhook-respons dat de nieuwste gebeurtenis is gesynchroniseerd?

Nee. Dit toont aan dat je endpoint een succesvolle respons op een verzoek heeft teruggestuurd. Bevestig ook dat validatie, queue-verwerking, databaseopslag en weergave zijn geslaagd. Controleer de payload om vast te stellen welke gebeurtenis het verzoek bevatte.

Waarom toont de pagina van de vervoerder een nieuwere scan dan mijn API-antwoord?

Bevestig eerst dat je hetzelfde pakket bekijkt en dat beide waarnemingen op vergelijkbare tijdstippen zijn gedaan. De publicatie door de vervoerder en de ontvangst of beschikbaarstelling van een gebeurtenis door de trackingprovider kunnen op verschillende tijdstippen plaatsvinden. Als het verschil blijft bestaan, gebruik dan de documentatie en supportprocedure van de provider om de specifieke zending te onderzoeken in plaats van uit te gaan van een updategarantie.

Moet ik het tijdstempel van de gebeurtenis of het tijdstip waarop mijn systeem deze heeft ontvangen gebruiken om de nieuwste status te kiezen?

Gebruik een gedocumenteerde regel die geschikt is voor je workflow en bewaar beide waarden. Het tijdstempel van de gebeurtenis beschrijft wanneer de gemelde activiteit plaatsvond; de ontvangsttijd beschrijft wanneer je systeem hiervan op de hoogte raakte. Geen van beide velden lost elk geval afzonderlijk op, vooral niet wanneer brontijden dubbelzinnig zijn of eerdere scans laat binnenkomen.

Wat als de API-status ongewijzigd is maar de gebeurtenissenlijst een nieuwe invoer bevat?

Dat kan verwacht zijn als meerdere gebeurtenissen van de vervoerder naar één genormaliseerde status worden gemapt. Vergelijk de details van de gebeurtenis en controleer of je applicatie de nieuwe invoer heeft opgeslagen en waar nodig weergeeft. Behandel een ontbrekende gebeurtenis en een ongewijzigd samenvattend label als verschillende problemen.

Bronnen