PostNL.
Op maat.

/Technische aanpak

PostNL biedt een SOAP- en REST-API voor verschillende verzendservices. Wij bouwen een solide integratie.

/De PostNL-koppeling in detail

Een PostNL-koppeling verbindt je eigen systeem rechtstreeks met de PostNL API, zodat verzendlabels, track & trace, bezorgopties en retouren volledig automatisch verlopen. Hieronder lees je hoe zo'n koppeling werkt, wat de API biedt, hoe wij hem bouwen en welke valkuilen je voorkomt.

Waarom je systeem aan PostNL koppelen?

PostNL is verreweg de grootste pakketbezorger van Nederland, met het dichtste netwerk van afhaalpunten. Naarmate je verzendvolumes groeien, wordt handmatig werken in het PostNL-portaal een knelpunt: labels aanmaken, barcodes kopiëren en bezorgopties instellen kost steeds meer tijd en vergroot de kans op fouten.

Een directe koppeling met de PostNL API automatiseert dit volledig. Je systeem genereert labels, track & trace-codes stromen terug naar je ordersysteem en klanten ontvangen automatisch bezorgupdates. Het resultaat is een sneller, betrouwbaarder en schaalbaarder verzendproces — elke minuut die niet naar kopiëren en plakken gaat, gaat naar je klant.

Wat biedt de PostNL API?

De PostNL API is uitgebreid en ontsluit vrijwel alle diensten die PostNL aanbiedt. De onderdelen die we het vaakst koppelen:

• Shipping API — verzendlabels voor binnenlandse en internationale zendingen, inclusief brievenbuspakketten, standaardpakketten, verzekerde zendingen en grote volumes.
• Track & trace — realtime statusinformatie per barcode, van aanmelding tot aflevering, met verwachte bezorgdatum en uitzonderingen.
• Bezorgopties — de Delivery Options API toont beschikbare opties op postcode en datum (standaard, avondlevering, op afspraak). Ideaal om in je checkout te tonen.
• Afhaalpunten — het PostNL-puntennetwerk opvragen op locatie of postcode, zodat klanten kunnen kiezen voor ophalen in de buurt.
• Adresvalidatie — adressen controleren en aanvullen vóórdat je een label aanmaakt, zodat je mislukte bezorgingen en onnodige retouren voorkomt.
• Retouren — retourlabels aanmaken die de klant kan gebruiken via elk PostNL-punt.
• Statusupdates via webhooks — push-notificaties bij statuswijzigingen, zodat je niet continu hoeft te pollen.

Hoe werkt een PostNL-koppeling?

Je systeem communiceert rechtstreeks met PostNL. Op basis van het afleveradres, het gewicht en de gekozen bezorgoptie genereert de koppeling automatisch een verzendlabel dat direct geprint kan worden — ook als PDF of ZPL op thermoprinters in het magazijn. Een veelgebruikte toepassing is het tonen van bezorgopties in de checkout van je webshop: op postcode en datum ziet de klant welke opties beschikbaar zijn, en de keuze wordt automatisch in het label verwerkt.

Bij grote volumes verloopt de verwerking op de achtergrond, zodat je systeem snel blijft, ook als er honderden labels tegelijk worden aangemaakt. Een goede koppeling betaalt zichzelf terug zodra je meer dan een handvol pakketten per dag verstuurt.

Stappenplan: zo bouwen we een PostNL-koppeling

Wij bouwen een PostNL-koppeling in vijf fasen, zodat hij vanaf dag één betrouwbaar en piekbestendig is:

1. Voorbereiding & sandbox — API-key aanvragen, requirements in kaart brengen en alles eerst opzetten in de PostNL-testomgeving.
2. Labelgeneratie — labels automatisch aanmaken op basis van adres, gewicht en pakkettype, klaar voor thermoprinter of PDF.
3. Bezorgopties in de checkout — beschikbare bezorgopties en afhaalpunten tonen via de Delivery Options en Locatie API.
4. Track & trace en webhooks — statusupdates terug naar je ordersysteem en automatische bezorgmails naar klanten.
5. Monitoring & go-live — logging, retries en alerting inrichten, productiesleutel activeren en gecontroleerd live.

