PostNL Shipping API koppelen aan je TMS

Je wilt zendingen aanmaken, labels printen en status terugmelden in je TMS, zonder dat je voor elke wijziging bij PostNL een developer moet bellen. Deze handleiding loopt de PostNL Shipping API koppelen stap voor stap door: van sandbox-key tot live labelaanvraag, plus de twee wijzigingen die PostNL voor 2026 heeft aangekondigd en die je koppeling kunnen breken als je er niet op voorbereid bent.

Wat je nodig hebt voordat je begint

Je hebt een account op het PostNL developer portal nodig, met een sandbox-apikey en later een productiekey. Daarnaast heb je je CustomerCode en CustomerNumber nodig (die krijg je bij je PostNL-contract), en minimaal één testzending met een geldig NL- of BE-adres om de eerste labelaanroep te valideren.

Begin niet met losse code schrijven voordat je de documentatie hebt doorgenomen. PostNL biedt alle API's als Postman collections aan, wat testen aanzienlijk versnelt ten opzichte van zelf requests opbouwen op basis van de SOAP- of REST-documentatie. Test eerst in de sandbox-omgeving met een paar verschillende productcodes (binnenland, brievenbuspakje, EU) voordat je iets in productie zet.

Stap 1: kies de juiste API-laag voor je TMS-koppeling

Voor nieuwe koppelingen kies je de Shipping API, niet de losse Barcode-, Labelling- en Confirming-services. De Shipping API combineert de functionaliteit van de Labelling-, Confirming-, Barcode- en Easy Return API's, wat implementatie eenvoudiger maakt en overhead vermindert bij het aanvragen van deze services. Voor de meeste verladers die net beginnen met een PostNL-koppeling in hun TMS is dit de voor de hand liggende keuze.

Heb je al een bestaande ERP-koppeling die met losse Barcode- en Labelling-calls werkt? Dan hoef je niet meteen alles om te bouwen. Voor de meeste producten kun je de barcode weglaten uit de Shipping API en wordt deze automatisch gegenereerd. Kies je toch voor een aparte barcode-aanroep, automatiseer dan de twee API-calls (Barcode en Labelling) en gebruik de ontvangen barcode direct als input voor de Labelling API.

Belangrijk om te weten: de nieuwere API-versies vervangen de oudere, verbeteren de performance en maken integratie eenvoudiger en schaalbaarder, met stabielere en voorspelbaardere updates. Als je nu nog op een oude v1-integratie draait, is dit het moment om te migreren, niet nadat PostNL een deadline aankondigt.

Bouw je liever niet zelf de vertaallaag tussen je TMS en de PostNL-API? Sendcloud, nShift, ShipStation/ShipEngine en Cargoson bieden deze koppeling kant en klaar aan, met verschillende accenten:

Stap 2: bouw de labelaanvraag op met de juiste velden

Een labelaanvraag in de Shipping API bestaat uit een aantal verplichte structuren: het AddressType (01 voor de ontvanger, 02 voor de afzender), het ProductCodeDelivery voor het gekozen verzendproduct, en de barcode (optioneel, zie stap 1). Voor multicollo-zendingen, denk aan een pallet met meerdere colli richting hetzelfde adres, komt er een extra laag logica bij.

1. Maak per pakket een apart verzoek aan om een label op te vragen of de zending te bevestigen.
2. Koppel de pakketten aan elkaar via het Group type in elk verzoek.
3. Geef het aantal pakketten in de zending (GroupCount), het volgnummer van het specifieke pakket (GroupSequence) en de hoofdbarcode van de zending (MainBarcode) mee, en specificeer Multicollo als GroupType (GroupType 03).
4. Controleer dat elk pakket een eigen barcode heeft voordat je het verzoek verstuurt.
5. Bevestig de zending (Confirming), los of gecombineerd met de labelaanvraag.

Let op drie beperkingen die vaak over het hoofd worden gezien. Elk pakket in de multicollo-zending moet een eigen, unieke barcode hebben. Voor Extra@Home- en Cargo-zendingen kunnen de verzoeken niet los worden gedaan voor multicollo-zendingen; deze moeten in één gezamenlijk verzoek worden bevestigd. En: multicollo is niet beschikbaar voor EU-zendingen, Mail-pakketten en retouren. Bouw deze validatie in je TMS-regels in, anders krijg je pas bij de PostNL-respons te horen dat het verzoek niet klopt.

Stap 3: koppel de Shippingstatus API voor track & trace in je dashboard

Wil je near-realtime statusinformatie tonen in je eigen TMS of klantportaal, dan gebruik je de Shippingstatus API naast de Shipping API. Op basis van barcode of zendingreferentie kun je de status van pakketten opvragen; zowel de actuele status als de complete status, die een overzicht geeft van alle statussen die het pakket tijdens het distributieproces krijgt.

Voor periodieke synchronisatie in plaats van losse polling per barcode gebruik je een andere methode: met de Updatedshipments-methode haal je alle bijgewerkte statussen op over een gedefinieerde periode, en met de GetSignature-methode vraag je de handtekening van de ontvanger op, indien beschikbaar. Dat scheelt je duizenden losse API-calls als je honderden zendingen per dag verwerkt.

