InPost Integration FAQ

Business topics

Your Account Manager

Carrier website

https://inpost.pl/

Carrier privacy policy

https://inpost.pl/en/policy

Carrier logo

ShipX document

API ShipX ENG Documentation

Dokumentacja API ShipX

Fast Return document

InPost Quick Returns

InPost Szybkie Zwroty

Plugins document

[ENG] Plugins documentation

[PL] Dokumentacja wtyczki

Common Errors

https://dokumentacja-inpost.atlassian.net/wiki/spaces/PL/pages/451903492/InPost+Integration+FAQ#Possible-errors

Production

URL: https://api-shipx-pl.easypack24.net

Parcel Manager Production: https://manager.paczkomaty.pl/

Request collection: https://dokumentacja-inpost.atlassian.net/wiki/spaces/PL/pages/18153477/Authorization+Query+Collections#Query-collection-and-environment-profiles

Sandbox

URL: https://sandbox-api-shipx-pl.easypack24.net

Parcel Manager Sandbox: https://sandbox-manager.paczkomaty.pl/

(You can access the sandbox by creating an account in the Sandbox Manager)

Request collection: https://dokumentacja-inpost.atlassian.net/wiki/spaces/PL/pages/18153477/Authorization+Query+Collections#Query-collection-and-environment-profiles

Create token

Documentation:

(google translate required)

https://inpost.pl/sites/default/files/2022-03/instrukcja-konfiguracji-api-shipx.pdf

Organization ID:

Token:

inpost_locker_standard

Parcel locker shipment - standard

Delivery to Parcel Locker - the customer has 48h to collect the parcel. Can extend collection via the InPost app

inpost_courier_standard

Courier shipment standard

Delivery by courier to the indicated address

inpost_courier_c2c

Courier shipment - InPost Courier C2C (service for a retail customer - prepaid)

Delivery by courier to the indicated address

inpost_locker_pass_thru 

Parcel locker shipment - Pass-Thru

Sending at Parcel Locker and collection of the parcel by the customer at the same Parcel Locker

inpost_courier_express_1000

Courier shipment with delivery until 10:00

Delivery by courier to the specified address by a specific time

inpost_courier_express_1200

Courier shipment with delivery until 12:00

Delivery by courier to the specified address by a specific time

inpost_courier_express_1700

Courier shipment with delivery until 17:00

Delivery by courier to the specified address by a specific time

inpost_courier_palette

Courier shipment Pallet Standard

Delivery to the pallet address by dedicated transport

Allegro dedicated services

Description

inpost_locker_allegro

Allegro dedicated service

Delivery to Parcel Locker (Allegro service) - the customer has 48h to collect the parcel. Can extend collection via the InPost app

inpost_courier_allegro

Allegro dedicated service

Delivery by courier to the indicated address (Allegro service)

inpost_letter_allegro

Allegro dedicated service

Delivery by courier to the indicated address (Allegro service)

Label format

ZPL/PDF/EPL

PDF: https://api-shipx-pl.easypack24.net/v1/shipments/1592329333/label?format=pdf

ZPL: https://api-shipx-pl.easypack24.net/v1/shipments/1592329333/label?format=zpl

EPL: https://api-shipx-pl.easypack24.net/v1/shipments/1592329333/label?format=eplepepl

Label type

A6/normal

PDF - 200 DPI

ZPL - 200DPI and 300DPI (courier/parcel locker)

300DPI: https://api-shipx-pl.easypack24.net/v1/shipments/1592329333/label?format=zpl&type=dpi300

200DPI: https://api-shipx-pl.easypack24.net/v1/shipments/1592329333/label?format=zpl&type=dpi300

Label dimensions

Label field validation

143mm x 100mm (height x width)

Example

Other

• We do not support unicode characters (i.e. kanji, Cyrillic, etc.) on label

• Number of characters per PDF label:

"company_name": 35 characters

"street" and "building number" together on label: 137 characters

"city": 42 characters

"first_name" and "last_name" together on label: 58 characters

• Number of characters on the ZPL label in “reference”: 96

Courier dimensions

Maximum dimensions:

• 350 x 240 x 240 cm

Maximum weight:

• 50 kg

Quantity:

• default 1,

• maximum 99 ( only for domestic parcels )

Locker dimensions

height x width x depth cm

Size A (S) - 8 x 38 x 64 cm

Size B (M) - 19 x 38 x 64 cm

Size C (L) - 41 x38 x 64 cm

Max weight: 25 kg

The corresponding parcel size is mapped from the box into which the parcel was placed by the courier, depending on the machine.
These can be caches after the Avisomat, Laundromat or other.

