General Information

Here you will find general information you need to get started using PostNord APIs

- Quick Start Guide
- PostNord API Official FQDN
- API Key
- HTTP Headers
- HTTP Caching
- Authentication
- Swagger API Specification
- Client
- Authorization Request
- OAuth - Client credential flow
- Request to secured API
- How we manage API versioning

Quick Start Guide

PostNord provides a range of API’s to facilitate integration with your back end systems. Integrate PostNord web services directly into your website, customs applications or e-commerce platform.

Our APIs are easy to use and customizable to meet your shipping needs.

Read the developer API documentation
For development
- Sign up for a Sandbox
- The test API key is provided to you in the registration email
- The test URL Host is: atapi2.postnord.com
For production
- Sign up for Free/Premium plan
- The production API key is provided to you in the registration email
- The production URL Host is: api2.postnord.com

For help, contact api.support@postnord.com

PostNord API Official FQDN | IP addresses

PostNord has removed the fixed IPs on the API gateway: api2.postnord.com & atapi2.postnord.com

Please configure Firewall rules using an alias or FQDN (e.g. api2.postnord.com)

Why: With fixed IPs PostNord unable to scale the API gateway from a vendor perspective.

API Key

All of PostNord APIs requires the API key to be sent in the request as a query parameter apikey

The API key is used to identify you as a consumer of APIs.

Example

https:///{URL-host}/test?apikey=91f146137449a4068b3523a80xxx

HTTP Headers

Allows the client and the server to pass additional information with the request or the response.

The table lists recommended HTTP headers, to be set by the client.

Header	Example	Description
Content-Type:	application/json	The MIME type of the request body
X-External-Request-ID:	904344e8cde5-f058ebd6-02f7f942e	Unique transaction ID, used for transactional correlation between the client and PostNord (troubleshooting)
Authorization:	Bearer 1ijDG7gOOZ9Cj6VeH9tq	Authentication credentials, which may contain the Access-token from the Oauth2 login

HTTP Caching

It is not recommended to cache data on the client side, this guarantees that the client always retrieves the latest data.

Note: It is ok to cache data, if the API explicitly allows that.

Authentication

PostNord OAuth2 implementation supports the standard client credential grant type.

Each secured API has a set of scopes that defines the permissions to access their resources
- They are listed in the API swagger definition
The client must be registered, to be able to perform an OAuth2 login
- A successful login creates an Access token to the client with the assigned scopes.
- A client can choose to request all scopes or a subset of those defined
The Access token is used in the calls to PostNord secured APIs

Swagger API specification

They are published under the API docs section in the developer portal.

The secured APIs has a securityDefinitions in their swagger defining the scopes
Reference: Swagger specification - OAuth


          securityDefinitions": {

          "OAuth2": {

          "type": "oauth2",

          "tokenUrl": "https://pp-gate.ess.postnord.com/mga/sps/oauth/oauth20/token",

          "flow": "application",

          "scopes": {

          "https://api.postnord.com/scopes/shipment/declare/vat/write": "Modify the
            resource"

          }}}

APIs that require secure access (IAM)

APIs that require IAM are marked with (IAM required) in the title. For example:

Client (application)

This represents your application that want to use the protected APIs.

You need to register the client
Send the following information to api.support@postnord.com with the subject: IAM

Client Data	Description
API Key	The production key from the sign up
Client Application Name	The name of the client.
Redirect_URI*	After successful authorization, the authorization server will redirect the user back to the application with either an authorization code or access token in the URL.
Scopes	Provide a list of the scopes that the client needs access to, retrieved by looking into the APIs swagger specifications

3. PostNord will supply you the following information to be used in the OAuth2 authorizations request.

Client Data	Description
client_id	The client_id is a public identifier for the client
client_secret	The client_secret is a secret known only to the client and authorization server

Authorization request

How to obtain an access-token for the client.

Test Authorization server URL: https://pp-gate.ess.postnord.com/mga/sps/oauth/oauth20/token
Production Authorization server URL: https://gate.ess.postnord.com/mga/sps/oauth/oauth20/token

OAuth - Client credential flow

Request an access-token without user interact.


          curl -X POST \

          https://pp-gate.ess.postnord.com/mga/sps/oauth/oauth20/token \

          -H 'Accept: application/json' \

          -H 'Content-Type: application/x-www-form-urlencoded' \

          -d 'grant_type=client_credentials&client_id=xyzxyz&client_secret=xyzxyz'

Use HTTPS POST to the authorization server

The Content-Type Header contains

application/x-www-form-urlencoded

The Body contains

grant_type: client_credentials
client_id: the received PostNord client_id
client_secret: the received PostNord client_secret for the client_id

Response message


          HTTP/1.1 200 OK

          Content-Type: application/json

          Cache-Control: no-store

          Pragma: no-cache

          {

          "access_token": "o5Ptk3GUEgNV3izvuDl5",

          "acr": "client_credentials",

          "token_type": "bearer",

          "expires_in": 3599

          }

The HTTP Headers contains

Content-Type: application/json Returned content type to the client
Cache-Control: no-store Ensures that the clients doesn't cache the request
Pragma: no-cache Ensures that the clients doesn't cache the request

The Body contains

access_token: The access token string as issued by the authorization server
acr: Authentication context reference
token_type: The type of token this is, typically just the string “bearer”
expires_in: The duration of seconds the access token is granted for

Request to secured API

The access token value from the Authorization response message, must be used in the request to the secured API.
Must be sent in the HTTP Header "Authorization:" with the token_type Bearer

Example

The Authorization response has a value of "access_token": "o5Ptk3GUEgNV3izvuDl5"
Secured API request "Authorization: Bearer o5Ptk3GUEgNV3izvuDl5"

How we manage API versioning

Part of Postnord's booking clients responsibility is to keep in mind how we manage our API versioning.

vN- versioning

Defines the major version of the API e.g. /v1 , the API must be able to evolve overtime to minimize the need for new versions. The following changes can be introduced to the API that do not constitute a breaking change:

A new resource or API endpoint
A new optional parameter
A change to a non-public API endpoint
A new optional key in the JSON POST body
A new key returned in the JSON response body

Conversely, a breaking change included anything that could break the integration such as:

A new required parameter
A new required key in POST bodies
Removal of an existing endpoint
Removal of an existing endpoint request method
A materially different internal behavior of an API call — such as a change to the default behavior.