Bekijk ook onze bredere aanpak voor API-koppelingen op maat.

Authenticatie, API-keys en de testomgeving

Voordat je systeem een label kan aanmaken, identificeert het zich bij PostNL met een API-key: een unieke sleutel die je meestuurt in de apikey-header van elk verzoek. PostNL-klanten vragen die aan via het zakelijke portaal MijnPostNL, onder Mijn account > API's beheren, gekoppeld aan het juiste klantnummer (PostNL: How do I get an API key?).

Cruciaal: begin nooit rechtstreeks in productie. PostNL biedt een aparte sandbox-omgeving (api-sandbox.postnl.nl) die functioneel identiek is, met een eigen testsleutel. Pas nadat het testtraject is afgerond ontvang je een productiesleutel (van test naar productie). Een nette koppeling kent beide omgevingen en bewaart sleutels versleuteld, buiten de broncode.

Let op het verschil met veel andere API's: PostNL gebruikt géén OAuth2-flow met access tokens die verlopen en vernieuwd moeten worden. Er is alleen die ene sleutel. Dat maakt de koppeling in de basis eenvoudiger dan een OAuth2-integratie, maar het legt de verantwoordelijkheid voor de sleutel volledig bij jou. Voor het live versturen hoort daar bovendien een zakelijk PostNL-account bij, met een klantnummer en klantcode die je meestuurt bij het aanmaken van zendingen.

Een API-key is een wachtwoord met de deur wagenwijd open als hij uitlekt. Houd hem strikt serverside — nooit in front-endcode, een repository of een openbaar toegankelijke plek.

Van barcode naar track-and-trace in je eigen omgeving

Klanten willen weten waar hun pakket is, en het liefst zonder je klantenservice te bellen. Zodra je een zending aanmaakt, krijg je een unieke barcode terug — het 3S-nummer. Dat nummer koppelt de zending aan je eigen order en is de basis voor track-and-trace: met de Track & Trace API haal je op basis daarvan de bezorgstatus op en toon je die in je eigen klantportaal, je bevestigingsmails of je ordersysteem, in je eigen huisstijl, in plaats van klanten door te sturen naar een externe pagina.

Waar een verzendplatform statuswijzigingen vaak naar je toe duwt, vraag je bij een directe koppeling de status ook zelf op. Bouw dat netjes: vraag statussen op een verstandig ritme op in plaats van continu, respecteer de limieten van de API en werk alleen bij als er echt iets veranderd is. Zo blijft de koppeling snel en belast je de API niet onnodig.

Internationale verzending en douanedocumenten

Voor pakketten buiten de EU is altijd een douaneformulier nodig — een CN22 of CN23, afhankelijk van gewicht en waarde (welk douaneformulier?). De PostNL API ondersteunt dit via het Customs-onderdeel in de Shipping-webservice: inhoudsomschrijving, waarde, land van herkomst en HS-goederencode per artikel. Een koppeling vult die gegevens automatisch uit je order- en productdata, zodat pakketten niet bij de douane blijven hangen door een onvolledig formulier.

Veelgemaakte koppelingsfouten en hoe je ze voorkomt

Een PostNL-koppeling die in een demo werkt, is nog geen koppeling die jarenlang betrouwbaar honderden pakketten per dag verwerkt. De problemen die we het vaakst tegenkomen — en voorkomen:

• Hardgecodeerde sleutels en endpoints — sandbox- en productiesleutel door elkaar of een sleutel in de broncode leidt tot mislukte verzoeken of beveiligingsrisico's. Bewaar sleutels in versleutelde configuratie en maak de omgeving instelbaar.
• Onvolledige adres- of douanegegevens — een ontbrekende huisnummertoevoeging of leeg douaneveld geeft afgekeurde labels. Valideer de gegevens vóór het verzoek, niet erna.
• Geen omgang met tijdelijke storingen — een API kan kortstondig traag of onbereikbaar zijn. Zonder nette afhandeling mislukt een hele batch labels. Probeer het verzoek opnieuw en houd de status per zending bij.
• Dubbele labels — een opnieuw verstuurd verzoek zonder controle maakt twee labels voor één order. Werk met een eigen referentie per zending en idempotente verwerking, zodat dubbele aanmaak wordt herkend in plaats van uitgevoerd.
• Synchroon labels maken tijdens piekdrukte — elk label live aanmaken op het betaalmoment maakt je systeem afhankelijk van de snelheid van PostNL. Verwerk labels op de achtergrond zodat de checkout snel blijft.

