InPost International API Documentation (0.2)

 

Getting started with InPost Rest API 

InPost APIs use REST, authenticate with OAuth 2.0 access tokens, and return HTTP response codes and responses encoded in JSON. You can test integrations with a sandbox environment. 

 


Authorization 

 

Address of production environment: https://api.inpost-group.com

Test environment address: https://sandbox-api.inpost-group.com

OAuth2 with authorization code flow and PKCE - Preferred method of authorisation

Overview

Our API is compliant with oAuth 2.1 (OAuth 2.1 ) so we require using PKCE in this authorization method. The Authorization Code Flow with Proof Key for Code Exchange (PKCE) is an extension that enhances the security of the authorization code flow. PKCE is designed to protect authorization codes from interception attacks.

 

Step 1: Generate Code Verifier and Code Challenge

Before initiating the authorization request, generate a code verifier and code challenge.

  • Code Verifier: A high-entropy cryptographic random string.

  • Code Challenge: A base64-url-encoded SHA256 hash of the code verifier.

import base64 import hashlib import os def generate_code_verifier(): return base64.urlsafe_b64encode(os.urandom(32)).rstrip(b'=').decode('utf-8') def generate_code_challenge(verifier): challenge = hashlib.sha256(verifier.encode('utf-8')).digest() return base64.urlsafe_b64encode(challenge).rstrip(b'=').decode('utf-8') code_verifier = generate_code_verifier() code_challenge = generate_code_challenge(code_verifier) print("Code Verifier:", code_verifier) print("Code Challenge:", code_challenge)

 

Step 2: Authorization Request

The next step is redirect user to our login page with following parameters.

If you want to receive a long lived refresh token (offline token) you have to add offline_access in scopes parameter”

https://sandbox-login.inpost-group.com/realms/external/protocol/openid-connect/auth ?client_id=myclient &redirect_uri=https://myapp.com/callback &response_type=code &scope=api:shipments:write api:tracking:read api:one-time-pickups:write api:points:read &code_challenge=abc123def456ghi789 &code_challenge_method=S256

 

Step 3: Login in and accept passing data to external system

 

image-20240621-102549.png

 

image-20240621-102904.png

 

Step 4: Exchange authorization code to receive refresh and access token

 

On redirect uri provided in previous step we receive one-time code that we need to exchange to obtain refresh and access token.

If you want to receive a long lived refresh token (offline token) you have to add offline_access in scopes parameter

curl --location 'https://sandbox-api.inpost-group.com/auth/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'client_id=example' \ --data-urlencode 'client_secret=123456789xxxx' \ --data-urlencode 'grant_type=authorization_code' \ --data-urlencode 'redirect_uri=https://myapp.com/callback' \ --data-urlencode 'code=b9e50bd4-5ab0-4701-8c73-69466aa7ba21.......' \ --data-urlencode 'code_verifier=WIFPE6ylf8eGdggfT2r9zdXL8duZFrUNo0tbbHxolI4'

If offline_access scope was provided please keep refresh_token in safe place, because it does not require logging in to the system again by user

Step 5: Access token expiration

If your access_token will expire, your system need to exchange refresh_token to get a new access token.


Example requests with bearer token


OAuth2 with client_credentials flow - Alternative method of authorisation

 

The following examples show you how to get your access token using cURL. This flow has the limitation that we cannot use it where one app is working on behalf of multiple users. It is strictly correlated with one account and we recommend it for simple integrations.

InPost REST APIs use OAuth 2.0 access tokens to authenticate requests. Your access token authorizes you to use the InPost REST API server. 

To call a REST API in your integration, you'll need to exchange your client ID and client secret for an access token.  

You can make the API call in any programming language. The following examples show you how to get your access token using cURL.  

 

Step result 

InPost API returns an access token and the number of seconds the access token is valid. When you make calls to a REST API, include the access token in the authorization header: -H Authorization: Bearer ACCESS-TOKEN. When your access token expires, call /auth/token again to request a new access token.

 



