Skip to main content
HomeBlogGidsenEen Tracking API-integratie testen in de ontwikkelomgeving: sandbox, testnummers, nagebootste webhooks

Een Tracking API-integratie testen in de ontwikkelomgeving: sandbox, testnummers, nagebootste webhooks

17TRACK

Om een tracking-API-integratie in ontwikkeling te testen, gebruikt u drie aanvullende methoden: een sandbox van de provider of gedocumenteerde testnummers voor API-gedrag, lokale fixtures voor herhaalbare verzendscenario's en mock-webhooks voor uw ontvangende endpoint. Voer vervolgens een gecontroleerde livecontrole uit om de onderdelen te valideren die simulaties niet kunnen bewijzen, waaronder inloggegevens, abonnementsconfiguratie en daadwerkelijke gebeurtenislevering.

Een tracking-API-integratie testen in een ontwikkelingssandbox met testnummers

Deze handleiding is bedoeld voor ontwikkelaars die verzendtracking koppelen aan een e-commerceplatform, orderbeheersysteem, ERP- of klantnotificatieservice. Het doel is niet alleen een succesvolle API-respons te ontvangen. Het is de bedoeling te bewijzen dat trackingupdates de juiste orderstatus opleveren zonder dubbele berichten, verloren gebeurtenissen of onbedoeld contact met echte klanten.

Scheid het gedrag van de provider van het gedrag van de applicatie

Een trackingintegratie heeft minstens twee grenzen: verzoeken die uw applicatie naar de provider verstuurt en updates die uw applicatie daarna ontvangt of ophaalt. Een succesvol verzoek bij de eerste grens bewijst niet dat de tweede grens werkt.

Bouw het testplan rond deze grenzen in plaats van te verwachten dat één trackingnummer het volledige systeem test.

TestmethodeWat hiermee kan worden gevalideerdWat hiermee niet op zichzelf kan worden vastgesteld
Sandbox van de providerOndersteunde aanvraagformaten, authenticatie en gesimuleerd gedrag zoals beschreven door de providerBeschikbaarheid van productiegegevens van vervoerders of leveringsgedrag in productie
Gedocumenteerde testnummersDe specifieke scenario's die aan die nummers zijn toegewezenAndere statussen, vervoerders of webhookreeksen
Lokale fixtures en API-mocksUw parser, toewijzingsregels, opslag en foutafhandelingOf de echte provider verzoeken accepteert of dezelfde payload verzendt
Mock-webhookverzoekenEndpointafhandeling, validatie, deduplicatie en gevolgen voor downstreamsystemenConfiguratie van callbacks aan de providerzijde of echte leveringspogingen
Gecontroleerde live testEchte connectiviteit en de waargenomen verzendworkflowElke zeldzame fout, uitzondering of leveringsreeks

Aanbevolen aanpak: maak lokale tests deterministisch, gebruik door de provider ondersteunde tests waar beschikbaar en reserveer livezendingen voor het bevestigen van de verbinding tussen systemen.

Bevestig het providercontract voordat u fixtures schrijft

Begin met de officiële documentatie voor de API-versie die u wilt gebruiken. Bevestig de basis-URL, authenticatiemethode, registratievereisten, het responseschema, de webhookconfiguratie en alle gedocumenteerde testfaciliteiten. Ga er niet van uit dat er een aparte sandbox bestaat omdat de provider een API aanbiedt.

Gebruik voor een 17TRACK-integratie de 17TRACK Tracking API-pagina en de officiële API-documentatie als uitgangspunt. Controleer daar de toepasselijke specificaties voor verzoeken en callbacks voordat u providerspecifieke voorbeelden bouwt. De onderstaande voorbeelden zijn bewust fixtures die eigendom zijn van de applicatie en geen weergave van het 17TRACK API-schema.

Beantwoord deze vragen voordat u ontwikkelingscode met een extern account verbindt:

  • Zijn ontwikkelings- en productiegegevens voor authenticatie gescheiden, en tot welke omgeving geeft elke inloggegevens toegang?
  • Ondersteunt een sandbox callbacks of alleen request-response-tests?
  • Zijn testnummers gedocumenteerd en welke exacte resultaten leveren ze op?
  • Kunnen registraties of andere testverzoeken accountquota verbruiken of permanente records aanmaken?
  • Welke regels voor callbackauthenticatie, bevestiging, time-outs en nieuwe pogingen zijn gedocumenteerd?
  • Welke identificatoren koppelen een trackingregistratie, zending, vervoerder en callbackgebeurtenis?

Als testgedrag niet duidelijk is gedocumenteerd, vraag de provider dit dan te bevestigen. Blijf ondertussen uw eigen verwerkingslogica met mocks testen. Een niet-bevestigde sandboxmogelijkheid is een onzekerheid voor de planning, geen bewijs dat de provider die mogelijkheid niet heeft.

