Skip to content

PostNL API: How to Integrate Shipping & Tracking into Your Website

In today’s competitive e-commerce landscape, a seamless shipping and tracking experience is vital for any online business. Customers expect transparency and efficiency from the moment they place an order to the moment it arrives at their doorstep. PostNL, a leading postal and logistics service provider, recognizes this need and offers a robust API solution to help businesses integrate shipping and tracking functionalities directly into their websites. This comprehensive guide will delve into the intricacies of the PostNL API, providing a step-by-step walkthrough for understanding and implementing it successfully.

Table of Contents

Understanding the PostNL Shipping API

What is an API?

API stands for Application Programming Interface. In simple terms, it’s a set of rules and specifications that allow different software systems to communicate and interact with each other. Think of it as a messenger that delivers requests and responses between applications.

The Power of the PostNL Shipping API

The PostNL Shipping API is a powerful tool that brings together a range of features that were previously handled by separate APIs, including:

  • Labelling API: Generate shipping labels for domestic and international parcels.
  • Confirming API: Confirm shipments with PostNL, generating labels, and matching them to the correct recipients.
  • Barcode API: Generate unique barcodes for your shipments.
  • Easy Return API: Manage international returns efficiently.

This consolidation into a single “all-in-one” API offers several significant benefits for businesses:

  • Simplified Integration: Developers can now integrate PostNL’s shipping services with fewer lines of code and less complexity.
  • Reduced Overhead: Fewer API calls mean faster processing times and less strain on your server resources.
  • Flexibility: You can integrate the Shipping API into various points in your website’s checkout process, giving you more control over the workflow.
  • Enhanced User Experience: By incorporating the receiver’s email address, you can seamlessly integrate with Mijn PostNL (PostNL’s customer portal), providing customers with a more streamlined and informative tracking experience.

Key Features of the PostNL Shipping API

The PostNL Shipping API is packed with a suite of features designed to simplify and streamline your shipping processes. Let’s explore these key features in more detail:

Label Generation

The API empowers you to generate a variety of shipping labels tailored to different shipment types:

  • Domestic Labels: Create labels for shipments within the Netherlands and Belgium.
  • International Labels: Generate labels for both EU and non-EU international parcels, ensuring compliance with customs requirements.
  • Return Labels: Easily create return labels for your customers, facilitating hassle-free return processes.

Furthermore, the API offers various label formats to cater to your specific printing needs:

  • A6 Label: The standard label size for most shipments.
  • BuspakjeExtra Label: Suitable for smaller parcels that can fit in a mailbox.
  • CN23 Form: A customs declaration form for international shipments.
  • Commercial Invoice: A detailed document outlining the contents and value of an international shipment.
  • COD Card: (Cash On Delivery) Required for domestic COD shipments within the Netherlands.

Barcode Management

The Shipping API offers flexibility in how you manage barcodes:

  • Provide Your Own Barcodes: If you have an existing barcode system, you can seamlessly integrate it with the API.
  • Automatic Barcode Generation: For most shipment types, the API can automatically generate unique barcodes, saving you time and effort.

However, there are a few exceptions to automatic barcode generation:

  • International Mail & Packet Products: Barcodes for these specific products must be provided.
  • Label in the Box (Return Label): The return barcode within a “Label in the Box” shipment must be supplied.
  • Multi-collo Shipments: Each package within a multi-collo shipment needs its unique, pre-generated barcode.
  • Combilabels ‘Parcels Non-EU’ (Product Code 4945): The down partner barcode for these shipments needs to be provided.

Confirmation Options

The shipment confirmation process is a critical step in finalizing a label and ensuring its acceptance by PostNL’s system. The Shipping API offers two options for confirmation:

  • Confirm Within the Same API Call: This streamlines the process by generating and confirming the label in a single request.
  • Confirm Separately: This approach provides greater flexibility, allowing you to generate the label first and then confirm it later, if needed.

Multi-package Shipments (Multi-collo)

The API seamlessly supports the creation of multi-package shipments, known as multi-collo. Here’s how it works:

  • Individual Labels: Each package within a multi-collo shipment receives its unique label.
  • Grouped Shipments: The API allows you to link these individual packages into a single shipment by using the “Group Type” parameter.
  • Supported Destinations: Multi-collo shipments are currently available for domestic deliveries within the Netherlands and Belgium, as well as shipments between the two countries.

Handling Multiple Shipments

To enhance efficiency, the Shipping API can process up to four shipments within a single request. This batch processing capability significantly streamlines your workflow, especially for businesses that handle a high volume of orders.

Merged Label Printing

