Skip to main content
HomeBlogGidsenJe eerste Tracking API-verzoek: een walkthrough van een REST-client met Postman en Curl

Je eerste Tracking API-verzoek: een walkthrough van een REST-client met Postman en Curl

17TRACK

Om je eerste tracking-API-verzoek te doen, configureer je het endpoint, de authenticatieheader en de JSON-body in een REST-client, verstuur je het verzoek en controleer je zowel de HTTP-status als de response-body. Deze walkthrough gebruikt de Tracking API van 17TRACK om dezelfde workflow in Postman en curl te demonstreren: registreer een zending, vraag de trackinginformatie op en controleer of het resultaat klaar is voor gebruik door je applicatie.

Je eerste Tracking API-verzoek: een walkthrough van een REST-client

Het doel is een kleine, reproduceerbare integratietest, geen productie-implementatie. Je hebt API-inloggegevens nodig en een trackingnummer dat je mag verwerken. De onderstaande opdrachten gebruiken het v2.2-endpointpatroon; controleer de endpointversie en accountspecifieke vereisten in de 17TRACK API-documentatie voordat je ze uitvoert.

Begrijp wat je eerste verzoek moet bereiken

Een integratie voor het volgen van zendingen heeft twee afzonderlijke aandachtspunten: de service vertellen welke zending moet worden gevolgd en de trackinginformatie ophalen die aan die zending is gekoppeld. In de hier gedemonstreerde workflow zijn dit afzonderlijke verzoeken. Registratie betekent niet dat het pakket al onderweg is en een geslaagde registratie garandeert niet dat vervoerdergebeurtenissen onmiddellijk beschikbaar zijn.

Gebruik voor je eerste test één zending in plaats van een batch. Zo kun je authenticatiefouten, ongeldige trackingnummers en de interpretatie van responses eenvoudiger afzonderlijk onderzoeken. Je eerste nuttige mijlpaal is niet simpelweg: “Ik heb HTTP 200 ontvangen.” Het is: “De API heeft mijn beoogde bewerking geaccepteerd en ik kan het resultaat op zendingsniveau uitleggen.”

Postman biedt een visuele interface voor het bewerken van verzoeken en het inspecteren van responses. curl maakt dezelfde HTTP-uitwisseling reproduceerbaar vanuit een terminal. Geen van beide verandert de authenticatieregels, zendingsgegevens of verwerkingslogica van de API. Gebruik de tool waarmee je het verzoek het duidelijkst kunt onderzoeken en reproduceer de werkende configuratie vervolgens in de andere tool.

Bereid je inloggegevens, zending en verzoekdetails voor

Verzamel het volgende voordat je een van beide clients opent:

  • Geautoriseerde API-inloggegevens: verkrijg deze via de configuratie van je 17TRACK API-account. Een consumententracking-sessie is geen vervanging voor API-inloggegevens.
  • Een echt trackingnummer: gebruik een zending die je bezit of waarvoor je toestemming hebt. Een recent actieve zending is doorgaans nuttiger dan een verzonnen nummer bij het testen van echte trackinggegevens.
  • De vervoerder, indien bekend: houd de naam van de vervoerder bij de hand voor diagnose. Als voor jouw situatie een vervoerder-ID vereist is, gebruik dan de waarde en het veld uit de API-documentatie in plaats van te gokken.
  • Het huidige requestcontract: controleer de API-versie, authenticatieheader, requeststructuur en eventuele accountbeperkingen.
  • Een veilige werkruimte: plaats geen inloggegevens, klantgegevens of volledige trackingresponses in openbare repositories, screenshots of gedeelde supportberichten.

De minimale requestvoorbeelden gebruiken deze instellingen:

InstellingVoorbeeldconfiguratie
Basis-URLhttps://api.17track.net/track/v2.2
RegistratiebewerkingPOST /register
Bewerking voor trackinginformatiePOST /gettrackinfo
Authenticatieheader17token: YOUR_API_TOKEN
Body-indelingContent-Type: application/json, met een JSON-array van zendingsobjecten