Examples of mappings:
D <= A (locker size D corresponds to locker A in our systems)
E = A
H = A
I = B
J = C

Flow (endpoint)

Integration process: Integration process with InPost services

We recommend creating shipments in simplified mode

DOC: Creating a shipment in the simplified mode

Create shippments:

POST https://api-shipx-pl.easypack24.net/v1/organizations/YOUR_ID_ORGANIZATIONS/shipments

Checking the status of a shipment:

GET https://api-shipx-pl.easypack24.net/v1/shipments/ID_SHIPMENTSID S

Download label:

GET https://api-shipx-pl.easypack24.net/v1/shipments/ID_SHIPMENTS/label?format=pdf (pdf/zpl/epl)

Tracking: (not authorized)

GET https://api-shipx-pl.easypack24.net/v1/tracking/TRACKING_NUMBER

Create shipment:

Checking the status of a shipment:

Parameters

sender → The attribute is not required. If no data is provided ,by default the data of the organization in which the shipment is created will be used

By default, if you do not add the SENDER parameter in the requisition for the creation of a parcel - the sender data are assigned from our system, the ones you specified when creating an account in Parcel Manager.

If you want to overwrite the SENDER parameter data, you should add this part in the request for shipment creation:

This way you will overwrite the data, phone number or email with your own data:

‘sender": {
‘name": null,
‘company_name": ‘company_name’,
‘first_name": ‘first_name’,
‘last_name": ‘last_name’,
‘email": ‘test@grupainteger.pl’,
‘phone": ‘321321321’,
‘address": {
‘street": ‘Czerniakowska’,
‘building_number": ‘87A’,
‘city": ‘Warsaw’,
‘post_code": ‘00-718’,
‘country_code": ‘PL’
}

email → This parameter is required for Parcel Locker shipments
This parameter is not required for Courier Standard shipments

address → This parameter is not required for Parcel Locker shipments
This parameter is required for Courier Standard shipments

phone → Regex

PL: \A(\(?((\+)|00)48\)?) → 9 digits
FR: \A(\(?((\+)|00)33\)?) → 9 digits
ES: \A(\(?((\+)|00)34\)?) → 9 digits
BE: \A(\(?((\+)|00)32\)?) → 8-9 digits
DE: \A(\(?((\+)|00)49\)?) → 10-11 digits
LU: \A(\(?((\+)|00)352\)?) → 9 digits
PT: \A(\(?((\+)|00)351\)?) → 9 digits
AT: \A(\(?((\+)|00)43\)?) → 7-13 digits
GB: \A(\(?((\+)|00)44\)?) → 10 digits
IT: \A(\(?((\+)|00)39\)?) → 9-10 digits
NL: \A(\(?((\+)|00)31\)?) → 10 digits
IE: \A(\(?((\+)|00)353\)?) → 10 digits
MC: \A(\(?((\+)|00)377\)?) → 8 digits
CH: \A(\(?((\+)|00)41\)?) → 9 digits
UA: \A(\(?((\+)|00)380\)?) ->9 digits
BY: \A(\(?((\+)|00)375\)?) → 9 digits
BG: \A(\(?((\+)|00)359\)?) → 8-9 digits
CY: \A(\(?((\+)|00)357\)?) → 8 digits
CZ: \A(\(?((\+)|00)420\)?) → 9 digits
DK: \A(\(?((\+)|00)45\)?) → 8 digits
EE: \A(\(?((\+)|00)372\)?) → 7-8 digits
FI: \A(\(?((\+)|00)358\)?) → 8-10 digits
GR: \A(\(?((\+)|00)30\)?) → 10 digits
HU: \A(\(?((\+)|00)36\)?) → 9 digits
LT: \A(\(?((\+)|00)370\)?) → 8 digits
LV: \A(\(?((\+)|00)371\)?) → 8 digits
MT: \A(\(?((\+)|00)356\)?) → 8 digits
SE: \A(\(?((\+)|00)46\)?) → 9 digits

target_point → The name of the destination point to which the shipment is to be delivered, from which it will be collected by the receiver, e.g. name of the a parcel locker
Only shipments for Parcel Lockers

dropoff_point → Name of the sending point to which the sender delivers the shipment to be sent, e.g. name of the parcel locker. Required when stating the sending method pok, courier_pok, parcel_locker

reference → Additional description of the shippment e.g the order number. Will transfer information to labels for Parcel Locker service

The attribute is not required. At least 3 characters, up to 100 characters, the attribute mrefay be transferred empty

