ADR-0006 — Shipment Provider: PostNL¶
| Status | Accepted |
| Date | 2025 |
| Deciders | Flooris development team / Zwerfkei management |
Context¶
The Zwerfkei platform requires a carrier integration for generating shipment labels and track & trace codes. The carrier must support domestic (Netherlands) and international parcel delivery and provide an API for programmatic label creation.
Decision¶
PostNL is adopted as the primary shipment carrier and label provider for the Zwerfkei platform.
Rationale¶
- PostNL is the existing carrier used within the Zwerfkei business operations.
- PostNL provides a well-documented REST API for shipment creation, label generation and track & trace.
- PostNL offers a broad range of shipment products (standard, signature required, evening delivery, etc.) that cover Zwerfkei's fulfilment requirements.
- A PostNL business account and API access are already in place.
Supported Shipment Options¶
| Option | PostNL Product | Product Code | Signature | Notes |
|---|---|---|---|---|
| Standard | PostNL Standaard | 3085 |
No | Standard home delivery, daytime |
| Signature required | Handtekening voor ontvangst | 3089 |
Yes | Proof of receipt required |
| Evening delivery | Avondlevering | 3096 |
No | Delivery between 18:00–22:30 |
Integration Pattern¶
- When an order is ready to ship, a back office employee initiates shipment creation from the order detail page.
- The Zwerfkei Backend sends a shipment creation request to the PostNL API with the delivery address and selected product code.
- PostNL returns a track & trace code and a shipment label (PDF).
- The track & trace code and label reference are stored in
OrderFulfilment. - The track & trace code is made visible to the customer in their order overview.
Consequences¶
- The Zwerfkei Backend must implement a PostNL API client for shipment creation.
- A valid delivery address must exist on the order before a shipment can be created.
- Label PDF storage must be handled (stored locally or retrieved on-demand from PostNL).
- Future extensions (e.g. international shipments, pickup points) require additional PostNL product codes and rule configuration.