General Information
Here you will find general information you need to get started using PostNord APIs
Quick Start Guide
PostNord provides a range of APIs 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.