Bouw een geïsoleerde ontwikkelomgeving

Gebruik een afzonderlijke database of geïsoleerde tenant, aparte geheimen en synthetische orders. Stuur e-mails, sms-berichten en andere meldingen naar testbestemmingen of een notificatiesink. Een zending die in een fixture als afgeleverd is gemarkeerd, mag geen bericht naar een echte koper activeren.

Voeg een expliciete omgevingsmarkering toe aan interne records en logboeken. Bewaar providergegevens voor authenticatie op de server, buiten versiebeheer, en maskeer geheimen in vastgelegde verzoeken. Als tijdelijke publieke toegang voor callbacks nodig is, stel dan alleen de bedoelde ontwikkelroute beschikbaar en behoud de authenticatiecontroles.

Maak een kleine set bekende orders voordat u gebeurtenissen verzendt. Neem twee zendingen op die aan één order zijn gekoppeld en, als uw applicatie dit ondersteunt, dezelfde tekenreeks voor het trackingnummer onder verschillende vervoerderscontexten. Deze gevallen leggen aannames bloot dat een trackingnummer op zichzelf altijd een uniek bedrijfsrecord identificeert.

Definieer vooraf het verwachte effect van elke test: de verzendstatus, orderkoppeling, tijdlijnvermeldingen, het aantal meldingen en het auditrecord. Zo wordt een demonstratie een bewering die kan slagen of mislukken.

Gebruik testnummers alleen voor hun gedocumenteerde doel

Een trackingnummer heeft twee afzonderlijke testfuncties. Het kan worden gebruikt als invoer om registratie te valideren en het kan een zending identificeren die trackinggebeurtenissen oplevert. Een nummer dat de formatvalidatie doorstaat, biedt niet noodzakelijkerwijs een bruikbare gebeurtenisgeschiedenis.

Wanneer officiële testnummers beschikbaar zijn

Leg het door de provider vermelde scenario naast elk nummer vast. Een nummer dat is gedocumenteerd voor een afgeleverde zending mag niet worden verondersteld een uitzondering, retour of mislukte bezorgpoging te simuleren. Controleer ook of het resultaat vaststaat, in de loop van de tijd verandert of een specifieke vervoerdersselectie vereist.

Houd deze nummers in een speciale configuratie voor integratietests. Verspreid ze niet door unit-tests, waar veranderend extern gedrag anders deterministische tests onbetrouwbaar kan maken.

Wanneer officiële testnummers niet zijn bevestigd

Gebruik synthetische identificatoren binnen uw eigen applicatie en mock de providergrens. Verzin nooit een aannemelijk nummer en neem niet aan dat het voor tests is gereserveerd: het kan bij een echte zending horen.

Gebruik voor livevalidatie zendingen die u beheert en waartoe u geautoriseerde toegang hebt. Vermijd het kopiëren van trackingnummers uit openbare screenshots of klantgesprekken. Behandel verzendgeschiedenissen als mogelijk gevoelig, omdat ze locaties, tijdstippen en bezorginformatie kunnen bevatten.

Een oudere afgeleverde zending kan helpen bij het valideren van parsing, maar is een slechte afhankelijkheid voor continuous integration. De beschikbaarheid van historische gegevens en de externe respons kunnen veranderen. Bewaar een geschoonde fixture voor herhaalbare tests en houd de livecontrole apart.

Maak fixtures rond betekenisvolle verzendtransities

Bouw fixtures op basis van het gedocumenteerde schema en, indien beschikbaar, geschoonde echte responses. Houd payloadfixtures van de provider gescheiden van uw interne genormaliseerde gebeurtenismodel. Test de adapter ertussen, zodat een interne mock een defecte providerparser niet verbergt.

Een nuttige startset omvat deze scenario's:

  • Nog geen trackinggebeurtenissen: bewaar de zending zonder beweging of bezorging te claimen.
  • Onderweg: werk de tijdlijn bij en behoud de juiste orderkoppeling.
  • Uit voor bezorging: pas uw notificatiebeleid toe zonder bezorging als voltooid te behandelen.
  • Afgeleverd: leg de voltooiing vast en voer de bedoelde bedrijfsactie één keer uit.
  • Uitzondering of bezorging geprobeerd: behoud het onderscheid met een voltooide bezorging.
  • Retourbeweging: interpreteer niet elke latere scan als voortgang richting de oorspronkelijke ontvanger.
  • Onbekende status: bewaar voldoende informatie voor diagnose zonder een statusmapping te verzinnen.