comments → The attribute is not required. At least 3 characters, up to 100 characters, the attribute mrefay be transferred empty. Will transfer information to labels for Parcel Locker service and Courier Standard

mpk → Name of the place where the costs were incurred

MPK - a value that the user can freely modify. It must be created - this value is unique and can not create another one like it.

Usage:
MPK value appears on invoices.

This allows you to split shipments (giving 2 different MPKs in shippment) and filter them later without creating a subaccount in InPost systems.
MPK works in Courier and Parcel Locker service

Statuses

DOC: Statuses

Statuses list for Parcel Locker:

https://api-shipx-pl.easypack24.net/v1/statuses?shipment_type=inpost_locker_standard&lang=en_GB

Statuses list for Courier Standard:

https://api-shipx-pl.easypack24.net/v1/statuses?shipment_type=inpost_courier&lang=en_GB

Standard process:

• Parcels first scan in Inpost sorting centre

adopted_at_source_branch
adopted_at_sorting_center

• Processing of item for delivery

adopted_at_target_branch
sent_from_source_branch

• Handing over of item to delivery

out_for_delivery

• Placed parcels in the parcel machine (for inpost_locker)

ready_to_pickup

• Delivery

delivered

• Return to shipper

return to shipper

• Delivery failed. Wrong address

undelivered_wrong_address
undelivered_incomplete_address

• Other reasons (impossible to contine with the delivery)

avizo
courier_avizo_in_customer_service_point

• Delivery failed. Customer modified delivery address

readdressed
redirect_to_box

• Delivery failed. Customer refused to accept their order

rejected_by_receiver

• Delivery delayed due to restricted delivery service in your area

delay_in_delivery

• Other reasons (impossible to contine with the delivery).

undelivered
returned_to_sender
canceled
undelivered_cod_cash_receiver

Status confirming delivery of parcel (final) generating payment (customer charged)

“Delivered”

Push technologies to delivery notifications

InPost parcels delivered in Poland receive notifications in the InPost mobile app and email notifications. If someone does not have the mobile app, they receive an SMS

Picking up parcels with Parcel Locker

Parcels can be picked up by scanning the QR code or opening the box remotely via the app

Multi-packs in inpost_courier_standard

The maximum number of multipacks is: 99
Minimum number of multipacks is: 1

DOC: https://dokumentacja-inpost.atlassian.net/wiki/spaces/PL/pages/18153501/Creating+a+shipment+in+the+simplified+mode#Query-with-multiple-packages-(can-only-be-created-for-inpost_courier)

Shipment cancellation

In order to cancel a shipment within an organization, the user has to be its member. Additionally, the shipment has to be in created or offers_prepared status, otherwise an invalid_action  error will be returned

DOC: Shipment cancellation

An unused label will be cancelled after 45 days

API Response time

On Sandbox:: extended time above 2 seconds

On Production: up to 2 seconds maximum

The time for querying the shipment should be extended to the indicated values

Common Errors

• When creating a consignment, the following is returned: “Insurance should be equal or higher than COD”

When creating a collection parcel, please note that the parcel must be insured for a minimum of the collection value or more

• API returns error "403 access forbidden fo this token”

The API returns an error when the wrong organisation id is entered. You will need to log in to https://manager.paczkomaty.pl and retrieve the organisation id located on the API tab at https://manager.paczkomaty.pl/auth/login.

• API returns error “500 Unexpected error occurred. Contact your administrator at integracja@inpost.pl”

If the API returns a 500 error, contact the integracja@inpost.pl integration team or your account manager with the error ID that will appear in the response from the API.,

• API returns error “debt_collection”

If you are a postpaid customer (you have a contract) please check that the payment for the last invoice has been made and then contact your account manager to check that the contract is connected to your account

• API returns error “trucker_ID_is_not_set_for_organization” error

Please contact your account manager. This means that the courier service has not been connected

• API returns error “target_point: does_not_exist”

The specified receiving point “target_point” is incorrect (name) or the point has been taken off the network due to failure, relocation, etc.

• API returns error “target_point: invalid_box_machine_function”

It means that the selected pick-up point does not have the function of collecting a shipment from this point. You can only send a shipment at this point.

Tracking API/Report

Report: Report

API: Tracking

Example request (No need to authorise):

GET https://api-shipx-pl.easypack24.net/v1/tracking/520000015802677026992693

URL tracking link

https://inpost.pl/sledzenie-przesylek?number=[parcel_number]

Other

• The API allows you to check the status of a single shipment - it is not possible to verify several parcels at once

• API allows tracking the status of parcels 45 days in advance

Configuration

Webhook is used to send the user information about changes in the status of the shipment.