HTTP Status codes 

 

Each request to the API returns an HTTP status indicating the result of the processing. The following list contains the most commonly used statuses: 

200 OK Returned when the GET and PUT methods succeed. 

201 Created Confirms the creation of a document using the POST method. 

202 Accepted Indicates that the request has been accepted by the server, but its processing has not yet been completed (applies to asynchronous processing). 

204 No Content Returned when an operation succeeds, but the request does not return any data (e.g., DELETE method). 

304 Not Modified Indicates no changes in the HTTP request - no redirection. 

400 Bad Request Incorrect JSON data sent. 

401 Unauthorized The user is not authenticated - they should log in to Allegro and then try to make the request again. 

403 Forbidden The user is authenticated but does not have rights to the requested resource. 

404 Not Found The requested resource does not exist in the API. 

406 Not Acceptable An unsupported data type was passed in the Accept header. 

415 Unsupported Media Type An unsupported data type was passed in the Accept header. 

422 Unprocessable Entity Incorrect field values were sent, e.g., object validation returned an error, or some fields do not meet the criteria imposed on them by the resource. 

429 Too Many Requests The client exceeded the request limit. 

503 Service Unavailable Connection to the service is not possible. 


 

Versioning 

 

The InPost REST API is versioned. The API version name is based on the date when the API version was released. For example, the API version 2024-06-01 was released on 01 June 2024. 

Any breaking changes will be released in a new API version. Breaking changes are changes that can potentially break an integration. Breaking changes include: 

 

  • removing an entire operation 

  • removing or renaming a parameter 

  • removing or renaming a response field 

  • adding a new required parameter 

  • making a previously optional parameter required 

  • changing the type of a parameter or response field 

  • removing enum values 

  • adding a new validation rule to an existing parameter 

  • changing authentication or authorization requirements 

 

Any additive (non-breaking) changes will be available in all supported API versions. Additive changes are changes that should not break an integration. Additive changes include: 

  • adding an operation 

  • adding an optional parameter 

  • adding an optional request header 

  • adding a response field 

  • adding a response header 

  • adding enum values 

 

When a new REST API version is released, the previous API version will be supported for at least 12 months following the release of the new API version. 

 

Specifying an API version 

You should use the X-InPost-Api-Version header to specify an API version. For example: 

 

Requests without the X-InPost-Api-Version header will default to use the current version, which is now 2024-06-01. 

If you specify an API version that is no longer supported, you will receive a 400 error. 


 

Request IDs 

Each API request has an associated request identifier. You can find this value in the response headers, under X-Request-Id.  

 

You can provide own identifier and place it into request header and you receive it in response headers as well. We recommend using a strongly random character generator such as UUID.  

 

To expedite the resolution process, provide the request identifier when you contact us about a specific request.  


 

Shipping Methods

 

Name

Description

Name

Description

APM - Point (Locker)

Locker - Automated Parcel Machine (Paczkomat®)

PUDO - Point (PUDO)

Pick-up Drop-off Point - a store, kiosk, or other establishment acting on behalf of the InPost Group as a service point

HUB - Point (Hub)

InPost Group local warehouse, delivery branch, or sorting center

Address

Courier pick-up


 

Avaliable directions

 

 

 

from: PL - Poland

to:

 

Point (Locker)

Point (PUDO)

Point (Hub)

Address

BE - Belgium

Point (Locker)

Yes

Yes

Yes

Yes

Point (PUDO)

Yes

Yes

Yes

Yes

ES - Spain (Espania)

Point (Locker)

Yes

Yes

Yes

Yes

Point (PUDO)

Yes

Yes

Yes

Yes

FR - France

Point (Locker)

Yes

Yes

Yes

Yes

Point (PUDO)

Yes

Yes

Yes

Yes

IT - Italy

Point (Locker)

Yes

Yes

Yes

Yes

Point (PUDO)

Yes

Yes

Yes

Yes

