Bpost koppelen aan je TMS: stap voor stap

Je hebt bpost al draaien voor NL/BE-pakketten, maar de koppeling naar je TMS staat nog los. Dat betekent handmatig labels trekken in de bpost-portal terwijl de rest van je carriers al via je TMS-dashboard loopt. Dit artikel neemt je stap voor stap door het koppelen van de bpost Shipping Manager API aan je TMS: van account-ID en passphrase tot label genereren en track & trace terugkoppelen. Reken op een halve tot hele werkdag voor de technische kant, plus wachttijd op bpost's kant voor contract en IP-whitelisting.

Wat je nodig hebt voordat je begint

Je hebt een zakelijk bpost-contract nodig, geen los webshop-account. Bij het aanmaken van een bpost-account heb je het btw-nummer en mobiele telefoonnummer van het bedrijf nodig, en dit dient om een contractuele zakelijke relatie met bpost aan te vragen. Zonder dat contract kom je niet verder dan een consumentenaccount, en Odoo kan bijvoorbeeld niet koppelen met niet-zakelijke bpost-accounts — dezelfde beperking geldt voor vrijwel elke TMS- of ERP-koppeling.

Zorg dat je de volgende zaken klaar hebt liggen:

• Een actief bpost-contract met toegang tot de Shipping Manager-applicatie in het portaal.
• Toegang tot de bpost Shipping Manager applicatie en al haar modules/plugins vereist dat je bpost-klant bent en gebruikmaakt van je account-ID en passphrase.
• Een technisch aanspreekpunt bij bpost (account manager of de eSolutions-helpdesk) voor IP-whitelisting.
• Een TMS of middleware-laag die custom REST-koppelingen accepteert, of een carrier-module die bpost al ondersteunt.
• Toegang tot de bpack-integratiehandleiding met voorbeeldrequests en XSD's — deze zijn te vinden via de bpack integration manual, diverse voorbeelden en XSD-bestanden op de bpost freshdesk.

Bpost Shipping Manager API koppelen aan je TMS, stap voor stap

De koppeling bestaat uit acht stappen: van contractaanvraag tot een geverifieerde testorder. Sla geen stappen over, want de meeste storingen achteraf komen voort uit een configuratiefout in stap 3 of 4.

1. Vraag het bpost-contract en Shipping Manager-toegang aan. Als je nog wilt starten met bpost, vul je je contactgegevens in via het aanmeldformulier, waarna een sales representative contact opneemt om een afspraak te maken. Zonder dit contract krijg je geen SHM-toegang, punt uit.
2. Haal je account-ID en passphrase op. Log in op het bpost-portaal en ga naar Shipping Manager > Admin > General Settings. Het Account ID is je unieke identificatie, vereist om de link te maken tussen je shop en de bpost-applicaties. De passphrase is de sleutel die gebruikt wordt om de checksum voor de iFrame-integratie en de autorisatie-header voor de webservices te genereren. Let op: de passphrase mag niet langer zijn dan 30 tekens, en je moet zowel de naam van de webshop als de standaardwaarde van de passphrase aanpassen.
3. Laat je IP-adressen whitelisten. Neem contact op met bpost over welke IP-adressen van je servers gewhiteld moeten worden. Zonder deze stap weigert de API calls van je TMS-server — dit staat los van de account-ID/passphrase-fout en wordt vaak over het hoofd gezien omdat de foutmelding er hetzelfde uitziet.
4. Stel zones en tarieven in via Shipping Manager. Wanneer je verzendt met je eigen bpost-contract, moet je elk bestemmingsland handmatig activeren in de Shipping Manager door een prijszone toe te voegen, alle landen te selecteren waarnaar je wilt verzenden en per gewichtsstap een tarief in te voeren. Doe dit vóórdat je orders gaat aanmaken — anders loop je tegen de tarieffout uit de volgende paragraaf aan.
5. Maak een order aan via de SHM API. Gebruik de order-endpoint uit de bpack integratiehandleiding, Shipping Manager API voorbeeldrequests en XSD's om orderreferentie, adres en gekozen dienst mee te sturen. Stuur consequent de juiste ISO-landcode mee, dat scheelt je later een debugsessie.
6. Genereer het label. Roep de label-functie aan met orderreferentie en gewenst formaat. In de veelgebruikte PHP-library van tijsverkoyen ziet dat er zo uit: je roept createLabelForOrder aan met de orderreferentie, het gewenste formaat (bijvoorbeeld A6), een vlag voor retourlabels en of je de PDF-versie wilt, waarna je per label de barcode, het mimetype en de bytes terugkrijgt om als PDF weg te schrijven. Voor bulkverwerking bestaat een vergelijkbare functie voor meerdere orderreferenties tegelijk.
7. Koppel track & trace terug naar je TMS. Bpost biedt twee deeplink-varianten. Je voegt een deeplink naar de bpost eTracker toe met de unieke barcode van het pakket, volgens de structuur track.bpost.cloud/btr/web/#/search met itemCode en postalCode als parameters. Alternatief kun je een deeplink toevoegen op basis van je eigen klantreferentie, wat in de bpost Shipping Manager overeenkomt met je order-ID — handig als je nog geen barcode hebt op het moment dat de klant de trackingpagina opent. Omdat andere klanten mogelijk vergelijkbare ordernummers gebruiken, is het verstandig een ordernummerlogica te hanteren die uniek is, bijvoorbeeld "MyCompany_2015043001" in plaats van "123".
8. Test en verifieer voor je live gaat. Plaats een testorder en controleer drie dingen: geeft de orderstatus "created" terug, is het labelbestand openbaar en afdrukbaar, en heeft het trackingnummer het juiste bpost-formaat. Pas als alle drie kloppen zet je de koppeling live.

