DPD NL API koppelen aan je TMS in zeven stappen

De DPD NL ShipmentService REST API is goed gedocumenteerd, maar de documentatie is modulair opgebouwd over meerdere pagina's: login, storeOrders, Predict, e-label en rate limits staan elk apart. Dit is de volgorde waarin je het zelf bouwt, met de exacte endpoints, velden en foutafhandeling die je nodig hebt om DPD NL API koppelen aan je TMS in één keer goed te doen, zonder een account-ban op te lopen.

Wat je nodig hebt voordat je begint

Je hebt een zakelijk DPD NL-account nodig met toegang tot het developer-portaal, plus gescheiden credentials voor STAGE en Live. Zonder die twee sets werk je per ongeluk in productie terwijl je nog aan het testen bent.

• Een DPD NL zakelijk account met depotnummer (bijvoorbeeld depot 0522) en delisId/wachtwoord voor de login service.
• Aparte credentials voor de STAGE-omgeving en de Live-omgeving. Een token gegenereerd op de Stage-omgeving werkt niet op de Live-omgeving en andersom.
• Een TMS of middleware die uitgaande REST-calls met JSON kan doen en een bearer token in de header kan cachen (niet bij elke aanroep opnieuw opvragen).
• Minimaal TLS 1.2, oudere versies worden niet ondersteund.
• Testadressen en een paar dummy-zendingen om de STAGE-omgeving te doorlopen voordat je live gaat.

De zeven stappen om DPD NL te koppelen

Hieronder de complete flow van authenticatie tot een printbaar label in je TMS. Volg de volgorde: token eerst, dan storeOrders, dan pas Predict en e-label als extra opties.

Testen in STAGE voordat je live gaat

Voordat je live-credentials gebruikt, draai je het volledige scenario in de testomgeving. Labels die op de STAGE-omgeving zijn gegenereerd, zijn niet geldig en mogen niet voor live zendingen worden gebruikt. Checklist voor deze stap: testadres met een herkenbaar testformaat, een gewicht dat binnen normale grenzen valt, controle van het labelformaat (A4 versus thermisch printerformaat) en controle of de Predict-melding daadwerkelijk binnenkomt op je testmailbox.

Rate limits en volgordelijkheid respecteren

Dit is de stap waar de meeste zelfbouw-koppelingen misgaan, omdat parallelle threads logisch lijken maar hier verboden zijn. Slechts één API-aanroep tegelijk is toegestaan; pas als de service heeft gereageerd op de eerste aanroep mag een nieuwe verstuurd worden, en meerdere shipment service-aanroepen tegelijk versturen is verboden. Concreet: het genereren van één label duurt gemiddeld ongeveer 1 seconde, wat bij sequentieel werken met 100% buffer een veilige limiet geeft van 30 labels per minuut of 1.800 per uur. Bouw je TMS-koppeling dus als een queue met sequentiële verwerking, niet als een pool van gelijktijdige workers, ook niet als je vanaf meerdere IP-adressen verstuurt.

Optioneel: e-label voor pakketpuntafgifte

Voor klanten die zonder printer bij een DPD-pakketpunt willen afleveren, is er een alternatief. In plaats van het reguliere label kun je ook een e-label maken, een digitale QR-code die op een DPD-pakketpunt gescand wordt waarna het label daar wordt geprint. Let op: om de nieuwe e-label-service te implementeren en gebruiken is een upgrade naar ShipmentService 3.5 vereist, en DPD stelt alleen het label beschikbaar; het is je eigen verantwoordelijkheid om het label bij de klant te krijgen. Zorg dus dat je TMS de QR-afbeelding automatisch naar de klant mailt of in de order-tracking toont.

Label ontvangen en verwerken in het TMS

Bij een geslaagde aanroep krijg je het label direct terug in de response, geen aparte download-stap nodig. Bij een succesvolle ShipmentService-aanroep antwoordt het systeem met een Base64-string in het parcellabelsPDF-veld en een 14-cijferig pakketnummer in het parcelLabelNumber-veld. Je TMS moet die Base64-string decoderen naar een printbaar PDF en het aan de juiste zendingsregel koppelen, en het parcelLabelNumber gebruiken als trackingreferentie richting klant en WMS.

Predict-melding toevoegen voor de ontvanger

