PostNL icon

PostNL

Interact with PostNL API

Actions17

Overview

This node integrates with the PostNL API to generate shipping labels for one or more shipments. It is designed to facilitate the creation and preannouncement of shipment labels, including detailed shipment, customer, and message information. The node is useful in logistics, e-commerce, and shipping workflows where automated label generation is required to streamline parcel dispatch.

Typical use cases include:

  • Automatically generating shipping labels for orders in an e-commerce platform.
  • Preannouncing shipments to PostNL with all necessary customs and delivery details.
  • Including digital signatures on customs forms via base64 encoded images.
  • Handling multiple shipments in a single request with detailed address, contact, and customs data.

Properties

Name Meaning
Confirm Boolean flag indicating whether to confirm (preannounce) the shipment in the same API call. If true, the shipment is preannounced immediately. If false, a separate confirmation API call is required later.
Customer JSON object containing detailed customer information including address, contact person, customer code and number, email, and name. This defines the sender or customer details for the shipment. Example fields include street, city, country code, company name, department, door code, first and last names, floor, house number, region, and zip code.
Label Signature Optional string containing a GIF image of a signature encoded as a base64 string. Used to automatically sign customs forms. Maximum size is 280x60 mm (1058x226 pixels) and up to 65536 characters. The entire request must not exceed 200KB; larger requests will be rejected with HTTP 404 errors.
Message JSON object describing the message metadata such as MessageID, MessageTimeStamp, and Printertype (e.g., "GraphicFile" or "PDF"). This controls how the label is generated and formatted.
Shipments Required JSON array of shipment objects. Each shipment includes detailed information such as addresses (with types), amounts (payment info), barcode, coding text, collection timestamps, contacts, content description, cost center, order numbers, customs declarations, delivery address and date, dimensions, hazardous material info, product codes, receiver birthdate, references, remarks, return barcodes, and other optional fields. At least one shipment is required. This property allows specifying multiple shipments in one request.

Output

The node outputs JSON data representing the response from the PostNL API after attempting to generate the label(s). This typically includes label URLs, status information, and any relevant metadata returned by the API.

If the API returns binary data (such as PDF or graphic files for labels), it would be included accordingly, but this node primarily handles JSON responses describing the generated labels.

Dependencies

  • Requires an API key credential for authenticating with the PostNL API.
  • The node uses the PostNL environment URL configured in credentials.
  • No additional external dependencies are indicated beyond the PostNL API access.

Troubleshooting

  • Request Size Limit: The total request payload must not exceed 200KB. Including large base64 encoded signatures or many shipments may cause HTTP 404 errors without validation messages. Reduce payload size if this occurs.
  • Invalid JSON: The Customer, Message, and Shipments properties require valid JSON input. Malformed JSON will cause request failures.
  • Confirm Flag Misuse: Setting Confirm to false requires a subsequent confirmation API call. Forgetting this step may result in shipments not being processed.
  • Signature Image Size: The signature image must be within specified pixel dimensions and character length. Oversized images cause silent failures.
  • API Authentication Errors: Ensure the API key credential is correctly configured and has appropriate permissions.
  • Missing Required Fields: Omitting required fields like Customer, Message, or Shipments will cause validation errors from the API.

Links and References

Discussion