Bewaar trackingnummers als strings. Als je er een numeriek type van maakt, kunnen voorloopnullen verdwijnen of kan de waarde anderszins veranderen. De placeholder YOUR_TRACKING_NUMBER hieronder moet worden vervangen door je echte testzending; dit is geen werkend voorbeeldnummer.

Maak het registratieverzoek in Postman

1. Maak een kleine testomgeving

Maak in Postman een omgeving met drie variabelen: base_url, tracking_token en tracking_number. Stel base_url in op de bovenstaande basis-URL en voer je inloggegevens en zendingsnummer in bij de andere variabelen. Selecteer die omgeving voordat je het verzoek verstuurt.

Gebruik de beschikbare functies van Postman voor het omgaan met geheime waarden voor het token en controleer wat je werkruimte deelt of synchroniseert. Een waarde verbergen in de interface vervangt niet het beheer van wie er toegang toe heeft. Exporteer geen ingevulde inloggegevens met een collectie die bedoeld is voor collega's of openbare documentatie.

2. Configureer de methode, URL en headers

Maak een HTTP-verzoek, selecteer POST en voer {{base_url}}/register in als URL. Voeg op het tabblad Headers het volgende toe:

17token: {{tracking_token}}
Content-Type: application/json

Voor dit voorbeeld hoort de inlogcredential in de aangepaste 17token-header. Vervang deze niet door een Bearer-tokenconfiguratie alleen omdat een andere API dat patroon gebruikte. Controleer ook of overgenomen collectie-instellingen onbedoeld een Authorization-header toevoegen.

3. Voeg de JSON-body toe

Open Body, kies raw en selecteer JSON. Voer het volgende in:

[
  {
    "number": "{{tracking_number}}"
  }
]

De buitenste vierkante haakjes zijn belangrijk: dit verzoek gebruikt een array, ook al bevat deze maar één zending. Gebruik dubbele aanhalingstekens, verwijder afsluitende komma's en plaats geen opmerkingen in de JSON. Als de documentatie aanvullende informatie voor jouw vervoerder of zending vereist, voeg dan de gedocumenteerde velden toe voordat je het verzoek verstuurt.

4. Verstuur het verzoek en controleer het resultaat

Klik op Send. Controleer eerst of je überhaupt een HTTP-response hebt ontvangen. Een DNS-fout, TLS-fout, proxyprobleem of time-out verschilt van een response waarin wordt uitgelegd dat het verzoek ongeldig was. Inspecteer vervolgens de response-body op het resultaat van de bewerking en eventuele informatie over acceptatie of afwijzing op zendingsniveau.

Sla het verzoek op als “Register test shipment”. Noteer de HTTP-status, het API-resultaat en eventuele foutmelding zonder het token te kopiëren. Als de registratie mislukt, los die fout dan op voordat je verdergaat. Het herhaaldelijk indienen van een ongewijzigd verzoek maakt de diagnose moeilijker en kan accountresources verbruiken.

Reproduceer het verzoek met curl

De volgende opdrachten gebruiken een POSIX-achtige shell, zoals Bash of Zsh. PowerShell en Windows Command Prompt gebruiken andere regels voor aanhalingstekens en variabelen. Gebruik in PowerShell indien nodig curl.exe om het curl-programma aan te roepen in plaats van een shellspecifieke opdrachtalias.

Stel de basis-URL in en laad je inloggegevens via je gebruikelijke workflow voor geheimen in een omgevingsvariabele:

export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# Set TRACKING_API_TOKEN securely before continuing.

Een omgevingsvariabele houdt de inloggegevens buiten het herbruikbare voorbeeld, maar is geen volledig systeem voor geheimbeheer. Typ bij lokale tests geen echt token in een opdracht die door je shellgeschiedenis wordt bewaard. Gebruik voor automatisering de secret store van je platform en beperk de loguitvoer.

Maak een bestand met de naam shipment.json en vervang de placeholder door je testtrackingnummer:

[
  {
    "number": "YOUR_TRACKING_NUMBER"
  }
]