Gebruik uw eigen genormaliseerde namen voor deze scenario's en koppel de gedocumenteerde waarden van de provider er vervolgens expliciet aan. Ga er niet van uit dat verschillende API's dezelfde statuslabels gebruiken of dat een label overal dezelfde zakelijke betekenis heeft.

Varieer ook de vorm van de gegevens: een lege gebeurtenislijst, ontbrekende optionele velden, aanvullende onbekende velden, Unicode-locatienamen, tijdstempels met tijdzoneverschuivingen en verkeerd gevormde verplichte waarden. Uw parser moet compatibele toevoegingen kunnen verwerken en gegevens weigeren die niet veilig kunnen worden verwerkt.

Verzend mock-webhooks via het echte ontvangstpad

Een mock-webhook moet de ontvangstroute, authenticatiemiddleware, validatie, opslag en workerverwerking testen, en niet alleen de uiteindelijke statusupdatefunctie aanroepen.

De volgende payload stelt een synthetische interne gebeurtenis voor. De veldnamen, gebeurtenis-ID en status zijn illustratief; ze vormen geen callbackcontract van een provider.

{
  "event_id": "dev-event-001",
  "shipment_id": "dev-shipment-001",
  "tracking_number": "INTERNAL-TEST-001",
  "status": "in_transit",
  "occurred_at": "2025-01-15T10:00:00Z"
}

Sla dit op als tracking-event.json en post het naar een lokale testontvanger:

curl --request POST \
  http://localhost:3000/dev/tracking-events \
  --header 'Content-Type: application/json' \
  --data-binary @tracking-event.json

Dit commando valideert alleen de lokale routering en verwerking. Het toont geen authenticatie bij de provider aan. Houd een route die alleen voor ontwikkeling bedoeld is ontoegankelijk in productie, of test de productieontvanger met de gedocumenteerde authenticatiemethode van de provider en een afzonderlijk testgeheim.

Test authenticatie zonder productiecontroles te verzwakken

Als de provider ondertekende callbacks voorschrijft, implementeer dan precies dat schema in plaats van een willekeurige handtekeningheader of een willekeurig algoritme te kiezen. Bij schema's die request-bytes ondertekenen, moet u de oorspronkelijke body bewaren voor verificatie; het parsen en opnieuw serialiseren van JSON kan die bytes wijzigen.

Test geldige authenticatie, ontbrekende inloggegevens, gemanipuleerde bodies en onjuiste handtekeningen waar van toepassing. Als het gedocumenteerde schema tijdstempels of replaybeveiliging bevat, test die regels dan ook. HMAC is een gestandaardiseerde constructie voor berichtauthenticatie, maar het bestaan ervan bewijst niet dat een bepaalde trackingprovider deze gebruikt.

Test duplicaten, volgorde en herstel

De verwerking van zendingen moet correct blijven wanneer dezelfde update herhaaldelijk binnenkomt of gebeurtenissen in een onverwachte volgorde arriveren. Dit zijn defensieve testscenario's en geen beweringen over de leveringsgarantie van een bepaalde provider.

TestVerwacht gedrag van de applicatie
Verzend dezelfde gebeurtenis twee keerBehoud één logische gebeurtenis en voorkom dubbele klantmeldingen.
Verzend een oudere transitscan na bezorgingBehoud nuttige geschiedenis zonder de bezorgstatus automatisch terug te draaien.
Verzend gelijktijdige updatesPas consistente statustransities toe ondanks gelijktijdige workers.
Stop met verwerken na duurzame ontvangstHerstel en verwerk de opgeslagen gebeurtenis zonder een nieuwe callback nodig te hebben.
Opslag mislukt voordat ontvangst duurzaam isBevestig niet ten onrechte dat de ontvangst succesvol is geaccepteerd.
Verzend een onbekende zendingVolg een gedefinieerd quarantaine- of afwijzingsbeleid; raad nooit de orderkoppeling.

Geef voor deduplicatie de voorkeur aan een gedocumenteerde stabiele gebeurtenisidentificator wanneer die wordt meegeleverd. Definieer anders een zorgvuldig afgebakende identiteit op basis van relevante velden en test botsingen. Een trackingnummer op zichzelf is geen gebeurtenisidentiteit, omdat één zending veel legitieme updates kan genereren.

Scheid de gebeurtenisgeschiedenis van de huidige verzendprojectie. Het bewaren van historische scans vereist niet dat elke laat binnenkomende scan de weergegeven status overschrijft. Ook is 'gebruik de nieuwste tijdstempel' geen volledige regel: correcties, retourstromen en verschillende betekenissen van tijdstempels vereisen expliciete verwerking.

Bevestig bij asynchrone verwerking pas nadat de gebeurtenis een duurzaam overdrachtspunt heeft bereikt, zoals een vastgelegd inboxrecord of een duurzame wachtrij, overeenkomstig uw architectuur. Volg de gedocumenteerde bevestigingsvereisten van de provider. HTTP definieert de semantiek van statuscodes, maar het schema voor nieuwe pogingen van een specifieke afzender moet uit diens eigen contract komen.