LU - Luxembourg

Point (Locker)

Yes

Yes

Yes

Yes

Point (PUDO)

Yes

Yes

Yes

Yes

NL - Netherlands

Point (Locker)

Yes

Yes

Yes

Yes

Point (PUDO)

Yes

Yes

Yes

Yes

PT - Portugal

Point (Locker)

Yes

Yes

Yes

Yes

Point (PUDO)

Yes

Yes

Yes

Yes


 

Shipment weights and dimensions

Dimensions
(length x width x height)

Weight

Description

Comments

Dimensions
(length x width x height)

Weight

Description

Comments

64 x 38 x 8 cm

up to 25 kg

Size A

maximum dimensions and weight for size A

64 x 38 x 19 cm

up to 25 kg

Size B

maximum dimensions and weight for size B

64 x 38 x 39 cm

up to 25 kg

Size C

maximum dimensions and weight for size C

 

 

From: PL - Poland

To:

 

 

Point (Locker)

Point (PUDO)

Point (Hub)

Address

BE - Belgium

Point (Locker)

Min Dimenions inclusive (cm)

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

Max dimenions inclusive (cm)

64×38×39

64×38×39

64×38×39

64×38×39

Max Weight inclusive (kg)

25

25

25

25

Point (PUDO)

Min Dimenions inclusive (cm)

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

Max dimenions inclusive (cm)

64×38×39

64×38×39

64×38×39

64×38×39

Max Weight inclusive (kg)

25

25

25

25

ES - Spain (Espania)

Point (Locker)

Min Dimenions inclusive (cm)

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

Max dimenions inclusive (cm)

64×38×39

64×38×39

64×38×39

64×38×39

Max Weight inclusive (kg)

25

25

25

25

Point (PUDO)

Min Dimenions inclusive (cm)

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

Max dimenions inclusive (cm)

64×38×39

64×38×39

64×38×39

64×38×39

Max Weight inclusive (kg)

25

25

25

25

FR - France

Point (Locker)

Min Dimenions inclusive (cm)

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

Max dimenions inclusive (cm)

64×38×39

64×38×39

64×38×39

64×38×39

Max Weight inclusive (kg)

25

25

25

25

Point (PUDO)

Min Dimenions inclusive (cm)

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

Max dimenions inclusive (cm)
height x length x width

39x38x64

39x38x64

39x38x64

39x38x64

Max Weight inclusive (kg)

25

25

25

25

IT - Italy

Point (Locker)

Min Dimenions inclusive (cm)

0,1 cm on each side

0,1 cm on each side

0,1 cm on each side

0,1 cm on each side

Max dimenions inclusive (cm)
height x length x width

39x38x64

39x38x64

39x38x64

39x38x64

Max Weight inclusive (kg)

25

25

25

25

Point (PUDO)

Min Dimenions inclusive (cm)

0,1 cm on each side

0,1 cm on each side

0,1 cm on each side

0,1 cm on each side

Max dimenions inclusive (cm)
height x length x width

39x38x64

39x38x64

39x38x64

39x38x64

Max Weight inclusive (kg)

25

25

25

25

LU - Luxemburg

Point (Locker)

Min Dimenions inclusive (cm)

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

Max dimenions inclusive (cm)
height x length x width

39x38x64

39x38x64

39x38x64

39x38x64

Max Weight inclusive (kg)

25

25

25

25

Point (PUDO)

Min Dimenions inclusive (cm)

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

Max dimenions inclusive (cm)
height x length x width

39x38x64

39x38x64

39x38x64

39x38x64

Max Weight inclusive (kg)

25

25

25

25

NL - Netherlands

Point (Locker)

Min Dimenions inclusive (cm)

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

Max dimenions inclusive (cm)
height x length x width

39x38x64

39x38x64

39x38x64

39x38x64

Max Weight inclusive (kg)

25

25

25

25

Point (PUDO)

Min Dimenions inclusive (cm)

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