Verstuur het registratieverzoek:

curl --request POST \
  --url "$TRACKING_BASE_URL/register" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output register-response.json \
  --write-out 'HTTP status: %{http_code}\n'

Hiermee wordt de response-body opgeslagen in register-response.json en wordt de HTTP-status afzonderlijk afgedrukt. De verbindings- en totale time-outs zijn keuzes voor lokale tests en geen garanties van de 17TRACK-service. Open het opgeslagen bestand om het API-resultaat te inspecteren; alleen de statusregel is onvoldoende.

curl kan een overdracht succesvol voltooien terwijl de server een HTTP-foutresponse terugstuurt. Omgekeerd kan een transportfout voorkomen dat er überhaupt een bruikbare API-response binnenkomt. Behandel bij het scripten de exitstatus van curl, de HTTP-status en het resultaat op applicatieniveau als afzonderlijke signalen.

Vraag de trackinginformatie van de zending op

Nadat je de registratie hebt bevestigd, dupliceer je het Postman-verzoek en wijzig je de URL in {{base_url}}/gettrackinfo. Behoud de POST-methode, authenticatieheader, contenttype en zendingsbody. Sla het afzonderlijk op, zodat je de zending niet per ongeluk opnieuw registreert wanneer je gegevens wilt ophalen.

Het overeenkomstige curl-verzoek is:

curl --request POST \
  --url "$TRACKING_BASE_URL/gettrackinfo" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output tracking-response.json \
  --write-out 'HTTP status: %{http_code}\n'

Ga er niet van uit dat een nieuw geregistreerde zending onmiddellijk een volledige gebeurtenisgeschiedenis retourneert. De beschikbaarheid van gegevens hangt af van de zending en de verwerking door de service. Als informatie nog niet beschikbaar is, volg dan de gedocumenteerde richtlijnen voor ophalen en bijwerken in plaats van hetzelfde nummer herhaaldelijk te registreren of een krappe pollinglus uit te voeren.

Lees de response in drie lagen

  1. Transport: heeft de client verbinding gemaakt en een HTTP-response ontvangen?
  2. Bewerking: heeft de API het verzoek geaccepteerd en is de afzonderlijke zending geslaagd?
  3. Zendingsinformatie: identificeert de geretourneerde data het bedoelde pakket en wat bevestigt de status of gebeurtenisgeschiedenis daadwerkelijk?

Gebruik het officiële responseschema om status-, vervoerder- en gebeurtenisvelden te vinden. Houd het onderscheid in stand tussen een genormaliseerde zendingsstatus en de oorspronkelijke gebeurtenisbeschrijving van de vervoerder. Een geslaagde lookup is geen bewijs van bezorging en ontbrekende gebeurtenissen zijn geen bewijs dat een pakket verloren is.

Behoud bij het opslaan van tijdstempels de meegeleverde tijdzone- of offsetinformatie. Sorteer geen onbewerkte datumstrings met verschillende indelingen en neem niet aan dat ze een juiste chronologische volgorde vertegenwoordigen. Maak ook onderscheid tussen het tijdstip waarop je applicatie een record heeft opgehaald en het tijdstip waarop de gebeurtenis van de zending plaatsvond.

Los problemen op zonder alles tegelijk te wijzigen

  • Geen response: controleer de hostnaam, netwerktoegang, proxy-instellingen, TLS-configuratie en lokale time-out. Schakel certificaatverificatie niet routinematig uit als oplossing.
  • Authenticatiefout: controleer of het token actief is, de 17token-header aanwezig is en de geselecteerde Postman-omgeving de variabele correct invult. Controleer op onbedoelde spaties.
  • Ongeldig verzoek: controleer de API-versie, het bewerkingspad, de POST-methode, het contenttype en de JSON-arraystructuur aan de hand van de documentatie.
  • Zending afgewezen: lees de foutmelding die specifiek voor de zending geldt. Controleer het nummer en eventuele vereiste vervoerdersinformatie in plaats van elke afwijzing als een authenticatieprobleem te behandelen.
  • Geen trackinggebeurtenissen: bevestig de registratie en de identiteit van de bedoelde zending. Controleer of vervoerdersinformatie nodig is en of updates beschikbaar zijn voordat je opnieuw probeert.
  • Postman werkt maar curl niet: vergelijk de opgeloste URL, de daadwerkelijke headers en de bytes van de body. Shell-aanhalingstekens en niet-ingestelde omgevingsvariabelen zijn veelvoorkomende oorzaken waardoor de verzoeken uiteenlopen.