Voer een gecontroleerde livecontrole uit en stel releasecriteria vast

Registreer, zodra deterministische tests slagen, een geautoriseerde zending via de echte integratie en bevestig het volledige pad. Controleer of de provider het bedoelde record heeft geaccepteerd, of de callbackconfiguratie naar de juiste omgeving verwijst en of binnenkomende gegevens aan de verwachte zending worden gekoppeld.

Vereis niet dat elke verzendstatus tijdens die livecontrole verschijnt. Echte zendingen zijn geen beheersbare fixtures. Gebruik de livegang om connectiviteit en waargenomen compatibiliteit met het contract te valideren; gebruik herhaalbare fixtures voor zeldzame of destructieve scenario's.

Vereis vóór de release de volgende resultaten:

  • Gedocumenteerde succes- en foutresponses worden verwerkt, inclusief fouten op itemniveau als de API batchbewerkingen ondersteunt.
  • Time-outs leiden niet tot blinde nieuwe aanmaakpogingen wanneer het eerste verzoek al geslaagd kan zijn.
  • Dubbele gebeurtenissen kunnen geen dubbele bedrijfsacties aanmaken.
  • Ongeldige callbacks kunnen de verzendstatus niet wijzigen.
  • Workerfouten laten herstelbare gebeurtenissen achter in plaats van ze stilzwijgend te verliezen.
  • Ontwikkelingsverkeer kan geen echte klanten op de hoogte brengen of productieorders wijzigen.
  • Logboeken verbinden verzoeken, ontvangen gebeurtenissen, verwerkingsresultaten en meldingspogingen zonder geheimen bloot te leggen.

Een release is klaar wanneer u zowel de normale workflow als het herstel van een onzeker verzoek, een herhaalde callback of een onderbroken worker kunt uitleggen. Eén succesvolle trackingopvraging is niet voldoende.

Veelgestelde vragen

Kan ik een trackingintegratie testen zonder sandbox?

Ja. Mock de uitgaande API-grens, speel gedocumenteerde callbackfixtures opnieuw af en test uw normalisatie- en bedrijfsregels lokaal. Gebruik vervolgens een geautoriseerde livezending om daadwerkelijke connectiviteit te bevestigen. Dit biedt een aanzienlijke dekking, maar reproduceert geen ongedocumenteerd gedrag van de provider.

Waarom slaagt mijn trackingverzoek, maar worden er geen gebeurtenissen teruggegeven?

Acceptatie van een verzoek en beschikbaarheid van trackinggegevens zijn verschillende uitkomsten. Controleer de responsdetails van de provider, registratievereisten, regels voor vervoerdersidentificatie en het gedocumenteerde gedrag voor zendingen zonder gebeurtenissen. Verzin geen bewegings- of bezorginformatie om een lege tijdlijn aan te vullen.

Bewijst een succesvolle mock-webhook dat echte webhooks zullen aankomen?

Nee. Dit bewijst alleen het pad dat door de mock is getest. Echte levering hangt ook af van providerconfiguratie, publieke bereikbaarheid, TLS, authenticatie en het daadwerkelijke callbackcontract. Valideer deze met een door de provider ondersteunde testlevering of een geautoriseerde liveworkflow.

Moet ik HTTP 200 retourneren voordat de verwerking is voltooid?

Volg het gedocumenteerde bevestigingscontract van de provider. Bevestig in een asynchroon ontwerp na duurzame acceptatie en verwerk daarna in een worker. Succes retourneren vóór duurzame acceptatie kan een gebeurtenis verloren laten gaan als het proces direct daarna uitvalt.

Hoe moet ik klantmeldingen testen?

Stuur alle ontwikkelingsmeldingen naar een gecontroleerde sink. Controleer de bestemming, template, activerende transitie en het aantal verzendingen. Speel dezelfde gebeurtenis opnieuw af en simuleer nieuwe workerpogingen om te controleren of één verzendupdate geen herhaalde klantberichten genereert.

Bronnen

  • 17TRACK Tracking API — officieel uitgangspunt voor het tracking-API-product.
  • 17TRACK API-documentatie — naslagwerk voor het providerspecifieke integratiecontract; bevestig hier de toepasselijke test- en callbackvereisten.
  • RFC 9110: HTTP Semantics — semantiek van HTTP-responses en aandachtspunten voor het opnieuw proberen van verzoeken.
  • RFC 2104: HMAC — de gestandaardiseerde constructie voor berichtauthenticatie die wordt besproken in de richtlijnen voor callbackbeveiliging.