This feature simplifies the printing process by generating a single PDF document containing multiple shipping labels. It’s a time-saving solution that makes it easy to print multiple labels on a single sheet of paper.

The API offers various Merge printer types, each specifying the label placement on the sheet:

  • MergeA: Starts printing labels in the top-left corner.
  • MergeB: Begins printing labels in the top-right corner.
  • MergeC: Starts printing labels in the bottom-left corner.
  • MergeD: Begins printing labels in the bottom-right corner.

Printer Type Options

The Shipping API is compatible with a wide range of printers, ensuring you can use the printing setup that best suits your needs. Supported options include:

  • Graphic File Formats: Generate labels in popular graphic file formats such as GIF, JPG, and PDF, making them compatible with standard printers.
  • Zebra ZPL II: Direct label printing to Zebra printers using the Zebra Programming Language (ZPL II).
  • Resolution Options: Choose from various print resolutions (200, 300, and 600 dpi) to ensure optimal print quality for barcode readability.

Address Validation

Accuracy is paramount when it comes to shipping addresses. The PostNL Shipping API automatically validates and corrects receiver addresses using PostNL’s internal address database. This minimizes the risk of delivery errors and ensures your parcels reach their intended destinations without delays.

Error Handling

Integration errors are inevitable in software development. The PostNL API incorporates robust error handling mechanisms to help you identify and resolve issues efficiently. It provides detailed error messages that offer insights into the nature of the problem, enabling you to take corrective action and prevent shipment delays.

Step-by-Step Guide to Integrating the PostNL API

Now that you have a good understanding of the key features and benefits of the PostNL Shipping API, let’s walk through the steps of integrating it into your website.

1. Acquiring Your API Key

  • Visit the PostNL Developer Portal: Navigate to the PostNL Developer Portal, where you can find comprehensive documentation and resources.
  • Register for an Account: If you don’t have an existing account, create one to access the API.
  • Request an API Key: After registering, you can apply for an API key that will grant you access to the Shipping API.

2. Setting Up Your Development Environment

Before you start coding, you need to set up a suitable development environment. This usually involves:

  • Choosing an IDE: Select a code editor or IDE that you’re comfortable with. Some popular choices include Visual Studio Code, Sublime Text, or Atom.
  • Installing a REST Client: Tools like Postman or Insomnia allow you to easily test API requests and view responses during development.
  • Choosing a Programming Language: The PostNL API supports multiple programming languages, so you can choose one that aligns with your website’s back-end technology (e.g., PHP, Python, Node.js, Ruby).

3. Making Your First API Call

Let’s start with a simple example of making an API call to generate a shipping label using the postnl api. The following is a conceptual example in Python; the specific code will vary depending on your chosen programming language:

“`python
import requests

api_key = “YOUR_API_KEY”

url = “https://api.postnl.nl/v1/shipment”

shipment_data = {
“Customer”: {
“Address”: {
“AddressType”: “02”,
“City”: “The Hague”,
“CountryCode”: “NL”,
“HouseNr”: “123”,
“Street”: “Example Street”,
“Zipcode”: “2500AA”
},
“ContactType”: “02”,
“Email”: “sender@example.com”
},
“Shipments”: [
{
“Addresses”: [
{
“AddressType”: “01”,
“City”: “Amsterdam”,
“CountryCode”: “NL”,
“HouseNr”: “456”,
“Street”: “Destination Street”,
“Zipcode”: “1000AB”
}
],
“Barcode”: “YOUR_BARCODE”,
“ProductCodeDelivery”: “3085”,
“Dimension”: {
“Weight”: 1000
},
“ContactType”: “01”,
“Email”: “recipient@example.com”
}
]
}

headers = {
“apikey”: api_key,
“Content-Type”: “application/json”
}

response = requests.post(url, headers=headers, json=shipment_data)

if response.status_code == 200:
# Label generated successfully
label_data = response.json()
# Process label data to print or display
else:
# Handle API error
print(f”Error: {response.status_code} – {response.text}”)
“`

Explanation:
* Import necessary libraries: Import the requests library to make HTTP requests.
* Define your API key: Replace YOUR_API_KEY with your actual PostNL API key.
* Set the API endpoint URL: Specify the correct URL for the Shipping API.
* Create shipment data: Construct a JSON payload containing the necessary shipment details, including sender and recipient addresses, barcode, product code, weight, and contact information.
* Set headers: Include your API key in the request headers for authentication.
* Make the API call: Use the requests.post() method to send the shipment data to the API endpoint.
* Handle the response: Check the HTTP status code to verify the request’s success. If successful, extract the label data from the response. If there’s an error, handle it appropriately.

4. Integrating into Your Website’s Workflow

