Authentication

The PostNL API requires an API key to authenticate. You can request one via MijnPostNL.

If you do not already have a PostNL account, be sure to check out this page: https://developer.postnl.nl/request-api-key/

Note

The API key is automatically attached to the Firstred\PostNL\Entity\SOAP\UsernameToken object (SOAP) or apikey HTTP header (REST). You do not have to manually add the API key with every request.

Passing all credentials

Besides having to provide an API key, you will have to pass information about your business. These credentials will have to be passed with a Firstred\PostNL\Entity\Customer object when creating a new Firstred\PostNL\PostNL instance.

Note

The Firstred\PostNL\PostNL class is the main class of this library. It handles all functionality you will need from a developer’s perspective. After instantiating a new Firstred\PostNL\PostNL object you will have everything you need to communicate with the PostNL API. Everything else (caching, HTTP Clients, logging, etc.) is optional.

In order to get started with the API, the following credentials are important:

Required credentials

API key: Required: True

The API key

Customer code: Required: True

The customer code is a code that usually consists of 4 letters and appears in domestic 3S-codes.

Customer number: Required: True

The customer number is a number that usually consists of 8 digits.

Address

A filled Firstred\PostNL\Entity\Address object with at least the following information:

AddressType: Required: True

Default: 02

The address type should be 02, which means the address belongs to the sender.

City: Required: True

City

CompanyName: Required: True

The company name

HouseNr: Required: True

The house number

Street: Required: True

Street name

Zipcode: Required: True

The postcode. Be aware that the API might sometimes refer to a postcode as postcode, postal code or zipcode.

Collection location

Required: True

Default: 123456

I must admit that to this day I still do not have a single clue what this value means. It could refer to your local drop-off location (if you use one). If your PostNL account manager can provide you with a collection location number please use that one.

I usually fill out 123456 and it seems to work just fine.

Globalpack barcode type

Required: False

The barcode type to use for international shipments. This field is optional if you do not ship outside the EU.

This field usually consists of 2 letters.

Globalpack customer code

Required: False

The barcode type to use for international shipments. This field is optional if you do not ship outside the EU.

This field usually consists of 4 digits.

When you have all the required information, you are ready to configure the library. It can be configured as follows:

Note

Example configuration. All the credential come together in the Firstred\PostNL\Entity\Customer and main Firstred\PostNL\PostNL class.

<?php

use Firstred\PostNL\Entity\Address;
use Firstred\PostNL\Entity\Customer;

$apiKey = 'qjsdjufhjasudhfaSDFasdifh324';
$customer = (new Customer())
    ->setCollectionLocation('123456')
    ->setCustomerCode('DEVC')
    ->setCustomerNumber('11223344')
    ->setContactPerson('Test')
    ->setAddress((new Address())
        ->setAddressType('02')
        ->setCity('Hoofddorp')
        ->setCompanyName('PostNL')
        ->setCountrycode('NL')
        ->setHouseNr('42')
        ->setStreet('Siriusdreef')
        ->setZipcode('2132WT')
    )
    ->setGlobalPackBarcodeType('AB')
    ->setGlobalPackCustomerCode('1234')
;

$postnl = new PostNL(
    $customer,        // The filled Customer object
    $apiKey,          // The API key
    false,            // Sandbox = false, meaning we are now using the live environment
    PostNL::MODE_REST // We are going to use the REST API (default)
);

You might have noticed that several different ways have been used to instantiate an object. More information about this can be found in the Object instantiation section.

The PostNL client constructor accepts a few options:

customer

Required: True

The Firstred\PostNL\Entity\Customer object that is used to configure the client and let PostNL know who is requesting the data.

<?php

use Firstred\PostNL\Entity\Address;
use Firstred\PostNL\Entity\Customer;

// Create a new customer
$client = (new Customer())
    ->setCollectionLocation('123456')              // Your collection location
    ->setCustomerCode('DEVC')                      // Your Customer Code
    ->setCustomerNumber('11223344')                // Your Customer Number
    ->setGlobalPackBarcodeType('CX')               // Add your GlobalPack information if you nee
    ->setGlobalPackCustomerCode('1234')            // to create international shipment labels
    ->setContactPerson('Sander')
    ->setAddress((new Address())
        ->setAddressType('02')                     // This address will be shown on the label
        ->setCity('Hoofddorp')
        ->setCompanyName('PostNL')
        ->setCountrycode('NL')
        ->setHouseNr('42')
        ->setStreet('Siriusdreef')
        ->setZipcode('2132WT')
    )
    ->setEmail('test@voorbeeld.nl')
    ->setName('Michael')
;

apiKey

The API key to use. Note that if you want to switch from the legacy API to the new SOAP and REST API you will have to request a new key.

If you want to connect to the legacy API, you should pass a Firstred\PostNL\Entity\SOAP\UsernameToken with your username and token set:

$usernameToken = new UsernameToken('username', 'token');

You can request an API key for the sandbox environment on this page: https://developer.postnl.nl/content/request-api-key For a live key you should contact your PostNL account manager.

sandbox: Required: True

Indicate whether you’d like to connect to the sandbox environment. When false the library uses the live endpoints.

mode

Required: True

This library provides three ways to connect to the API:

Firstred\PostNL\PostNL::MODE_REST: REST mode
Firstred\PostNL\PostNL::MODE_SOAP: SOAP mode (deprecated since v1.4.0)
Firstred\PostNL\PostNL::MODE_LEGACY: Legacy mode – This is the legacy SOAP API, which is now disabled and replaced with SOAP mode (deprecated since v1.4.0).

Authorization

You may not be authorized to access all services. Contact your PostNL account manager to find out what’s available to you.