Max dimenions inclusive (cm)
height x length x width

39x38x64

39x38x64

39x38x64

39x38x64

Max Weight inclusive (kg)

25

25

25

25

PT - Portugal

Point (Locker)

Min Dimenions inclusive (cm)

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

Max dimenions inclusive (cm)
height x length x width

39x38x64

39x38x64

39x38x64

39x38x64

Max Weight inclusive (kg)

25

25

25

25

Point (PUDO)

Min Dimenions inclusive (cm)

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

2,1 cm on each side

Max dimenions inclusive (cm)
height x length x width

39x38x64

39x38x64

39x38x64

39x38x64

Max Weight inclusive (kg)

25

25

25

25


 

Shipment creation 

 

The Create Shipment API (shipments/address-to-point, shipments/point-to-point) allows users to create a single shipment. This API is designed to streamline the shipment creation process, providing various output format options, starting with links to obtain PDF label format. 

 

Service Logic and Availability Based on Delivery Type 

 

Our Create Shipments API is designed to cater to a wide range of shipping needs, offering flexibility and customization in how shipments are handled. However, certain services and delivery options are subject to variations based on specific conditions, such as the delivery type or the destination country. Below, we outline how these conditions affect the availability and specifications of services like insurance, as well as the current geographical limitations on certain delivery types.

 

Insurance Value Variability 

The insurance coverage value available for a shipment can vary depending on the chosen delivery method. This variability ensures that the insurance options offered are aligned with the risk profile and requirements of the selected delivery type. For instance: Shipments delivered to automated parcel machines (APMs) may have a different maximum insurance value compared to those delivered directly to an address. 

 

Geographic Limitations on Delivery Types 

Certain delivery options may be restricted to specific geographical regions due to operational, regulatory, or logistical considerations. 

 

Future Expansions and Adjustments 

Please note that these conditions and limitations are subject to change as we expand our services and enter into new markets or partnerships. We are continuously working to extend the range of delivery options and enhance the flexibility of our services to meet the needs of our international user base. 


 

Point to Point

 

Request URL

POST /shipments/point-to-point

 

Request Body 

The request body is a JSON object that contains detailed information about the shipment to be created, including sender and recipient details, priority, value-added services (VAS), references and parcel details within the shipment. 

 

Label format: Label format attribute will be rolling out as a way to help merchants decide what type of shipping document will be included in the response. 

 

Sample Request Body

 

Response

The response will contain details of the created shipment, including shipment id, tracking number, and any additional information pertinent to the shipment creation process.

 

Sample Response Body:

 

Root object:

Field 

Nullable? 

Type 

Description 

labelFormat 

No 

Enum 

Available options: PDF_URL 

shipment 

No 

Shipment Object 

Data necessary for booking a shipment 

 

Shipment object:

Field

Nullable?

Type

Description

sender

No

Sender Object

Information about the sender

recipient

No

String

Information about the recipient

origin

No

Origin Object 

Information about the origin

destination

No

Destination Object

Information about the destination.

priority

No

Enum

Available options: STANDARD

valueAddedServices

Yes

Value Added Services Object

List of requested additional services and it’ details:

references

Yes

References Object

Available shipment references.

parcel

No

Parcel Object

Single package details.

 

Origin object: 

Field 

Nullable? 

Type 

Description 

countryCode 

No 

String

Available options: PL

shippingMethods 

No 

Shipping Methods Object 

Available options: APM, PUDO, HUB 

 

Destination object:

Field

Nullable?

Type

Description

countryCode

Yes

String

Available options: PL

pointName

No

String

Name of the targeted delivery point.

 

Insurance object:

Field

Nullable?

Type

Description

value

No

Decimal

Max Insurance 5000

currency

No

String

Available options: EUR

Sender and recipient object:

Field

Nullable?

Type

Description

companyName

Yes

String

Can be used interchangeably instead of First and Last name.

firstName

No

String

First name

lastName

No

String

Last name 

email

No

String

Email

