Een trackingnummer registreren via de API: aanvraagvelden, vervoerderscodes en reacties
Om een trackingnummer via API te registreren, stuur je een geauthenticeerd registratieverzoek met het trackingnummer van de zending en, indien vereist, een vervoerdersidentifier. Controleer vervolgens de respons voor elke ingediende zending—not just de HTTP-status—en sla op of de registratie is geslaagd, mislukt of onzeker blijft. Registratie start de trackingworkflow; dit bewijst niet dat de vervoerder het pakket heeft gescand of dat er al trackinggebeurtenissen beschikbaar zijn.
Deze handleiding is bedoeld voor ontwikkelaars die een orderbeheersysteem, magazijntoepassing of e-commerceplatform koppelen aan een tracking-API. 17TRACK wordt gebruikt als concreet integratievoorbeeld. Ook wordt uitgelegd welke gegevens moeten worden gecontroleerd aan de hand van de documentatie voor de door jou geselecteerde API-versie.
Wat registratie wel en niet doet
Een registratieverzoek vertelt een trackingservice welke zending je wilt volgen. Dit verschilt van het kopen van een verzendlabel, het boeken van een ophaalafspraak of het verzoeken aan een vervoerder om een zending aan te maken. In een typische integratie genereert de verzendworkflow eerst een trackingnummer, waarna je toepassing dat nummer registreert.
Houd deze drie gebeurtenissen in je toepassing gescheiden:
- Zending aangemaakt: je verzendsysteem heeft een trackingnummer toegewezen.
- Registratie geaccepteerd: de trackingservice heeft de zending voor tracking geaccepteerd.
- Trackinginformatie ontvangen: gebeurtenissen van de vervoerder zijn beschikbaar gekomen via de trackingservice.
Werk een order niet bij naar “onderweg” alleen omdat de registratie is geslaagd. Een nieuw aangemaakt label heeft mogelijk nog geen fysieke acceptatiescan. De klantgerichte verzendstatus moet afkomstig zijn van trackinggebeurtenissen die volgens je statusregels zijn geïnterpreteerd, niet van de registratierespons.
Begin voor 17TRACK-integraties met het overzicht van de Tracking API en gebruik de officiële API-documentatie als bron voor endpoints, velddefinities, authenticatie en respons-codes. De onderstaande voorbeelden richten zich op registratie en niet op de afzonderlijke taken voor het ophalen van resultaten of ontvangen van updates.
Bereid de aanvraagvelden voor voordat je de API-aanroep schrijft
De nuttigste voorbereiding is een klein veldcontract tussen je verzendsysteem en je trackingintegratie. Bepaal waar elke waarde vandaan komt, of deze kan ontbreken en hoe deze wordt gevalideerd.
| Veld of waarde | Doel | Implementatieregel |
|---|---|---|
| Trackingnummer | Identificeert de te volgen zending. | Sla het op en verzend het als tekenreeks; behoud voorloopnullen. |
| Vervoerdersidentifier | Identificeert de vervoerder binnen het systeem van de trackingprovider. | Gebruik de gedocumenteerde identifier van de provider, niet een interne magazijncode. |
| Interne referentie | Verbindt de registratie met je verzendrecord. | Gebruik een ondersteund referentieveld indien beschikbaar; behoud hoe dan ook je eigen databasemapping. |
| Aanvullende identificatiegegevens | Kunnen helpen een zending te identificeren wanneer een vervoerder meer vereist dan alleen het trackingnummer. | Dien alleen velden in die voor die integratie en vervoerder zijn gedocumenteerd. |
| API-referentie | Authenticeert de aanroepende account. | Bewaar deze op de server en sluit deze uit van applicatielogs. |
Behandel het trackingnummer als identifier
Converteer een trackingnummer nooit naar een integer. Numerieke conversie kan voorloopnullen verwijderen en grote waarden kunnen in sommige programmeeromgevingen precisie verliezen. Verwijder onbedoelde spaties aan het begin en einde, maar verwijder geen leestekens en wijzig de hoofdlettergebruik niet, tenzij de relevante documentatie of het vervoerdersformaat die normalisatie ondersteunt.
Valideer duidelijke invoerfouten voordat je de API aanroept: lege tekenreeksen, onverwachte regeleinden en een ordernummer dat in het trackingnummerveld is gekopieerd. Leg niet één universele lengte- of tekenregel op voor alle vervoerders. Een validatieregel die bij één vervoerder past, kan geldige nummers van een andere vervoerder afwijzen.
Houd orderreferenties gescheiden van verzendidentiteiten
Een order kan meerdere pakketten hebben en een vervangende zending kan een nieuw trackingnummer introduceren. Modelleer registratie op verzend- of pakketniveau in plaats van aan te nemen dat elke order één trackingnummer heeft.
Als je een door de provider ondersteunde tag of referentieveld gebruikt, kies dan bij voorkeur een ondoorzichtige verzendreferentie in plaats van het e-mailadres of straatadres van een klant. Je eigen database moet de gezaghebbende koppeling blijven tussen orders, zendingen, trackingnummers en vervoerdersmappings.
Kies de juiste vervoerderscode
Een vervoerderscode is niet noodzakelijk een universele branche-identificatie. De waarde die door een trackingplatform wordt herkend, kan verschillen van de vervoerdersnaam die in je verzendsoftware is opgeslagen. Zelfs twee systemen die numerieke codes gebruiken, kunnen verschillende nummers aan dezelfde vervoerder toewijzen.
Onderhoud een expliciete mapping van je verzendservice naar de vervoerdersidentifier van de trackingprovider. Maak waar nodig onderscheid tussen de regionale activiteit of service van een vervoerder en het bredere merk. Een mapping die alleen op een weergavenaam is gebaseerd, kan dubbelzinnig worden wanneer verzendsystemen aliassen gebruiken.
- Wanneer de vervoerder bekend is: gebruik de gedocumenteerde vervoerdersidentifier indien ondersteund, vooral wanneer trackingnummerformaten overlappen.
- Wanneer de vervoerder onbekend is: gebruik automatische detectie alleen via het gedocumenteerde mechanisme. Neem niet aan dat weglating, een lege tekenreeks, nul en null hetzelfde betekenen.
- Wanneer het resultaat onjuist lijkt: controleer het oorspronkelijke label, de verzendservice en de mapping voordat je hetzelfde nummer herhaaldelijk registreert.
Automatische detectie is nuttig, maar vormt geen bewijs dat een bepaalde vervoerder de zending fysiek in bezit heeft. Ook garandeert een geldige vervoerderscode niet dat het verstrekte trackingnummer bij die vervoerder hoort.
Houd vervoerdersmappings configureerbaar in plaats van ze verspreid door de applicatiecode op te nemen. Registreer wanneer een mapping voor het laatst is gecontroleerd en neem een bekende zending op in regressietests wanneer je deze wijzigt.
Voorbeeld: een 17TRACK-registratieverzoek indienen
Het volgende voorbeeld toont het 17TRACK v2.2-registratieendpoint, de authenticatieheader 17token en een array met één trackingnummerobject. Controleer vóór implementatie of deze versie en de aanvraagvereisten overeenkomen met je account en de officiële documentatie. Het trackingnummer is een tijdelijke aanduiding en moet worden vervangen door een echte verzendidentifier.
curl --request POST \
--url 'https://api.17track.net/track/v2.2/register' \
--header "17token: ${TRACKING_API_TOKEN}" \
--header 'Content-Type: application/json' \
--data '[
{
"number": "YOUR_TRACKING_NUMBER"
}
]'
Dit minimale voorbeeld toont geen vervoerdersselectie of vervoerdersspecifieke aanvullende velden. Controleer de registratiedocumentatie om te bepalen hoe vervoerdersdetectie werkt wanneer het vervoerdersveld ontbreekt en of je zending aanvullende informatie nodig heeft. Als je een vervoerder opgeeft, gebruik dan het gedocumenteerde veld carrier en de identifier die door die API-versie wordt verwacht.
Voer dit verzoek uit vanuit een server-side omgeving. Neem het token niet op in een openbare storefront, browserscript of mobiele applicatie die aan klanten wordt verspreid. Een omgevingsvariabele is handig voor een lokaal voorbeeld; productie-implementaties moeten de geheimenbeheercontroles van je organisatie gebruiken.
Test eerst één bekende zending en controleer de volledige respons voordat je het volume verhoogt. Test vervolgens ongeldige invoer en een batch met zowel geldige als ongeldige items. Deze controles laten zien of je integratie daadwerkelijk resultaten per item verwerkt in plaats van alleen een HTTP-succesrespons te herkennen.
Lees de respons op drie niveaus
Een betrouwbare responsverwerker beantwoordt drie afzonderlijke vragen: heeft het verzoek de service bereikt, heeft de service de bewerking geaccepteerd en wat is er met elke zending gebeurd?
1. HTTP- en transportresultaat
Een verbindingstime-out, TLS-fout of onderbroken respons vertelt niet noodzakelijk of de server het verzoek heeft verwerkt. Markeer dat resultaat als onzeker totdat je het kunt verifiëren. Een HTTP-successtatus bevestigt een geslaagde HTTP-uitwisseling, maar je moet nog steeds de applicatierespons controleren.
2. Resultaat op verzoekniveau
Controleer het gedocumenteerde resultaat en de foutvelden op het hoogste niveau van de API. Authenticatiefouten, ongeldige JSON en accountbeperkingen vereisen verschillende acties. Sla de oorspronkelijke foutcode en het oorspronkelijke bericht van de provider op in plaats van elke fout te reduceren tot “tracking niet beschikbaar”.
Ga er niet van uit dat een numerieke applicatiecode dezelfde betekenis heeft als een HTTP-statuscode. Hun betekenissen komen uit verschillende lagen en moeten afzonderlijk worden geïnterpreteerd.
3. Resultaat op verzendniveau
Houd bij batchregistratie rekening met elk ingediend item. Een respons kan geaccepteerde en afgewezen zendingen onderscheiden; je parser moet het exacte schema volgen dat voor de geselecteerde versie is gedocumenteerd. Markeer niet een volledige batch als geregistreerd alleen omdat één item is geslaagd.
Normaliseer providerresponsen naar je eigen stabiele applicatiestatussen. Je database kan bijvoorbeeld accepted, rejected en uncertain gebruiken. Dit zijn voorgestelde interne statussen en geen letterlijke 17TRACK-responswaarden. Bewaar de oorspronkelijke providerrespons volgens een passend beleid voor bewaartermijn en toegang, zodat ontwikkelaars afwijkingen kunnen onderzoeken.
Een nuttig registratierecord bevat de interne verzend-ID, het ingediende nummer, de vervoerdersselectie, het tijdstip van de poging, de API-versie, het resultaat en de foutdetails van de provider. Houd registratiestatus gescheiden van bezorgstatus.
Verwerk nieuwe pogingen zonder een eindeloze lus te creëren
Het retrybeleid moet afhangen van de fout en niet alleen van het feit of er een uitzondering is opgetreden.
- Ongeldige invoer: corrigeer het veld voordat je opnieuw probeert. Het herhalen van een ongewijzigd ongeldig verzoek helpt waarschijnlijk niet.
- Authenticatiefout: controleer de referenties en accountconfiguratie. Vermijd het herhaaldelijk indienen van dezelfde mislukte batch.
- Rate limiting: volg de gedocumenteerde limieten en eventuele toepasselijke retry-instructies. Gebruik begrensde backoff in plaats van onmiddellijke parallelle nieuwe pogingen.
- Tijdelijke servicefout: probeer opnieuw binnen een vastgestelde limiet voor pogingen en tijd.
- Time-out na indiening: verifieer de registratiestatus van de zending volgens het gedocumenteerde API-gedrag voordat je ervan uitgaat dat de eerste poging is mislukt.
- Respons in verband met duplicaten: controleer of de zending al is geregistreerd en correct aan je applicatierecord is gekoppeld.
Ga er niet van uit dat registratie idempotent is, tenzij de documentatie dat gedrag definieert. Deduplicatie aan de applicatiekant vermindert onbedoelde herhaalde indieningen, maar bepaalt niet hoe de provider met duplicaten omgaat.
Gebruik een interne uniciteitsregel die past bij je verzendmodel. Alleen het trackingnummer is mogelijk geen voldoende permanente sleutel voor verschillende vervoerders en lange bewaartermijnen. Behoud de vervoerderscontext en je eigen verzendidentifier en documenteer hoe vervangingen en gecorrigeerde nummers worden verwerkt.
Monitor registratie afzonderlijk van trackingupdates
API-monitoring moet een integratiefout onderscheiden van een zending die simpelweg geen nieuwe gebeurtenis van de vervoerder heeft. Deze situaties vereisen verschillende verantwoordelijken en oplossingen.
Monitor voor registratie de aantallen acceptaties en afwijzingen, foutcategorieën, onzekere resultaten, de retry-achterstand en de responstijd. Monitor voor daaropvolgende tracking de ontvangst van updates of fouten bij het ophalen afzonderlijk. Stel geen numerieke alarmdrempels vast voordat je normaal verkeer en de gedocumenteerde operationele limieten van de provider begrijpt.
Een praktische productiecontrole moet antwoord geven op het volgende:
- Heeft elke zending die op tracking wacht een registratierecord?
- Kan elke geaccepteerde registratie worden teruggevoerd naar het juiste pakket?
- Worden afgewezen items doorgestuurd naar iemand die de onderliggende gegevens kan corrigeren?
- Worden onzekere verzoeken geverifieerd in plaats van achtergelaten of onbeperkt opnieuw geprobeerd?
- Worden klantgerichte statussen afgeleid van verzendgebeurtenissen in plaats van registratieacceptatie?
- Worden referenties en onnodige persoonsgegevens uitgesloten van logs?
Voor e-commerceactiviteiten is de operationele overdracht net zo belangrijk als de API-aanroep. Ontwikkelaars moeten verantwoordelijk zijn voor transport- en parseerfouten; verzend- of fulfilmentteams moeten onjuiste labels, vervoerdersmappings en ontbrekende verzendinformatie kunnen onderzoeken.
Veelgestelde vragen
Kan ik een trackingnummer registreren vóór de eerste scan door de vervoerder?
Registratie en scans door de vervoerder zijn afzonderlijke gebeurtenissen. Een service kan een nummer accepteren voordat trackinggebeurtenissen beschikbaar zijn, afhankelijk van de validatieregels. Interpreteer acceptatie niet als bewijs dat de vervoerder het pakket heeft ontvangen.
Moet ik altijd een vervoerderscode opgeven?
Dat hangt af van het gedocumenteerde detectiegedrag van de API en van de betrokken zending. Als de vervoerder bekend is, kan een expliciet en correct gemapt identificatienummer dubbelzinnigheid verminderen. Als de vervoerder onbekend is, gebruik dan de gedocumenteerde methode voor automatische detectie in plaats van zelf een vervoerderswaarde te verzinnen.
Waarom gaf de API HTTP-succes terug terwijl een zending mislukte?
Het HTTP-verzoek kan slagen terwijl de applicatie een afzonderlijk item afwijst. Lees het applicatieresultaat op het hoogste niveau en de resultaten op verzendniveau. Dit onderscheid is vooral belangrijk bij batchverzoeken.
Wat moet ik doen wanneer een registratieverzoek een time-out krijgt?
Behandel het resultaat als onzeker. De server kan het verzoek hebben verwerkt voordat de verbinding wegviel. Controleer het gedocumenteerde gedrag van de provider bij duplicaten en beschikbare methoden voor registratie- of trackingopzoekingen. Verifieer of probeer daarna opnieuw volgens een begrensd beleid.
Configureert registratie automatisch trackingmeldingen?
Ga daar niet van uit. Registratie, het ophalen van trackinginformatie en webhookconfiguratie zijn afzonderlijke integratiekwesties. Controleer de relevante documentatie en test het volledige updatepad voordat je erop vertrouwt voor klantmeldingen.
Bronnen
- 17TRACK API-documentatie — referentie voor registratie-endpoints, authenticatie, aanvraagvelden, vervoerdersidentifiers, responsschema's en foutafhandeling. Stem implementatiedetails af op de API-versie die je implementeert.
- Overzicht van de 17TRACK Tracking API — officieel startpunt voor het Tracking API-product en bronnen voor ontwikkelaarsintegratie.


