Providerhandleidingen
PostNL: instellen en beheren
Maak PostNL-barcodes en verzendetiketten aan, haal tracking op en vraag optioneel bezorgoffertes op.
Op deze pagina
Werkwijze bij de provider
Maak PostNL-barcodes en verzendetiketten aan, haal tracking op en vraag optioneel bezorgoffertes op. Dit is de vervoerderadapter voor Shipping, niet een vervanging voor verzendzones, eigen tarieven of een PostNL-account. Etiketten worden op de lokale opslagschijf van de applicatie bewaard.
Vereisten
Agovena Core ^0.0.1. Activeer Shipping vóór deze uitbreiding.
Deze uitbreiding is niet als productierijp gemarkeerd. Controleer de ondersteunde werkwijze in je eigen testomgeving voordat je klantbestellingen aanneemt.
Het pakket instellen
Activeer Shipping en PostNL en voer hun migraties uit. Stel api_key, customer_code en customer_number in. collection_location is optioneel, sandbox staat standaard aan en default_product_code is standaard 3085. Vul correcte verzendadressen en productgewichten in. Controleer of je PostNL-overeenkomst de gekozen dienst en bestemming ondersteunt voordat je die aanbiedt.
Providerspecifieke grenzen
De API-client kiest via sandbox tussen api-sandbox.postnl.nl en api.postnl.nl en verstuurt de header apikey. De client gebruikt endpoints voor barcodes, zendingen, status en checkout. HTTP 401 of 403 wordt als configuratiefout behandeld, 400 als ongeldig adres en 422 als niet-ondersteunde bestemming. Dat zijn andere situaties dan een onbereikbare provider.
Test een volledig Nederlands adres en daarna een niet-ondersteunde bestemming. Controleer barcode, opgeslagen etiket en tracking voor dezelfde zending. Controleer echte offertebedragen voordat je liveoffertes gebruikt: een optie zonder prijs kan op nul uitkomen. Bepaal bewust wat er gebeurt als offertes ontbreken. Bekijk na een time-out eerst de bekende barcode of externe zending voordat je een nieuw etiket aanvraagt. Testgegevens en testetiketten zijn geen productieovereenkomst voor verzending. 2
Configuratiecontract
| Veld | Type | Verplicht | Geheim | Standaard |
|---|---|---|---|---|
api_key |
string |
Ja | Ja | Leeg |
customer_code |
string |
Ja | Nee | Leeg |
customer_number |
string |
Ja | Nee | Leeg |
collection_location |
string |
Nee | Nee | Leeg |
sandbox |
boolean |
Nee | Nee | true |
default_product_code |
string |
Nee | Nee | "3085" |
Dit zijn de velden uit het manifest. Een optioneel veld kan voor een API-handeling toch noodzakelijk zijn, zoals hierboven beschreven. Bewaar geheime waarden alleen in beschermde instellingen, nooit in productbeschrijvingen, URL’s of gedeelde voorbeelden. 1
Werking en foutafhandeling
Onvolledige adressen of fouten bij de offerte-API leveren geen liveoffertes op. Voor etiketten worden straat en huisnummer gecontroleerd. Dienstcode 3085 wordt buiten Nederland geweigerd. Een bestaande koppeling tussen bestelling en barcode wordt hergebruikt. Ontbrekende of ongeldige etiketgegevens geven een fout in plaats van een lege PDF. Annuleren via deze adapter is niet ondersteund. Volg daarvoor het vervoerdersproces; lokaal annuleren trekt het etiket niet vanzelf in.