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 allows users to create and optionally confirm shipments in a single API call, producing labels that can be printed or saved in various formats such as PDF or graphic files.

Common scenarios where this node is beneficial include:

  • Automating label generation for e-commerce orders.
  • Batch processing multiple shipments with detailed shipment and customs information.
  • Integrating shipping workflows into broader automation pipelines.

Practical example:
A logistics company can use this node to automatically generate shipping labels for all daily orders, including customs declarations for international shipments, and receive the labels in PDF format ready for printing.

Properties

Name Meaning
Confirm Boolean flag to determine if the shipment should be confirmed (preannounced) in the same API call. If true, the shipment is preannounced immediately; if false, a separate confirmation request is required later.
Customer JSON object containing customer details including address, contact person, customer code and number, and email. This defines the sender or customer information related to the shipment. Example fields include AddressType, City, CompanyName, Countrycode, Department, Doorcode, FirstName, Floor, HouseNr, Name, Region, Street, Zipcode, CollectionLocation, ContactPerson, CustomerCode, CustomerNumber, and Email.
Label Signature Optional base64 encoded GIF image of a signature to automatically sign customs forms. Maximum size is 280x60 mm (1058x226 pixels) and up to 65536 characters. The entire request must not exceed 200KB to avoid HTTP 404 errors.
Message JSON object containing message metadata such as MessageID, MessageTimeStamp, and Printertype. Printertype can be "GraphicFile" or "PDF", indicating the desired output format of the label.
Shipments Required JSON array of one or more shipment objects. Each shipment includes detailed information such as addresses, amounts, barcodes, collection timestamps, contacts, content description, cost center, customer order number, customs data, delivery address and date, dimensions, hazardous material info, product codes, references, remarks, return barcode/reference, and other optional fields. At least one shipment is required. This property encapsulates all necessary data to generate accurate shipping labels.

Output

The node outputs JSON data representing the response from the PostNL API after generating the shipment label(s). This typically includes label data in the requested format (e.g., PDF or graphic file), shipment confirmation status, and any relevant metadata returned by the API.

If binary data is included (such as the actual label file), it will represent the printable shipping label in the specified format.

Dependencies

  • Requires an API key credential for authenticating with the PostNL API.
  • The node expects the base URL for the API environment to be configured in the credentials.
  • No additional external dependencies are indicated beyond the PostNL API service.

Troubleshooting

  • Request Size Limit: Including a large base64 encoded signature or very large shipment data may cause the request to exceed the 200KB limit, resulting in HTTP 404 errors. To resolve, reduce the size of the signature image or split shipments into smaller batches.
  • Missing Required Fields: Omitting required properties like Customer, Message, or Shipments will likely cause validation errors from the API. Ensure all required JSON structures are correctly formatted and included.
  • Confirm Flag Misuse: Setting Confirm to false requires a subsequent confirmation API call. Forgetting this step may result in shipments not being processed as expected.
  • Invalid JSON Format: Since several properties require JSON input, invalid JSON syntax will cause errors. Validate JSON inputs before execution.
  • API Authentication Errors: Ensure the API key credential is valid and the environment URL is correctly set to avoid authentication failures.

Links and References

Discussion