DHL Parcel API koppelen aan je TMS in 6 stappen

Je bouwt een koppeling tussen je TMS en DHL Parcel EU (BE-LU-NL), en na tien minuten zoeken in de developer-documentatie heb je meer vragen dan antwoorden. Dat is normaal: DHL Parcel API koppelen vraagt om een paar stappen die nergens in één document naast elkaar staan. Deze handleiding loopt het hele proces door, van sleutel tot werkende label- en trackingflow, met de exacte endpoints die je nodig hebt.

Wat je vooraf nodig hebt

Zonder deze vier dingen kom je niet verder dan een foutmelding op stap 1.

• Een zakelijk account bij My DHL Parcel voor Nederland, België of Luxemburg. Zonder account krijg je geen API-toegang; om de DHL Parcel EU (BE-LU-NL) API te gebruiken heeft je organisatie een actief klantaccount nodig bij een van de DHL Parcel-landen.
• Een sandbox key om te testen zonder live labels te genereren. Deze verzamel je apart via je My DHL Parcel-account, zoals de documentatie aangeeft: voor testen verzamel je je API sandbox key via My DHL Parcel.
• Een TMS of middleware met een custom HTTP-koppelmodule, of een developer die dat voor je bouwt.
• Basiskennis van REST, JSON en HTTPS. DHL is daar zelf duidelijk over: de DHL Parcel EU (BE-LU-NL) API is ontwikkeld voor en door developers, en je hebt kennis nodig van REST API's, JSON en HTTPS, naast een zakelijk account bij My DHL Parcel.

Stap 1: API-sleutel aanmaken in My DHL Parcel

Je genereert je user-id en key via het instellingenmenu van je account, niet via de developer portal zelf. Dat onderscheid verwart veel mensen die net beginnen met DHL Parcel API koppelen.

1. Log in op My DHL Parcel voor het land waar je account draait (NL, BE of LU).
2. Ga naar "Instellingen" via het gebruikersmenu.
3. Klik op "CREATE API KEY" in het tabblad "API KEYS". Volgens de documentatie: door in het gebruikersmenu "Settings" te selecteren en op de knop "CREATE API KEY" te klikken in het tabblad "API KEYS", worden de user-id en key gegenereerd.
4. Bewaar deze gegevens direct. De informatie wordt maar één keer gegeven, en wanneer je de knop opnieuw indrukt, wordt een nieuwe user-id en key gegenereerd die de vorige overschrijft en ongeldig maakt.

Dit user-id/key-paar gebruik je zo voor precies één ding: de eerste authenticatiecall. Niet voor losse requests daarna.

Stap 2: Authenticeren en tokens beheren

De DHL Parcel EU API werkt met een access/refresh token-flow, geen simpele API-key-header per request. Dat is de eerste plek waar koppelingen vastlopen als je het verkeerd bouwt.

De flow werkt zo: de user-id en key worden gebruikt om de eerste call te maken naar het Authenticate API key endpoint, en als antwoord geeft dat endpoint zowel een access token als een refresh token terug. In de praktijk stuur je dit naar https://api-gw.dhlparcel.nl/authenticate/api-key met je userId en key in de body, en krijg je een JSON-respons terug met accessToken, accessTokenExpiration, refreshToken en refreshTokenExpiration, plus een lijst accountNumbers gekoppeld aan je key. De vervaltijd staat expliciet in de respons: de access token is geldig voor een beperkte tijd, aangegeven via het antwoordattribuut 'accessTokenExpiration'. Zodra die verlopen is, hoef je niet opnieuw met user-id en key te authenticeren: dan kun je opnieuw toegang krijgen door een nieuwe access token op te halen met de refresh token via het Authenticate refresh token endpoint. Dat tweede endpoint is https://api-gw.dhlparcel.nl/authenticate/refresh-token.

De refresh token leeft veel langer. Houd er rekening mee dat ook deze refresh token een vervaldatum heeft, maar die is significant langer dan die van de access token. Bouw dus automatische token-refresh in je koppeling: sla de expiration-timestamp op, check die voor elke batch, en ververs proactief in plaats van te wachten op een 401. Nachtelijke batchverwerking (denk aan verzamelde bestellingen die om 23:00 uur worden verlabeld) loopt anders vast op een verlopen token terwijl niemand kijkt.

Stap 3: Capabilities checken vóór verzending

Niet elke combinatie van land, postcode en dienst is beschikbaar. Sla deze check over en je krijgt mislukte labelaanvragen op momenten dat je het niet kunt gebruiken, bijvoorbeeld tijdens piekdrukte.

DHL biedt hiervoor een los endpoint: de Capability Service API checkt of de geselecteerde opties, diensten en het type zending beschikbaar zijn voor elke dienst of elk land. De kernservices van de bredere API zijn capabilities check, pickup request, label creation, time windows en tracking.

Voor een NL-webshop die ook naar België en Luxemburg verzendt is dit geen formaliteit. Avondlevering of afleveren op een ophaalpunt is niet overal en niet voor elke dienst beschikbaar. Check dus per bestemmingsland welke opties je kunt aanbieden, vóórdat je die opties in je checkout toont.

Stap 4: Label en zending aanmaken

Met een geldige access token kun je de shipment-payload versturen. De verplichte velden zijn ontvangernaam, straat, postcode, plaats en landcode, plus een referentie voor je eigen orderadministratie.