For a production environment, the webhook address can be added on the page https://manager.paczkomaty.pl/zaloguj  in the My Account> API tab

For a sandbox environment, the webhook address can be added on the page https://sandbox-manager.paczkomaty.pl/  in the My Account> API tab

DOC: Webhooks

Example when the shipment status has been changed:

{
  "event_ts": "2020-03-20 15:08:42 +0100",
  "event": "shipment_status_changed",
  "organization_id": 1,
  "payload": {
    "shipment_id": 49,
    "status": "delivered",
    "tracking_number": "602677439331630337653846"
  }
}

Example when the shipment has been created:

{
  "event_ts": "2020-03-20 15:08:06 +0100",
  "event": "shipment_confirmed",
  "organization_id": 1,
  "payload": {
    "shipment_id": 49,
    "tracking_number": "602677439331630337653846"
  }
}

Addres IP webhook

Webhook address database: 91.216.25.0/24

Documentation Geowidget V5

DOC: Geowidget v5

Example:

Production: https://geowidget.inpost.pl/examples/index.html

Sandbox: https://sandbox-easy-geowidget-sdk.easypack24.net/examples/index.html

API Points

Authorization

Production environment

https://api.inpost.pl/v1/points

Sandbox environment

https://sandbox-api-gateway-pl.easypack24.net/v1/points

DOC (PROD/SAND): Points (Parcel Locker, ParcelPoint)

Token Geowidget

Access to the Points API is authorised. Obtaining a token is possible through the Parcel Manager.
At the beginning of the documentation it is described how to obtain the token:
Points (Parcel Locker, ParcelPoint)

The Points resource represents locations where the services of logistics operators are available. Points can be self-service machines (Parcel Machine®) or branches, customer service points

The parcel_locker type displays all points from which the customer can collect the parcel and only the currently active (enabled) points. Excludes points that are only used for sending parcels (no parcel pick-up)

Search point by location:

Pagination:

DOC: https://dokumentacja-inpost.atlassian.net/wiki/spaces/PL/pages/18153493/Points+Parcel+Locker+ParcelPoint#Search-criteria

Authorization

Email/Password from Parcel Manager https://manager.paczkomaty.pl/auth/login

Endpoint

Production: https://api.paczkomaty.pl

Sandbox: https://sandbox-api.paczkomaty.pl

DOC:

InPost Quick Returns

The function https://api.paczkomaty.pl/?do=revloggenerateactivecode is used to generate one active return code, with which you can send a parcel at the Parcel Locker

DOC: Generating active code

The https://api.paczkomaty.pl/?do=revloggetreport function allows you to generate a report that will return active codes and used codes along with the shipment status.

DOC: Report

You can check the current status of a shipment sent with a return code using the Report function.

Available parcel sizes

height x width x depth cm

Size A (S) - 8 x 38 x 64 cm

Size B (M) - 19 x 38 x 64 cm

Size C (L) - 41 x38 x 64 cm

Shipment return tracking

Example tracking flow:

The moment when customers generate a return code:

(see from below)

"tracking_details": [
        {
            "origin_status": "DOR",
            "status": "delivered",
            "agency": null,
            "location": null,
            "datetime": "2024-07-03T12:56:26.000+02:00"
        },
        {
            "origin_status": "PDD_3",
            "status": "out_for_delivery_to_address",
            "agency": null,
            "location": null,
            "datetime": "2024-07-03T08:14:43.000+02:00"
        },
        {
            "origin_status": "PWO",
            "status": "adopted_at_source_branch",
            "agency": null,
            "location": null,
            "datetime": "2024-07-03T04:25:07.000+02:00"
        },
        {
            "origin_status": "WZO",
            "status": "sent_from_source_branch",
            "agency": null,
            "location": null,
            "datetime": "2024-07-02T17:30:52.000+02:00"
        },
        {
            "origin_status": "PWO",
            "status": "adopted_at_source_branch",
            "agency": null,
            "location": null,
            "datetime": "2024-07-02T17:00:31.000+02:00"
        },
        {
            "origin_status": "OZPA",
            "status": "taken_by_courier",
            "agency": null,
            "location": null,
            "datetime": "2024-07-02T08:52:07.000+02:00"
        },
        {
            "origin_status": "NWP",
            "status": "dispatched_by_sender",
            "agency": null,
            "location": null,
            "datetime": "2024-07-01T21:24:14.000+02:00"
        },
        {
            "origin_status": "PPN",
            "status": "confirmed",
            "agency": null,
            "location": null,
            "datetime": "2024-07-01T21:24:01.000+02:00"
        }