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.
• 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.

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 zodat dubbele aanmaak wordt herkend.
• 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.

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