Deze data gebruik je niet alleen intern. Je kunt de respons van de Shippingstatus API gebruiken om klanten proactief te informeren over de status van hun pakketten, of om de status automatisch te tonen of bij te werken, bijvoorbeeld in een klantenserviceportaal. Voor een B2B-verlader met een track&trace-widget op de klantomgeving is dit vaak de belangrijkste reden om de Shippingstatus API apart te koppelen, los van de labelflow.

Stap 4: testen in sandbox, live zetten en de printkwaliteit checken

Je weet dat de koppeling werkt als drie dingen kloppen: de testzending krijgt een geldige barcode terug, het label print scanbaar op je thermische of laserprinter, en de Shippingstatus API geeft binnen enkele minuten een status als "aangeboden" of "in transit" terug voor die barcode.

Eén ding wordt vaak onderschat: printkwaliteit. Pakketten lopen soms vertraging op door slecht geprinte verzendlabels, omdat de barcode niet gescand kan worden; let daarom goed op de printkwaliteit van je labels, zodat PostNL slimmer kan sorteren en sneller kan leveren. Dit is geen theoretisch probleem: een verkeerd geconfigureerde thermische printer, verkeerde DPI-instelling, of een oud lint kan een technisch perfecte API-koppeling toch laten stranden op de sorteerband.

Faalmodus: twee PostNL-wijzigingen in 2026 die je koppeling kunnen breken

PostNL heeft twee concrete wijzigingen aangekondigd die directe impact hebben op bestaande integraties. Beide staan in het changelog van PostNL, en beide zijn het waard om nu al in je testomgeving te controleren, niet pas na livegang.

Wijziging 1: postbus-restrictie vanaf 24 februari 2026

Vanaf 24 februari 2026 zijn Delivery Code-zendingen met een postbusnummer als ontvangeradres niet meer aan te maken via IT-oplossingen. De reden is functioneel: de Delivery Code-service vereist de fysieke aanwezigheid van de ontvanger om de verificatiecode als bewijs van levering te geven, en postbussen zijn onbemand met een ander overdrachtsproces, waardoor deze code niet betrouwbaar ingevoerd of geverifieerd kan worden, met als gevolg dat de levering niet afgerond kan worden. PostNL bouwt hier validatie voor in: om te voorkomen dat onbezorgbare zendingen het netwerk instromen, wordt validatie afgedwongen over alle versies van de Labelling-, Confirming- en Shipment-API's.

Wat je nu al kunt doen: valideer het adrestype vóór je de labelaanvraag verstuurt, en bouw een fallback-product in je TMS-regels voor de gevallen waarin een klant toch een postbusadres invoert bij een Delivery Code-zending. Wacht niet tot PostNL de aanvraag afwijst, want dan zit die zending al in je orderproces vast.

Wijziging 2: labellay-out brievenbuspakjes+ vanaf 12 juli 2026

Vanaf 12 juli 2026 gaan brievenbuspakjes+ (24 uur) die vooraf zijn aangemeld met productcodes 2928 en 2929 over van het postnetwerk naar het pakkettennetwerk, waardoor ze vanaf die datum door het pakketbezorgnetwerk in plaats van het postbezorgnetwerk worden afgehandeld. Dat klinkt als een operationele wijziging, maar heeft ook technische impact: de labellay-out voor dit product verandert, en de v2 API's (Shipping v2 en Labelling v2) genereren en retourneren vanaf die datum automatisch een nieuw labelformaat, al blijft de output in liggende oriëntatie.

Voor koppelingen via de API zelf hoef je niets aan te passen: bij vooraankondiging via de API is geen actie vereist, want de API genereert automatisch het nieuwe labelformaat voor productcode 2928 en 2929, brievenbuspakje+. Maar test dit toch vooraf in de sandbox, vooral als je een eigen labelrenderer of printersjabloon gebruikt bovenop de PDF die PostNL teruggeeft. Een label dat qua lay-out net anders is dan waar je printertemplate op is afgestemd, is precies het soort verrassing die je liever in juni ontdekt dan op 13 juli.

Waar dit past in je bredere carrier-koppelstrategie

Als je naast PostNL ook DPD NL, GLS en bpost los aan je ERP of WMS koppelt, bouw je deze labelaanvraag-, barcode- en statuslogica in feite drie of vier keer opnieuw, met net weer andere veldnamen en foutcodes per carrier. Multi-carrier oplossingen zoals Sendcloud, nShift, ShipStation en Cargoson bieden deze koppelingen voorgebakken aan, inclusief de PostNL Shipping API en Shippingstatus API, zodat je die onderhoudslast niet zelf draagt bij elke API-wijziging.

Voor wie zelf blijft bouwen: houd het PostNL developer portal in de gaten voor toekomstige changelog-updates, en test iedere wijziging eerst in de sandbox-omgeving voordat je live gaat. Dat is minder werk dan een productieprobleem oplossen op de dag dat een wijziging ingaat.