De meestvoorkomende configuratiefout — en hoe je hem oplost

De fout die je het vaakst tegenkomt gaat niet over authenticatie, maar over zones. De meldingen "A tariff for a given country is missing, although I'm certain I added it" en "A zone has not been configured, or a country is missing from a zone, although I'm certain I configured it" staan letterlijk in bpost's eigen knowledge base als aparte, veelgestelde probleemcategorie.

De oorzaak is bijna altijd hetzelfde: een mismatch tussen de zone-naam die je in Shipping Manager hebt ingesteld en de ISO-landcode die je TMS daadwerkelijk verstuurt. Controleer dus niet alleen of het land in de zone staat, maar ook of de spelling en code exact overeenkomen met wat je systeem doorgeeft. Een zone "Nederland" die je TMS als "NL" aanlevert werkt meestal wel, maar een zone die je handmatig hebt aangemaakt met een afwijkende naamgeving kan alsnog niet matchen.

De tweede failure mode is authenticatie. Een foutmelding door verkeerd gebruik van account-ID en/of passphrase, of doordat bij API-verbinding de checksum niet correct is opgezet, komt regelmatig voor. Als de standaard-passphrase in je Shipping Manager nog gelijk is aan de default, moet je die om beveiligingsredenen wijzigen naar een zelfgekozen waarde, en let op dat deze niet langer dan 30 tekens mag zijn. Vergeet je dit na een reset, dan werkt de checksum-validatie niet meer en krijg je dezelfde foutmelding terug alsof je credentials verkeerd zijn, terwijl het probleem in werkelijkheid bij de vergeten wijziging zit.

Zelf bouwen of een multi-carrier laag ertussen zetten?

Een directe SHM-koppeling geeft je volledige controle over elk veld en elke foutafhandeling, maar je onderhoudt het zelf: elke wijziging in bpost's XSD's of een nieuwe delivery method (bpack 24h Pro, bpack Bus, bpack World Business) betekent code aanpassen. Voor verladers die naast bpost ook DPD, PostNL of GLS draaien, is een multi-carrier laag vaak praktischer dan acht van dit soort losse integraties naast elkaar onderhouden.

Een paar opties die bpost al kant-en-klaar aansluiten, naast eigen bouw:

• Sendcloud — heeft een specifieke bpost-contractactivatie-flow met eigen instructies voor account-ID, passphrase en zone-configuratie.
• Transsmart/nShift — carrier-netwerk met bpost naast DPD en PostNL, gericht op label- en rateflows voor e-commerce.
• DeliveryMatch — ketenregie-TMS gericht op orkestratie tussen meerdere carriers en verzendmethodes.
• Cargoson — biedt één uniforme RESTful API die bpost en 2.000+ vervoerders ondersteunt in Europese en Noord-Amerikaanse markten, met wekelijks nieuwe integraties. Het idee is dat je met bpost en andere carriers via dezelfde endpoints, authenticatie en dataformaten werkt, zodat je Bpost kunt integreren met je ERP, e-commerceplatform of andere software, en één systeem gebruikt om met alle carriers te werken als je er meerdere hebt. Zie de technische documentatie als referentie voor hoe zo'n gelaagde koppeling er in de praktijk uitziet.

Wil je zelf geen polling-logica bouwen voor statuswijzigingen? Vraag dan na of je TMS-leverancier webhooks ondersteunt voor boekingsbevestigingen en zendingswijzigingen, zodat je niet continu de Fetch Order-endpoint hoeft te bevragen om te zien of er al een barcode beschikbaar is.

Checklist voor go-live

• Contract, account-ID en passphrase actief en getest.
• IP-adressen van je serveromgeving gewhiteld door bpost.
• Zones en tarieven gevalideerd met een echte testorder per bestemmingsland.
• Labelformaat (A4 of A6) afgestemd op je printers en pickproces.
• Track & trace-koppeling zichtbaar en klikbaar in je TMS-dashboard.
• Terugvalscenario gedocumenteerd: wat doe je operationeel als de SHM API tijdelijk niet bereikbaar is?

Loop je na deze stappen nog tegen de zone-fout aan, controleer dan eerst je exportbestand vanuit het TMS voordat je bpost belt: negen van de tien keer zit het probleem in de landcode die je systeem verstuurt, niet in de configuratie bij bpost zelf.