Skip to content
agovena.
agovena.
Get started
Community

Provider guides

PostNL: configuration and operations

Create pre-announced PostNL shipments with barcodes and labels, follow tracking and use priced PostNL delivery options when available.

On this page

Status and workflow

The PostNL extension is a carrier for the shipping features in Agovena Core. It creates a pre-announced PostNL shipment with barcode and label, reads tracking and can add priced PostNL delivery options to checkout. It is an Extension, not a Module: orders, products and addresses keep their generic Core fields, and PostNL barcodes, labels and product codes stay inside this extension.

Production-ready for the documented scope. Every operation under Supported operations is implemented against the PostNL REST APIs for barcodes, labels, shipment status and checkout and verified with automated tests that replace the provider with faked HTTP responses, without network calls. Live acceptance on your own PostNL account remains an operator responsibility: create one shipment, download its label and follow its tracking with your own PostNL contract before you ship customer orders. Operations under Not supported are not advertised.

Requirements

  • Agovena Core ^0.0.1. Physical commerce and shipping are part of Core, so no additional Module is required.
  • A PostNL API contract with an API key, customer code and customer number.
  • Complete shipping addresses. The extension parses the street and house number from the first address line.

Set up the package

  1. Open Admin > Extensions and enable PostNL.
  2. Save the API key, customer code and customer number. The API key is encrypted and never redisplayed.
  3. Optionally set collection_location. Keep sandbox enabled for tests (https://api-sandbox.postnl.nl) and switch it off with live credentials (https://api.postnl.nl).
  4. Keep your Core shipping methods and rates configured. Checkout keeps using them for prices.
  5. Fulfillment uses the selected product code or default_product_code, which defaults to 3085 (Standard NL). Confirm that your contract covers the products and destinations you offer.

Supported operations

Operation Endpoint
Health check and barcode GET /shipment/v1_1/barcode
Pre-announced shipment with label POST /shipment/v2_2/label?confirm=true
Tracking GET /shipment/v2/status/barcode/{barcode}
Delivery options POST /shipment/v1/checkout

Every call uses the apikey header. Tracking reads CurrentStatus.Shipment.Status.PhaseCode: phases 2 and 3 become shipped, phase 4 becomes delivered and every other phase keeps the shipment in processing.

The PostNL Checkout API returns delivery options, not tariffs. Options without a positive price are skipped, so an unpriced option never becomes a free shipping quote and your Core rates stay in charge.

Domestic parcels and EU destinations without customs data are supported. Label PDFs are stored on the private local disk and can only be downloaded from Admin fulfillment. Customers see tracking, not the label file.

Not supported

  • Cancelling a pre-announced parcel. The PostNL API does not support it and the request fails with a clear error.
  • Shipments that need customs declarations. PostNL rejects them and Agovena shows a safe validation error.
  • Reprinting a failed label from Agovena. Reprint it from Mijn PostNL for the stored barcode.
  • Shipping prices from PostNL. Checkout prices come from your Core shipping rates unless PostNL returns a priced option.

Failure handling and ownership

  • PostNL documents no idempotency header, so the extension enforces one parcel per order. Shipment creation holds a short lock per order and a concurrent attempt fails before any provider call.
  • The barcode is stored as soon as PostNL confirms the shipment and before the label is decoded. A label failure therefore never leads to a second pre-announced parcel on retry, and a repeated request for an order with a PostNL barcode returns the existing mapping.
  • A shipment whose label could not be stored keeps status label_failed without a label file.
  • Without the postnl_shipments table the extension refuses to call PostNL.
  • HTTP 401 and 403 are reported as a configuration problem, 400 as an invalid address and 422 as an unsupported destination.
  • Redirects are never followed and automated tests never call the live API.

Configuration contract

Field Type Required Secret Default
api_key string Yes Yes Empty
customer_code string Yes No Empty
customer_number string Yes No Empty
collection_location string No No Empty
sandbox boolean No No true
default_product_code string No No "3085"

Keep sandbox enabled until a test shipment succeeds. default_product_code is used when an order has no selected PostNL product. Store secret values only in the protected extension settings, never in product descriptions, URLs, screenshots or shared examples.

View the package entry

Sources

Search documentation

Search guides, commands and API endpoints

What are you looking for?

Documentation