Voor cross-border zendingen buiten de EU, denk aan retouren via het VK, komen er twee extra velden bij: een btw-nummer en een EORI-nummer van de ontvanger. Zonder EORI-nummer loop je vast bij de douane, want douaneautoriteiten hebben de EORI-nummers van zowel afzender als ontvanger nodig om de partijen bij de transactie correct te identificeren. Voor pure BE-LU-NL zendingen binnen de EU zijn deze velden niet nodig; je gebruikt ze specifiek bij grensoverschrijdende zendingen buiten de douane-unie.

Heb je geen vaste dagelijkse ophaaltijd ingesteld bij DHL, dan regel je de ophaling via een los endpoint: de API-service "pickup request" geeft je de mogelijkheid om een ophaling van je zending aan te vragen, dus je pakketten, colli en/of pallets. Let op: het aanmaken of downloaden van een label vormt op zich nog geen vervoerscontract; dat contract komt pas tot stand zodra de gelabelde zending wordt opgehaald en geaccepteerd door DHL. Voor je TMS betekent dit dat "label aangemaakt" en "zending onderweg" twee verschillende statussen zijn, en dat je die niet door elkaar moet laten lopen in je facturatielogica.

Stap 5: Track & trace koppelen aan je TMS

Dit is het deel waar de meeste koppelingen hun waarde tonen: automatische statusupdates in plaats van klanten die zelf op de DHL-website moeten zoeken.

Het endpoint combineert barcode en postcode tot één sleutel: curl -X GET "https://api-gw.dhlparcel.nl/track-trace?key=3SBPB0000094346+9999AA" -H "Accept: application/json". De barcode komt uit de respons van je label-aanroep, de postcode is die van de ontvanger. Samen vormen ze de key-parameter, gescheiden door een plusteken.

Twee velden zijn relevant voor je TMS-statuslogica:

• deliveredAt: het feit dát, en wanneer, een pakket daadwerkelijk is afgeleverd wordt gecommuniceerd via het attribuut 'deliveredAt' op het hoogste niveau van de JSON-respons.
• pod: als er een handtekening beschikbaar is en de aanvraag is gedaan met trackingcode en postcode van de ontvanger, bevat de respons een veld pod met de URL naar de POD-afbeelding.

Koppel deliveredAt terug naar je TMS als trigger: zodra dit veld gevuld is, kun je automatisch de klant notificeren of de facturatiestatus bijwerken. Wil je niet elke paar minuten pollen, kijk dan naar de Track & Trace Pusher, die werkt op basis van webhooks in plaats van herhaalde GET-requests.

Stap 6: Testen, rate limits en go-live

Twee faalmodi kom je vrijwel gegarandeerd tegen. Beide zijn op te lossen zonder DHL-support te bellen.

Rate limiting. DHL beschermt de eigen infrastructuur actief: rate limits beschermen de DHL-infrastructuur tegen verdachte requests die vastgestelde drempels overschrijden, en wanneer de limiet is bereikt ontvang je een specifieke HTTP-statuscode. Bouw retry-met-backoff in je koppeling: bij een rate-limit-response wacht je een paar seconden en probeer je opnieuw, in plaats van meteen te herhalen en de limiet verder te belasten.

Verlopen refresh token na lange inactiviteit. Test je koppeling een paar weken niet, dan kan zelfs de langlevende refresh token verlopen zijn. Los dit op met een dagelijkse health-check die een dummy-call doet, zodat je dit merkt vóórdat een klant een label niet krijgt.

Voordat je live gaat, doorloop je een volledige testcyclus in de sandbox:

1. Authenticeer met je sandbox user-id en key, controleer of je een geldige accessToken terugkrijgt.
2. Maak een testlabel aan en noteer de barcode uit de respons.
3. Vraag track & trace op via barcode plus postcode en controleer of de respons correct opbouwt.
4. Simuleer een aflevering (of wacht een echte sandbox-update af) en controleer of deliveredAt gevuld wordt.

Pas als deze vier stappen zonder handmatig ingrijpen werken, schakel je over naar je live user-id en key.

Waar dit past in je bredere carrier-mix

DHL Parcel is voor de meeste NL/BE-verladers niet de enige carrier. PostNL, DPD en bpost lopen er meestal naast, en elke carrier heeft zijn eigen auth-flow, veldnamen en rate limits. Bouw je dit zelf per carrier, dan onderhoud je straks vier verschillende token-refreshmechanismen en vier verschillende manieren om een POD op te halen.

Een alternatief is een kant-en-klare multi-carrier laag die deze koppelingen al heeft gebouwd en onderhoudt. Denk aan nShift, Sendcloud, ShipStation of Cargoson, die dit soort carrier-koppelingen als standaardfunctie aanbieden in plaats van dat jij ze zelf bouwt. Welke van de vier het beste past hangt af van je volume, je bestaande ERP/WMS-stack en of je meer waarde hecht aan tariefvergelijking of aan flexibele koppelbaarheid; dat is een aparte afweging die verdere uitwerking verdient.

Voor nu: als je DHL Parcel als losse koppeling bouwt, begin met de sandbox key, bouw de token-refresh goed vanaf dag één, en test de volledige cyclus van label tot POD voordat je ook maar één live zending verstuurt.