Wijzig per test één variabele en houd een korte registratie van het resultaat bij. Als je de console van Postman inspecteert of de uitgebreide uitvoer van curl gebruikt, behandel de uitvoer dan als gevoelig: requestheaders kunnen inloggegevens onthullen. Redigeer geheimen en klantinformatie voordat je diagnostische gegevens deelt.

Weet wanneer de walkthrough voltooid is

Je hebt een betekenisvolle eerste integratietest voltooid wanneer beide clients het bedoelde verzoek versturen, de registratie wordt begrepen, het ophalen een interpreteerbaar resultaat oplevert en je een API-fout kunt onderscheiden van een zending zonder nieuwe informatie. Overeenkomende HTTP-statuscodes alleen bewijzen niet dat de twee clients zich identiek hebben gedragen.

Houd inloggegevens op de server, valideer invoer en gebruik gestructureerde foutafhandeling voordat je de workflow in een applicatie opneemt. Raadpleeg de gedocumenteerde snelheidslimieten, batchlimieten, richtlijnen voor opnieuw proberen en opties voor het leveren van updates voor jouw account. Ga er niet blind van uit dat registratie veilig opnieuw kan worden geprobeerd na een time-out: de server kan het verzoek hebben verwerkt, ook al heeft je client de response niet ontvangen.

Voeg tests toe voor ongeldige inloggegevens, ongeldige JSON, een ongeldig zendingsnummer, een al geregistreerde zending, niet-beschikbare trackinggegevens en een netwerktime-out. Elk geval moet leiden tot een weloverwogen resultaat van de applicatie in plaats van een onverwerkte uitzondering of een misleidende status voor de klant.

FAQ

Kan ik testen zonder een echt trackingnummer?

Je kunt bepaalde validatiebewerkingen testen met een ongeldige waarde, maar daarmee verifieer je geen tracking van een zending. Gebruik voor het testen van echte gebeurtenissen een geautoriseerde zending of een gedocumenteerde testfixture als de service die aanbiedt. Ga er niet van uit dat willekeurige voorbeeldnummers bij een sandbox horen.

Waarom bevat een HTTP 200-response toch een fout?

HTTP-status en applicatieresultaten beschrijven verschillende lagen. Een server kan een verzoek succesvol ontvangen en verwerken terwijl hij meldt dat een afzonderlijke zending is afgewezen. Lees de response-body en het gedocumenteerde resultaat op zendingsniveau, niet alleen de HTTP-status.

Waarom wordt POST gebruikt om trackinginformatie op te halen?

Gebruik de methode die in het endpointcontract is gespecificeerd. Dit voorbeeld voor het ophalen accepteert zendingsidentificatoren in een JSON-requestbody via POST. Als je dit wijzigt in GET omdat de bewerking gegevens leest, behoud je het gedocumenteerde verzoek niet.

Moet ik het API-token in JavaScript van de browser plaatsen?

Neem geen privé-API-inlogcredential op in publiek geleverde frontendcode. Routeer verzoeken via een geautoriseerde backend die de credential beschermt, invoer valideert en bepaalt tot welke zendingsinformatie elke gebruiker toegang heeft.

Heb ik voor productie zowel Postman als curl nodig?

Nee. Het zijn nuttige test- en diagnosetools. Je productieapplicatie kan een geschikte HTTP-client gebruiken. Bewaar een opgeschoond Postman-verzoek of curl-commando als reproduceerbare referentie, zonder live token of onnodige klantgegevens.

Bronnen