phone

No

Phone Object

Phone Number 

languageCode

Yes

Enum

Available options: "pl_PL", "en_GB", "it_IT", "fr_FR", "fr_LU", "fr_BE", "nl_NL", "es_ES", "pt_PT"
Limited to sender country and destination country at a time. Ex. if sender is in Poland communication can be send in Polish.

 

Phone object:

Field

Nullable?

Type

Description

prefix

No

Enum

Available options: +48

number

No

String

Phone number corresponding to a chosen prefix.

References object:

Field

Nullable?

Type

Description

custom

Yes

Custom object

Individual key-value pairs with references are optional for customers. Up to three custom key-value pairs can be provided.

 

Parcel object:

Field

Nullable?

Type

Description

type

No

Enum

Available options: STANDARD

dimensions

No

Dimensions object

 Shipment dimensions

weight

No

Weight object

Information about weight of the parcel.

label

Yes

Label object

Information to be printed on the label.

 

Dimensions object:

Field

Nullable?

Type

Description

length

No

String

Dimension of one side of the parcel

width

No

String

Dimension of one side of the parcel

height

No

String

Dimension of one side of the parcel

unit

No

Enum

Available options: CM

 

Weight object:

Field

Nullable?

Type

Description

amount

No

String

 

unit

No

String

 Available options: KG

 

Label object:

Field

Nullable?

Type

Description

comment

Yes

String

A string to be printed on the label in the comment section.

barcode

Yes

String

Alphanumeric value to be encoded into Code-128 barcode and printed on the label.


 

Address to Point

 

Request URL

POST /shipments/address-to-point

 

Request Body

The request body is a JSON object that contains detailed information about the shipment to be created, including sender and recipient details, priority, value-added services (VAS), shipment references, parcel references and parcel details within the shipment.

 

Output options: Label format attribute will be rolling out as a way to help merchants decide what type of shipping document will be included in the response.

 

Sample Request Body

 

Response

The response will contain details of the created shipment, including shipment uuid, tracking number, and any additional information pertinent to the shipment creation process.

Sample Response Body:

 

Root object:

Field

Nullable?

Type

Description

labelFormat

No

Enum

Available options: PDF_URL

shipment

No

Shipment Object

Data necessary for booking a shipment

 

Shipment object:

Field

Nullable?

Type

Description

sender

No

Sender Object

Information about the sender

recipient

No

String

Information about the recipient

origin 

No 

Origin Object 

Information about the starting point of shipping. 

destination

No

Destination Object

Information about the destination.

priority

No

Enum

Available options: STANDARD

valueAddedServices

Yes

Value Added Services Object

List of requested additional services and it’ details.

references

Yes

References Object

Available shipment references.

parcel

No

Parcel Object

Single package details.

 

Sender and recipient object:

Field

Nullable?

Type

Description

companyName

Yes

String

Can be used interchangeably instead of First and Last name.

firstName

No

String

first name

lastName

No

String

last name

email

No

String

email

phone

No

Phone Object

Information about the phone number

languageCode

Yes

Enum

Available options: "pl_PL", "en_GB", "it_IT", "fr_FR", "fr_LU", "fr_BE", "nl_NL", "es_ES", "pt_PT"
Limited to sender country and destination country at a time. Ex. if sender is in Poland communication can be send in Polish.

 

Origin object: 

Field 

Nullable? 

Type 

Description 

address 

No 

Address 

object 

Information about the starting point of shipping. 

 

Address object:

Field

Nullable?

Type

Description

countryCode

No

String

Available options: PL

postalCode

No

String

postal ode

city

No

String

city

street

No

String

street

houseNumber

No

String

house number

flatNumber

Yes

String

flat umber

 

Destination object:

Field

Nullable?

Type

Description

countryCode

Yes

String

Available options: IT, FR, LU, BE, NL, ES, PT

pointName

No

String

Name of the targeted delivery point.

 

Phone object:

Field

Nullable?

Type