Ga naar de inhoud
agovena.
agovena.
Aan de slag
Community

Providerhandleidingen

PostNL: instellen en beheren

Maak vooraangemelde PostNL-zendingen met barcode en label, volg tracking en gebruik geprijsde PostNL-bezorgopties wanneer die beschikbaar zijn.

Op deze pagina

Status en werkwijze

De PostNL-extension is een vervoerder voor de verzendfuncties in Agovena Core. De extension maakt een vooraangemelde PostNL-zending met barcode en label, leest tracking uit en kan geprijsde PostNL-bezorgopties aan de checkout toevoegen. Het is een Extension, geen Module: orders, producten en adressen houden hun generieke Core-velden, en PostNL-barcodes, labels en productcodes blijven binnen deze extension.

Production-ready voor de gedocumenteerde scope. Elke bewerking onder Ondersteunde bewerkingen is gebouwd op de PostNL REST-API's voor barcodes, labels, zendingstatus en checkout en geverifieerd met geautomatiseerde tests die de provider vervangen door gesimuleerde HTTP-antwoorden, zonder netwerkcalls. Live acceptatie op je eigen PostNL-account blijft de verantwoordelijkheid van de beheerder: maak één zending, download het label en volg de tracking met je eigen PostNL-contract voordat je klantorders verzendt. Bewerkingen onder Niet ondersteund worden niet aangeboden.

Vereisten

  • Agovena Core ^0.0.1. Fysieke verkoop en verzending zijn onderdeel van Core, dus er is geen extra Module nodig.
  • Een PostNL API-contract met API-key, klantcode en klantnummer.
  • Volledige verzendadressen. De extension haalt straat en huisnummer uit de eerste adresregel.

Het pakket instellen

  1. Open Admin > Extensies en activeer PostNL.
  2. Sla de API-key, klantcode en klantnummer op. De API-key wordt versleuteld en nooit opnieuw getoond.
  3. Stel desgewenst collection_location in. Laat sandbox aan voor tests (https://api-sandbox.postnl.nl) en zet die uit met live gegevens (https://api.postnl.nl).
  4. Houd je verzendmethoden en tarieven in Core ingesteld. De checkout blijft die voor prijzen gebruiken.
  5. Fulfillment gebruikt de gekozen productcode of default_product_code, standaard 3085 (Standaard NL). Controleer of je contract de producten en bestemmingen dekt die je aanbiedt.

Ondersteunde bewerkingen

Bewerking Endpoint
Health check en barcode GET /shipment/v1_1/barcode
Vooraangemelde zending met label POST /shipment/v2_2/label?confirm=true
Tracking GET /shipment/v2/status/barcode/{barcode}
Bezorgopties POST /shipment/v1/checkout

Elke call gebruikt de apikey-header. Tracking leest CurrentStatus.Shipment.Status.PhaseCode: fase 2 en 3 worden verzonden, fase 4 wordt bezorgd en elke andere fase houdt de zending in behandeling.

De PostNL Checkout API geeft bezorgopties terug, geen tarieven. Opties zonder positieve prijs worden overgeslagen, dus een optie zonder prijs wordt nooit een gratis verzendofferte en je tarieven in Core blijven leidend.

Binnenlandse pakketten en EU-bestemmingen zonder douanegegevens worden ondersteund. Label-pdf's staan op de private lokale schijf en zijn alleen te downloaden via fulfillment in Admin. Klanten zien de tracking, niet het labelbestand.

Niet ondersteund

  • Een vooraangemeld pakket annuleren. De PostNL API ondersteunt dat niet en het verzoek faalt met een duidelijke foutmelding.
  • Zendingen die een douaneaangifte nodig hebben. PostNL weigert die en Agovena toont een veilige validatiefout.
  • Een mislukt label opnieuw printen vanuit Agovena. Print het opnieuw via Mijn PostNL voor de opgeslagen barcode.
  • Verzendprijzen van PostNL. Checkoutprijzen komen uit je verzendtarieven in Core, tenzij PostNL een geprijsde optie teruggeeft.

Foutafhandeling en eigendom

  • PostNL documenteert geen idempotency-header, dus de extension dwingt één pakket per order af. Het aanmaken van een zending houdt een korte lock per order vast en een gelijktijdige poging faalt voor er een call naar PostNL gaat.
  • De barcode wordt opgeslagen zodra PostNL de zending bevestigt, nog voordat het label wordt gedecodeerd. Een labelfout leidt daardoor bij een nieuwe poging nooit tot een tweede vooraangemeld pakket, en een herhaald verzoek voor een order met een PostNL-barcode geeft de bestaande koppeling terug.
  • Een zending waarvan het label niet kon worden opgeslagen, houdt status label_failed zonder labelbestand.
  • Zonder de tabel postnl_shipments weigert de extension PostNL aan te roepen.
  • HTTP 401 en 403 worden gemeld als configuratieprobleem, 400 als ongeldig adres en 422 als niet-ondersteunde bestemming.
  • Redirects worden nooit gevolgd en geautomatiseerde tests roepen nooit de live API aan.

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"

Laat sandbox aan tot een testzending slaagt. default_product_code wordt gebruikt als een order geen gekozen PostNL-product heeft. Bewaar geheime waarden alleen in de beschermde extension-instellingen, nooit in productbeschrijvingen, URL's, screenshots of gedeelde voorbeelden.

Bekijk het pakket

Bronnen

Doorzoek de documentatie

Zoek handleidingen, commando’s en API-endpoints

Waar ben je naar op zoek?

Documentatie