The specific integration process will vary depending on your website’s structure and functionality. However, here are some general steps:

  • Collect Shipment Information: During the checkout process, gather all the necessary shipment details from your customers (e.g., recipient address, product selection, delivery options). You can even utilize a postnl postcode api to streamline the address input process for your customers.
  • Trigger API Calls: At the appropriate point in your workflow (e.g., after order confirmation), initiate the API call to generate and confirm the shipping label using the post nl api.
  • Handle Label Data: Once the API call is successful, process the label data. This might involve:
    • Displaying the label on the screen for the customer to print.
    • Automatically sending the label to the customer’s email.
    • Storing the label data in your database for future reference.
  • Use Webhooks for Real-Time Updates: PostNL offers webhooks that provide real-time updates on shipment status changes (e.g., picked up, in transit, delivered). By integrating with webhooks, you can keep your customers informed about their order’s progress without having to poll the API repeatedly.

5. Testing and Debugging

Thorough testing is essential to ensure your integration is working correctly. Consider the following:

  • Test Different Scenarios: Test various scenarios, including domestic and international shipments, multi-package shipments, and different delivery options.
  • Use Test Data: Initially, use test data and the PostNL Sandbox environment to avoid generating real labels and affecting your production systems.
  • Implement Error Handling: Include robust error handling in your code to gracefully manage any API errors and provide helpful feedback to your customers.
  • Monitor Logs: Review your server logs and API response data to identify and address any issues that arise during testing.

Best Practices and Guidelines

PostNL provides specific guidelines to ensure your API integration is successful and conforms to their standards. Let’s highlight some of these best practices:

Request Size Limits

The Shipping API has a maximum request size limit of 200KB. It’s important to keep this in mind when sending large requests, especially if you’re generating multiple labels or including signature images. If your request exceeds this limit, you’ll likely encounter a HTTP 404 error. Consider these approaches to manage larger requests:

  • Split Large Shipments: If you have more than four shipments in a single order, divide them into multiple API calls.
  • Optimize Data: Carefully review your request payload and remove any unnecessary data fields to reduce the overall size.

Print Quality Requirements

Ensure you use high-quality printers to generate clear and readable shipping labels. Poor print quality, particularly for barcodes, can cause delays in sorting at PostNL facilities and hinder efficient delivery.

Understanding Address Types

PostNL uses specific address type codes to distinguish between different address roles in the shipping process. These codes include:

  • 01: Receiver: The address of the person or business receiving the shipment.
  • 02: Sender: The address of the person or business sending the shipment.
  • 03: Alternative Sender Address: An optional alternative address for the sender.
  • 04: Collection Address: The address where the shipment will be picked up.
  • 08: Return Address: The address to which the shipment should be returned.
  • 09: Delivery Address (Pick up at PostNL location): The address of the PostNL location where the recipient will pick up the shipment.

Shipment Type Codes

For international shipments, it’s essential to correctly classify the shipment type to ensure compliance with customs regulations. Here are some common shipment type codes:

  • Gift: A non-commercial shipment sent as a gift.
  • Documents: A shipment containing only documents.
  • Commercial Goods: A shipment containing goods intended for sale or resale.
  • Commercial Sample: A shipment containing samples of commercial goods.
  • Returned Goods: A shipment containing goods being returned to the sender.

Contact Type Requirements

For certain PostNL products and services (e.g., evening or same-day delivery, pick up at PostNL locations), providing contact information is mandatory. The API allows you to include:

  • Email: The email address of either the sender or receiver.
  • SMSNr: The SMS phone number of either the sender or receiver.
  • TelNr: The phone number of either the sender or receiver.

It’s highly recommended to include the recipient’s email address as this improves their experience with Mijn PostNL, allowing them to easily track their shipment and receive updates.

FAQ Section

Let’s address some common questions that might arise when working with the PostNL Shipping API:

Q: What if I need to send more than four shipments in one request?

A: Due to the request size limit, you’ll need to split larger orders into multiple API calls. You can also implement batch processing techniques to handle groups of four shipments at a time.

Q: Can I use the Shipping API for both domestic and international shipments?

A: Absolutely! The API supports a wide range of destinations, including domestic shipments within the Netherlands and Belgium, as well as international shipments to both EU and non-EU countries.

Q: What if my label size requirement is not listed in the available options?

A: For unique label size needs, it’s best to reach out to PostNL’s developer support team. They can provide guidance on how to handle non-standard label dimensions.

Q: How can I get support if I encounter issues with my API integration?

A: PostNL offers dedicated developer support. You can find their contact information on the PostNL Developer Portal, along with access to comprehensive documentation, troubleshooting guides, and other valuable resources.

Tags: