Workflow voor de Shipment Tracking API: van het registreren van een zending tot het ophalen van trackinggegevens
Een workflow voor een API voor het volgen van zendingen begint met het indienen van een trackingnummer en eventuele vereiste vervoerdersinformatie, het controleren of de registratie is geslaagd, het toestaan dat trackinggegevens beschikbaar komen en het ophalen van de status en gebeurtenisgeschiedenis van de zending. Voor een productie-integratie moeten ontwikkelaars elk trackingrecord ook aan een bestelling koppelen, gedeeltelijke fouten afhandelen, updates veilig verwerken en onderscheid maken tussen een geaccepteerde registratie en een daadwerkelijke scan door de vervoerder.
Deze handleiding legt die workflow uit voor ontwikkelaars die een ecommerceplatform, ordermanagementsysteem, magazijntoepassing of klantenservicetool koppelen. De aanbevelingen voor applicatieontwerp worden gescheiden van provider-specifieke API-vereisten. Gebruik voor een 17TRACK-integratie de officiële API-documentatie om het aanvraagschema, de authenticatie, ondersteunde bewerkingen en antwoordvelden te controleren voordat u de onderstaande voorbeelden implementeert.
Begrijp wat registratie wel en niet doet
Een zending registreren bij een trackingservice betekent dat u een identificatie indient zodat de service die zending kan volgen of beheren volgens het API-contract. Dit is niet dezelfde bewerking als het kopen van portokosten, het genereren van een verzendlabel, het boeken van een ophaling of het overdragen van een pakket aan een vervoerder.
Houd drie uitkomsten in uw applicatie afzonderlijk:
- Aanvraag ontvangen: De API heeft een antwoord op uw HTTP-aanvraag geretourneerd.
- Registratie geaccepteerd: De service heeft het afzonderlijke trackingrecord geaccepteerd voor verwerking.
- Trackinginformatie beschikbaar: De service beschikt over verzendinformatie die uw applicatie kan ophalen of ontvangen.
Deze uitkomsten mogen niet worden samengevoegd tot één enkele vlag voor “succes”. Een geaccepteerd trackingnummer kan nog geen gebeurtenissen van de vervoerder bevatten. Omgekeerd bewijst een succesvolle HTTP-respons voor een batchaanvraag niet dat elk item in de batch is geaccepteerd; controleer de structuur van het resultaat op applicatieniveau die door de provider is gedefinieerd.
1. Bereid uw verzendidentiteit en API-configuratie voor
Bepaal voordat u een registratieaanvraag doet hoe een zending in uw eigen systeem wordt geïdentificeerd. Alleen een order-ID is doorgaans onvoldoende, omdat één bestelling in meerdere pakketten kan worden opgesplitst. Geef elke zending of elk pakket een eigen intern record en koppel dat record aan de betreffende bestelling.
Een bruikbaar intern record bevat de volgende informatie. Dit zijn voorgestelde applicatievelden, geen 17TRACK-aanvraagsschema.
- Interne zending-ID: Uw stabiele identificatie voor het pakket.
- Orderreferentie: De bestelling of fulfilmentregistratie waartoe het behoort.
- Trackingnummer: De door de vervoerder uitgegeven identificatie, opgeslagen als tekst om voorloopnullen te behouden.
- Vervoerdersinformatie: De identiteit van de vervoerder die door uw fulfilmentsysteem is aangeleverd, indien bekend.
- Providerreferentie: Elke door de trackingservice geretourneerde identificatie die nodig is voor latere bewerkingen.
- Registratiestatus: Uw registratie van de vraag of de indiening in behandeling, geaccepteerd, afgewezen of wachtend op afstemming is.
- Trackingstatus: De meest recente verzendstatus, afzonderlijk bijgehouden van de registratiestatus.
Valideer invoer vóór indiening. Verwijder per ongeluk aanwezige spaties aan het begin en einde, maar herschrijf het trackingnummer niet op basis van aannames over het formaat van een vervoerder. Bewaar de oorspronkelijke waarde voor probleemoplossing. Als een vervoerder bekend is, koppel deze dan aan de gedocumenteerde vervoerdersidentificatie van de provider in plaats van een informele weergavenaam te verzenden.
Configureer authenticatie aan de serverzijde. Bewaar inloggegevens buiten het bronbeheer, scheid ontwikkel- en productieconfiguratie en verwijder geheimen uit logboeken. Controleer de gedocumenteerde API-versie, aanvraaglimieten, batchlimieten en accountvereisten in plaats van waarden uit een niet-gerelateerde integratie over te nemen.
2. Registreer de zending en leg het resultaat op itemniveau vast
Dien het trackingrecord in met de registratiebewerking die in de documentatie van uw provider wordt beschreven. Neem alleen verplichte velden op, plus optionele informatie met een duidelijk doel. Verstuur geen klantnamen, adressen of andere persoonsgegevens alleen omdat deze beschikbaar zijn in uw orderdatabase.
De volgende pseudocode illustreert de applicatiereeks. Functienamen zijn illustratief; het zijn geen API-eindpunten of SDK-methoden.
shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)
result = tracking_adapter.register(shipment)
if result.item_accepted:
save_registration_result(shipment_id, result)
elif result.outcome_unknown:
schedule_registration_reconciliation(shipment_id)
else:
save_registration_error(shipment_id, result)
route_for_retry_or_correction(result)
Bewaar voldoende informatie om uit te leggen wat er is gebeurd: de interne zending-ID, het tijdstip van indiening, het pogingsnummer, de uitkomst op itemniveau en eventuele aanvraagreferentie van de provider. Vertrouw niet uitsluitend op een tijdelijk workerlogboek. Uw klantenservice- en operationele teams hebben een blijvend antwoord nodig op de vraag of een zending succesvol is aangemeld.
Verwerk batchindieningen afzonderlijk
Als de API batchregistratie ondersteunt, koppel dan elk geretourneerd item aan de oorspronkelijke zending. Markeer niet de volledige batch als geaccepteerd omdat de HTTP-aanvraag succesvol is voltooid. Sla geaccepteerde items op, isoleer afgewezen items en onderzoek onduidelijke resultaten afzonderlijk.
Zo voorkomt u dat één ongeldig trackingnummer onnodige nieuwe pogingen afdwingt voor records die al zijn geslaagd. Ook krijgt het operationele personeel een bruikbare lijst met records die moeten worden gecorrigeerd.
Behandel time-outs als een onbekende uitkomst
Een time-out bewijst niet dat de registratie is mislukt. De provider kan de aanvraag hebben geaccepteerd voordat uw verbinding werd onderbroken. Gebruik gedocumenteerd idempotentiegedrag, afhandeling van duplicaten of opzoekbewerkingen om het resultaat af te stemmen voordat u blind opnieuw indient.
Als het gedrag van de provider bij duplicaten onduidelijk is, test dit dan met gecontroleerde records en bevestig het contract voordat u automatische nieuwe pogingen inschakelt. Het intern ontdubbelen van registratietaken blijft nuttig, maar vervangt niet het inzicht in hoe de externe service herhaalde aanvragen verwerkt.
3. Houd rekening met de komst van de eerste trackinginformatie
Nadat de registratie is geaccepteerd, zijn trackinggegevens mogelijk niet onmiddellijk beschikbaar. Er kan al een label bestaan voordat de vervoerder een fysieke verwerkingsgebeurtenis heeft geregistreerd. Ontbrekende informatie kan ook betekenen dat het trackingnummer, de vervoerderselectie of zending-specifieke vereisten voor het opzoeken moeten worden gecontroleerd.
Geef deze toestand expliciet weer. “Geregistreerd; wacht op trackinginformatie” is nauwkeuriger dan “Onderweg” of “Registratie mislukt”. Verzin geen leveringsschatting of bewegingsgebeurtenis om een lege interface op te vullen.
Onderzoek een record dat leeg blijft in de volgende praktische volgorde:
- Bevestig dat de afzonderlijke registratie is geaccepteerd.
- Vergelijk het ingediende trackingnummer met het fulfilmentrecord.
- Controleer de vervoerderskoppeling en alle gedocumenteerde aanvullende vereisten voor het opzoeken.
- Controleer de eigen trackingpagina van de vervoerder voor dezelfde zending.
- Als de vervoerder wel gebeurtenissen heeft maar uw integratie niet, controleer dan de ophaalantwoorden en neem contact op met de API-provider met geredigeerde diagnostische informatie.
Neem geen universele wachttijd over zonder bewijs. Escalatieregels moeten rekening houden met de verzendservice, het verwachte overdrachtsproces en uw eigen operationele verplichtingen.
4. Haal trackinggegevens op en interpreteer ze correct
Zodra het record beschikbaar is, roept u de gedocumenteerde bewerking voor trackingdetails aan met de vereiste identificaties. Ga er niet van uit dat registratie en ophalen identieke velden accepteren. Sommige API-contracten maken onderscheid tussen trackingnummers, vervoerdersidentificaties en door de provider gegenereerde recordreferenties.
Uw applicatie moet drie informatielagen onderscheiden:
- Zendingsoverzicht: De algemene toestand die wordt gebruikt in dashboards, orderpagina’s en operationele filters.
- Gebeurtenisgeschiedenis: De afzonderlijke waarnemingen, waaronder gebeurtenisbeschrijvingen, tijdstempels en locaties wanneer deze worden aangeleverd.
- Metadata voor ophalen: Wanneer uw applicatie de informatie heeft ontvangen of opgehaald en of de aanvraag succesvol is voltooid.
Een geslaagde zoekopdracht betekent dat de ophaalbewerking is geslaagd. Dit betekent niet dat het pakket sinds de vorige zoekopdracht is verplaatst. Vergelijk de geretourneerde trackinginformatie met uw opgeslagen record voordat u een melding of vervolgworkflow genereert.
Houd gebeurtenistijd en ophaaltijd gescheiden
Sla de tijd die bij een gebeurtenis van de vervoerder hoort afzonderlijk op van het tijdstip waarop uw systeem deze heeft ontvangen. Een gebeurtenis die vanmiddag is opgehaald, kan een eerdere scan beschrijven. Als u de gebeurtenistijd vervangt door de ophaaltijd, lijkt een oude update op een nieuwe fysieke beweging.
Behoud de oorspronkelijke tijdstempel en eventuele opgegeven offset. Normaliseer tijdstempels alleen voor vergelijking wanneer de tijdzone bekend is. Als een gebeurtenis geen tijdzonegegevens bevat, behoud die onzekerheid dan in plaats van stilzwijgend de tijdzone van uw server toe te wijzen.
Behoud de oorspronkelijke betekenis naast de genormaliseerde status
Een genormaliseerde status is nuttig om zendingen van verschillende vervoerders te groeperen, maar de oorspronkelijke gebeurtenisbeschrijving kan een operationeel probleem nauwkeuriger verklaren. Bewaar beide wanneer ze beschikbaar zijn. Alleen een brede uitzonderingscategorie vertelt een supportmedewerker mogelijk niet of de volgende actie bestaat uit het controleren van een adres, contact opnemen met de ontvanger of wachten op een nieuwe update.
Leid uit een vage status geen leveringsgarantie, bevestigd verlies of specifieke douane-uitkomst af. Escaleer op basis van de onderliggende informatie en uw operationele beleid.
5. Houd records bijgewerkt via polling of webhooks
Eenmalig details ophalen is voldoende om de connectiviteit te testen, maar niet om zichtbaarheid van zendingen te onderhouden. Uw productieontwerp heeft een mechanisme voor updates nodig. Bevestig welke mechanismen door uw gekozen provider worden ondersteund en welke voorwaarden eraan verbonden zijn.
Bij polling vraagt uw applicatie volgens een schema trackingdetails op. Plan aanvragen binnen de gedocumenteerde limieten, vermijd het herhaaldelijk opvragen van ongewijzigde records zonder reden en gebruik backoff voor opnieuw probeerbare fouten. Het openen van een orderpagina door een klant mag niet automatisch een onbeperkte upstream-aanvraag activeren; een opgeslagen trackingweergave kan de pagina bedienen terwijl een gecontroleerd achtergrondproces deze vernieuwt.
Als u webhooks gebruikt, valideer inkomende aanvragen dan met het gedocumenteerde verificatiemechanisme van de provider. Sla geaccepteerde berichten op of plaats ze duurzaam in een wachtrij voordat u ze volgens het webhookcontract bevestigt, en verwerk de gebeurtenissen vervolgens asynchroon.
Bouw de ontvanger zo dat deze duplicaten en een onverwachte aankomstvolgorde verdraagt, tenzij het gedocumenteerde leveringscontract anders garandeert. Gebruik indien beschikbaar een gebeurtenis-ID van de provider voor deduplicatie. Definieer en test anders een vingerafdruk op basis van geschikte gebeurtenisvelden, met het besef dat voor uw gegevens aanpassingen nodig kunnen zijn.
Een webhookgestuurde integratie kan ook gecontroleerd ophalen gebruiken voor afstemming. Zo kan een hersteltaak bijvoorbeeld records controleren die door een storing in de ontvanger zijn getroffen. Dit is een veerkrachtpatroon en geen toestemming om snelheidslimieten of provider-specifieke richtlijnen te negeren.
6. Zet trackinginformatie om in veilige bedrijfsacties
Werk uw interne zendingrecord bij voordat u klantgerichte acties activeert. Bewaar een duurzaam overzicht van meldingen en workflowovergangen, zodat een herhaalde gebeurtenis niet opnieuw dezelfde berichten genereert.
Koppel bedrijfsacties aan betekenisvolle wijzigingen in plaats van aan elke API-respons. Een nieuw waargenomen leveringsgebeurtenis kan een melding over levering rechtvaardigen. Een herhaalde respons met dezelfde gebeurtenis niet. Een uitzondering kan aanleiding geven tot een interne beoordeling, maar het klantbericht moet weergeven wat de gebeurtenis daadwerkelijk zegt.
Bepaal hoe u omgaat met gebeurtenissen die worden ontvangen nadat een zending als voltooid werd beschouwd. Verwijder de gebeurtenisgeschiedenis niet en blokkeer latere updates niet permanent alleen omdat een overzicht een eindstatus heeft bereikt. Uw regels voor bewaring, afstemming en meldingen moeten rekening houden met legitieme correcties zonder voltooide workflows steeds opnieuw te openen.
De workflow toepassen op een 17TRACK-integratie
Voor een aangepaste trackingintegratie zijn de relevante startpunten de 17TRACK Tracking API-pagina en de ontwikkelaarsdocumentatie. Gebruik de productpagina om het aanbod te beoordelen en de documentatie om het daadwerkelijke integratiecontract vast te leggen. Trackingpagina’s voor consumenten zijn geen vervanging voor API-specificaties.
Controleer voordat u uw adapter schrijft het authenticatieformaat, de registratie- en ophaalbewerkingen, de regels voor vervoerdersidentificatie, de verwerking van antwoorden op itemniveau en de toepasselijke aanvraaglimieten. Bevestig voor webhookgebaseerde verwerking ook het payloadschema, het verificatieproces, de vereisten voor bevestiging en het gedrag bij nieuwe pogingen.
Houd deze provider-specifieke details in een adapter in plaats van aannames over antwoordvelden door uw hele ordersysteem te verspreiden. De rest van uw applicatie kan dan werken met interne concepten zoals registratieresultaat, verzendstatus, gebeurtenisgeschiedenis en laatste succesvolle synchronisatie.
Controles vóór de lancering die kostbare fouten opsporen
- Geaccepteerd maar leeg record: De interface toont dat trackinginformatie in behandeling is, niet dat het pakket onderweg is.
- Gemengd batchresultaat: Elke zending krijgt een eigen opgeslagen uitkomst.
- Time-out na indiening: De worker stemt het onzekere resultaat af in plaats van uit te gaan van een fout.
- Herhaalde gebeurtenis: De verzendtijdlijn en klantmelding blijven ontdubbeld.
- Oudere gebeurtenis later ontvangen: De gebeurtenis wordt behouden zonder blindweg een nieuwer overzicht te vervangen.
- Niet-beschikbare upstreamservice: De klantpagina kan het laatst opgeslagen resultaat tonen met een passende aanduiding van de actualiteit.
- Onjuiste vervoerderskoppeling: Het record kan via een gedocumenteerd herstelpad worden gecorrigeerd.
- Opgesplitste bestelling: Elk pakket behoudt zijn eigen trackingstatus en gebeurtenisgeschiedenis.
- Blootstelling van inloggegevens of payload: Logboeken bevatten diagnostische referenties zonder geheimen of onnodige persoonsgegevens te lekken.
Het praktische voltooiingscriterium is niet simpelweg het ontvangen van een succesvolle registratierespons. Het is het kunnen volgen van een pakket vanaf indiening tot en met updates, het kunnen verklaren van een leeg of mislukt resultaat en het kunnen herstellen van onderbroken verwerking zonder gebeurtenissen te verliezen of klantacties te dupliceren.
FAQ
Maakt het registreren van een trackingnummer een zending aan?
Niet in de hier beschreven workflow. Bij trackingregistratie wordt een bestaande identificatie bij een trackingservice ingediend. Het aanmaken van een label, het kopen van portokosten en het boeken van een vervoerder zijn afzonderlijke bewerkingen, tenzij een specifieke API deze uitdrukkelijk combineert.
Waarom zijn trackinggegevens leeg nadat de registratie is geslaagd?
Registratieacceptatie en beschikbaarheid van trackinggegevens zijn verschillende voorwaarden. De vervoerder heeft mogelijk nog geen gebeurtenis geregistreerd, of het trackingnummer, de vervoerderskoppeling of aanvullende informatie voor het opzoeken moet worden gecontroleerd. Controleer het resultaat op itemniveau voordat u het record als succesvol geregistreerd beschouwt.
Moet ik de zending registreren telkens wanneer ik de status ophaal?
Gebruik herhaalde registratie niet als standaardmechanisme voor vernieuwing. Sla de geaccepteerde registratiestatus op en gebruik het gedocumenteerde ophaal- of updatemechanisme. Volg de expliciete regels van de provider voor correcties, reactivering of dubbele indieningen.
Moet ik polling of webhooks gebruiken?
Gebruik het mechanisme dat past bij het gedocumenteerde API-contract en uw operationele vereisten. Polling vereist een gecontroleerd aanvraagschema. Webhooks vereisen een veilige, duurzame ontvanger en verwerking die duplicaten veilig afhandelt. Waar dit wordt ondersteund, kunnen webhookupdates met gerichte afstemming een praktisch herstelpad bieden.
Kan ik een trackingnummer als enige zendingidentificatie in mijn database gebruiken?
Gebruik in plaats daarvan een interne zendingidentificatie. Sla het trackingnummer en de relevante vervoerderscontext op als kenmerken van dat record. Hierdoor zijn opgesplitste bestellingen, gecorrigeerde trackingnummers en provider-specifieke referenties eenvoudiger te beheren zonder de identiteit van uw interne zending te wijzigen.
Bronnen
- 17TRACK Tracking API — officieel productstartpunt voor het beoordelen van een 17TRACK API-integratie.
- 17TRACK API-documentatie — officiële referentie voor implementatiespecifieke aanvraagformaten, bewerkingen, antwoorden en integratievereisten. De pseudocode en voorgestelde interne velden in deze handleiding zijn voorbeelden van applicatieontwerp en geen citaten uit dit API-contract.