Monitoring, retries en foutafhandeling

Een verzendkoppeling is bedrijfskritisch: maakt het systeem geen labels aan, dan staat het magazijn stil. PostNL adviseert om bij statusupdates niet continu te pollen maar push-notificaties via webhooks te gebruiken (Shipping-webservice). Een robuuste opzet combineert drie lagen: retries met uitstel (een tijdelijke storing kost geen verloren label), logging van elk verzoek en antwoord, en monitoring die actief waarschuwt wanneer een batch labels mislukt — in plaats van dat je het pas merkt als een klant belt.

PostNL API rechtstreeks of via een verzendplatform?

Verzendplatformen zoals Sendcloud of MyParcel bieden een tussenlaag die in één integratie meerdere vervoerders ontsluit — praktisch als je snel wilt starten of met veel vervoerders werkt. Een directe PostNL-koppeling levert meer controle: geen afhankelijkheid van de roadmap van een tussenpartij, volledige toegang tot PostNL-specifieke functies en je verzenddata in eigen hand. Voor hoge volumes, een eigen ordersysteem of specifieke procesvereisten weegt die controle vaak zwaarder dan het gemak van een kant-en-klaar platform. Werk je met meerdere vervoerders, dan combineren we PostNL net zo goed met DHL of GLS in één uniforme verzendlaag.

Met welke systemen koppelen we PostNL?

Wij bouwen PostNL-koppelingen als integraal onderdeel van maatwerksoftware voor e-commerce, logistiek en fulfillment — geen generieke plugin met beperkte configuratie, maar een koppeling die exact doet wat jouw proces vereist. We koppelen PostNL aan webshops (WooCommerce, Shopify of maatwerk), ordermanagement- en magazijnsystemen (WMS), ERP-pakketten en eigen applicaties. Of dat nu betekent bezorgopties in de checkout tonen, labels genereren na betaling, retourverwerking automatiseren of een dashboard bouwen waarmee je magazijnteam alle zendingen van de dag in één oogopslag ziet.

PostNL doorkoppelen naar je andere systemen

Een verzendkoppeling staat zelden op zichzelf; de echte winst zit in het doorkoppelen. Een bezorgstatus "afgeleverd" kan een bevestigingsmail triggeren of een order afsluiten. Een geregistreerde retour kan je voorraad bijwerken en een terugbetaling in gang zetten. Verkoop je ook via marketplaces, dan laat je orders uit bijvoorbeeld een Bol.com koppeling via hetzelfde verzendproces lopen.

Zo blijft de hele keten — van order tot bezorging tot administratie — sluitend en zonder dubbel invoerwerk. Dat is precies waar het bij systemen koppelen om draait.

Mijn kijk op verzendkoppelingen

Verzenden voelt als een detail aan de achterkant van je webshop, maar het is precies waar klanten je op afrekenen. Een verkeerd label, een adres dat niet klopt of een track-and-trace die niet werkt, kost je direct vertrouwen. En op de inpaktafel is elke handmatige stap er één te veel zodra het volume oploopt.

Wat ik na jaren koppelingen bouwen zie: de techniek van de PostNL API is niet het moeilijke deel — een label aanmaken en een status ophalen is overzichtelijk. Het verschil zit in de details eromheen. Valideer je adressen? Is je verwerking idempotent? Weet iemand het als een label mislukt? En heb je de juiste keuze gemaakt tussen direct koppelen en een platform? Een koppeling die op mooie dagen werkt is makkelijk. Een koppeling die ook in de piek rond de feestdagen blijft draaien, vraagt om doordachte foutafhandeling en monitoring.

— Jasper

Bronnen: PostNL Developer Portal — API-overzicht, sandbox en API-key-aanvraag · PostNL douane-informatie.