Wil je dat de ontvanger vooraf een bericht krijgt over de bezorging, dan voeg je het Predict-blok toe. Binnen de productAndServiceData-sectie, onder orderType, voeg je de predict-sectie toe met velden channel, value en language. Voor een e-mailmelding in het Nederlands zet je channel op 1, value op het e-mailadres van de ontvanger en language op NL. Dit werkt voor vrijwel elk DPD-product, je hoeft er geen apart contract voor af te sluiten.

Zendinggegevens mappen naar storeOrders

Voor het daadwerkelijke label gebruik je de storeOrders-methode. storeOrders wordt gebruikt om parcel labels te genereren, inclusief retourlabels, via een POST naar ShipmentService/V3_5/storeOrders. Minimaal vul je adresdata, gewicht en productAndServiceData in; die laatste bepaalt welk DPD-product (Classic, Predict-only, etc.) je afneemt. Houd rekening met de dagelijkse deadline: een request is definitief en wordt gefactureerd zodra de API deze accepteert, ook als de aanvraag foutieve of onvolledige data bevat, en orders moeten vóór 22u00 zijn ingevoerd om de volgende werkdag te worden uitgevoerd. Bouw dus verplichte-veldvalidatie in je TMS in vóórdat de call de deur uitgaat, niet erna.

Token ophalen via de login service

Elke aanroep naar de shipment service vereist een geldig token. Een request aan de shipment service slaagt alleen met een actief authenticatietoken, dat je opvraagt via de login service en dat 24 uur geldig is. Je post delisId, password en messageLanguage naar de LoginService/V2_1/getAuth-endpoint en krijgt een authToken plus een authTokenExpires-timestamp terug. Cache dat token in je TMS: elk token is één werkdag CET/CEST geldig en moet gecached worden, want de login service meer dan 10 keer per dag aanroepen is niet toegestaan. Bouw dus geen logica die bij elke labelaanvraag opnieuw inlogt.

Hoe je weet dat het werkt, en wat je doet als het misgaat

Succes is meetbaar: een geldig 14-cijferig parcelLabelNumber, een label dat print zonder foutmeldingen, en een pakket dat zichtbaar wordt in het DPD-trackingsysteem zodra het gescand is bij het depot. Werkt een van die drie niet, dan zit het probleem meestal in het token, de rate limit of onvolledige velden.

De meest voorkomende faalmodus is niet een crash, maar een stille factuur. Zoals hierboven al genoemd: een verzoek dat door de API wordt geaccepteerd, wordt gefactureerd, zelfs met verkeerde of onvolledige gegevens. Valideer daarom verplichte velden (adres, postcode-formaat, gewicht) in je TMS vóórdat je de call verstuurt, niet als reactie op een foutcode. Een tweede veelvoorkomend probleem is een verlopen token dat je niet op tijd ververst; bij een verlopen authenticatie geeft elke DPD Shipper Webservice-service een bijbehorende foutcode terug, en bij ontvangst daarvan moet je verplicht opnieuw inloggen en een nieuw token cachen. Bouw die foutcode-check dus als vaste stap in je retry-logica, in plaats van blind te vertrouwen op de 24-uurs geldigheidsduur.

Zelf bouwen versus een multi-carrier laag

Als je alleen DPD NL verstuurt, is een directe koppeling op de native API prima te overzien: één login-endpoint, één storeOrders-call, één rate limit om rekening mee te houden. Draai je daarnaast PostNL, GLS en bpost, dan bouw je feitelijk drie tot vier keer dezelfde queue-logica met net iets andere velden en foutcodes per carrier. Multi-carrier lagen zoals Cargoson, ShippyPro, Sendcloud en EasyPost bieden DPD NL al kant-en-klaar naast tientallen andere carriers, wat de bouwtijd verkort maar ook betekent dat je een extra laag tussen je TMS en de carrier hebt zitten.

Voor een NL-parcel profiel met alleen DPD is de native route logisch, zeker als je al REST-ervaring in huis hebt. Zodra er een derde of vierde carrier bijkomt, weegt de extra bouwtijd van elke aparte koppeling meestal niet meer op tegen wat een multi-carrier laag je bespaart aan onderhoud.

Volgende stap

Begin met de STAGE-omgeving en bouw eerst alleen de basisflow: token ophalen, storeOrders versturen, label opslaan. Voeg Predict en e-label pas toe als die basis foutloos draait, en test de rate limit expliciet door bewust 40 labels achter elkaar aan te vragen in STAGE om te zien hoe je TMS reageert op een throttling-foutcode. Dat voorkomt dat je dit soort verrassingen pas ontdekt op je eerste drukke maandag in productie.