inPost.it • Public Developers Documentation (1.0.0)

Download OpenAPI specification:Download

This API specification is documented in OpenAPI format and defines the processes and steps that are commonly used from our customers.

Glossary

Point is the name used in our API to identify an Automated Parcel Locker (APM) and/or a PUDO (Pick-Up/Drop-Off InPost Point)

APM identify an Automated Parcel Locker.

PUDO identify a Pick-Up/Drop-Off InPost point

UC acronym for "use case". Some API documentation have this acronym before the name. This means that the documentation could be different from the complete one (e.g. some parameters may be partially missing, other parameters could have specific information, etc...)

Environments

Env Description URL
Staging Test environment integrated with inPost logistic https://stage-api-shipx-it.easypack24.net
Production - https://api-shipx-it.easypack24.net

Authentication

bearerAuth

Our APIs are divided into two categories:

  • Public: no security parameters required.
  • Private: a Bearer Token linked to your company will be required, in some cases, you will also need your OrganizationID as path parameter.

Request access

To get your Bearer Token and OrganizationID please contact InPost on the email provided at the top of this page.

Remember that we provide two different token: one for production environment and one for staging environment.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

Points

Points

Get the complete list of available points.

Request
query Parameters
name
string

Searches for points by name.

case-sensitive: parameter in capital letters.

Example: name=ITMIL00001P OR ITMIL00001P,ITMIL00005P,...
type
Array of strings (type)

Searches for points by type.

Items Enum: "parcel_locker" "pok" "pop"
Example: type=pop OR parcel_locker,pop,...
functions
Array of strings (functions)

Searches for points by functions.

Items Enum: "parcel" "parcel_send" "parcel_collect" "parcel_reverse_return_send" "standard_courier_send"
Example: functions=parcel OR parcel,parcel_send,...
partner_id
string

Searches for points by partner_id.

Example: partner_id=1,0,... OR 1
is_next
boolean

Filter for NEXT points.

Example: is_next=true
payment_available
boolean

Searches by point's payment availability.

Example: payment_available=true
city
string

Searches for points with given cities.

case-sensitive: parameters with the first capital letter.

Example: city=Roma,Lecce,... OR Roma
province
string 2 characters

Searches for points with given provinces.

case-sensitive: parameters with capital letters.

Example: province=MI,BA,... OR MI
relative_point
string <latitude,longitude>

Searches for points closest to the given coordinates.

Example: relative_point=52.123,19.321
relative_post_code
string

Searches for points closest to the given postcode.

Example: relative_post_code=20068
max_distance
number <meters> <= 50000
Default: 10000

Searches for points in distance up to the given value from relative_point or relative_post_code.

Example: max_distance=2000
limit
number

Limit the maximum number of points retrieved when using relative_point or relative_post_code.

Example: limit=10
sort_by
string
Default: "name"

SORTING: Sorts results by given parameter.

Enum: "name" "distance_to_relative_point" "status"
Example: sort_by=status
sort_order
string
Default: "asc"

SORTING: Set sort .

Enum: "asc" "desc"
Example: sort_order=desc
page
number
Default: 1

PAGINATION: Defines the page for which the results should be returned.

Example: page=4
per_page
number <= 500
Default: 25

PAGINATION: Defines the amount of points returned per page.

Example: per_page=100
fields
string

ATTRIBUTES-FILTERING: Defines the point attributes that should be returned.

Example: fields=name,type
Responses
200

Success

get/v1/points
Request samples
curl -i -X GET \
  'https://stage-api-shipx-it.easypack24.net/v1/points?name=ITMIL00001P%20OR%20ITMIL00001P%2CITMIL00005P%2C...&type=pok%2Cpop&functions=parcel%2Cparcel_collect%2Cparcel_reverse_return_send%2Cparcel_send%2Cstandard_courier_send&partner_id=1%2C0%2C...%20OR%201&is_next=true&payment_available=true&city=Roma%2CLecce%2C...%20OR%20Roma&province=MI%2CBA%2C...%20OR%20MI&relative_point=52.123%2C19.321&relative_post_code=20068&max_distance=2000&limit=10&sort_by=status&sort_order=desc&page=4&per_page=100&fields=name%2Ctype'
Response samples
application/json
{
  • "count": 940,
  • "page": 1,
  • "per_page": 25,
  • "total_pages": 38,
  • "items": [
    ]
}

UC/Point list by `relative_post_code`

######################

TRY IT NOT ENABLED

The "try it" feature isn't enabled for this use case due to technical limit (feature not support fixed query parameters). Try this with Postman.

######################

Query parameters

?relative_post_code=20068&max_distance=2000

Use cases couldn't be tested in the right column.

Request
query Parameters
relative_post_code
string

Searches for points closest to the given postcode.

Example: relative_post_code=20068
max_distance
number <meters> <= 50000
Default: 10000

Searches for points in distance up to the given value from relative_point or relative_post_code.

Example: max_distance=2000
Responses
200

Success

get/v1/points{#filterByRelativePostCodeQuery}
Request samples
curl -i -X GET \
  'https://stage-api-shipx-it.easypack24.net/v1/points{?relative_post_code=20068&max_distance=2000#filterByRelativePostCodeQuery}'
Response samples
application/json
{
  • "count": 8,
  • "page": 1,
  • "per_page": 25,
  • "total_pages": 1,
  • "items": [
    ],
  • "meta": {}
}

Geowidget - HTML/JS Widget

Basic info

GEOv4 (also known as Geowidget v4) is a point locator and picker designed by Integer sp. z o.o. It's main goal is to show map of points with several types (for example machines), provide informations about this points and give possibility to integrate with clients external systems. GEOv4 is a widget-type software, it means that whole code and processing is held on InPost servers, external clients only attach link to this code and specify configuration that will be used on theirs systems.

Data source

Data made available in the widget are extracted from the italian production environment: https://api-it-local-points.easypack24.net/v1/points

Design (RWD)

Desktop view

Mobile views

Integration

  1. Geowidget v4 can be easily integrated into any system or web page. Client web page should insert script in tag:
<script async src="https://geowidget.easypack24.net/js/sdk-for-javascript.js"></script>
<link rel="stylesheet" href="https://geowidget.easypack24.net/css/easypack.css"/>
  1. Include the widget configuration in Javascript
<script type="text/javascript">
  window.easyPackAsyncInit = function () {
    easyPack.init({});  // Configuration object
    var map = easyPack.mapWidget('easypack-map', function(point){
      console.log(point);
    });
  };
</script>
  1. Include the widget with a simple HTML tag inside your page.

    IMPORTANT the ID shouldn't be changed and should correspond to the ID used in the previous script.

<div id="easypack-map"></div>
  1. If you want to configure the widget, you can simply add your configurations in the Configuration Object included during the step 2. Here's an example of configuration, you can find parameter's details in the next charapter.
easyPack.init({
  defaultLocale: 'pl',
  points: {
    types: ['parcel_locker']
  },
  map: {
    defaultLocation: [51.507351, -0.127758],
    initialTypes: ['parcel_locker']
  }
});
  1. Check some example of the final result before to proceed:

Configuration parameters

ParameterName Description Default value
paymentFilter - false
listItemFormat Allows to change default layout of point information on points list. ["<b>{name}</b>", "<strong>{address_details.street}</strong> {address_details.building_number}"]
addressFormat A string that rapresent address format '{street} {building_number}
{post_code} {city}'
apiEndpoint URL to API Points which will be connected to Geowidget it: https://api-it-points.easypack24.net/v1
searchType Setup search type, available to use Open Street Map Nominatim or Google Maps Autocomplete.

Available parameters: osm, google

⚠️ For 'google' option map.googleKey is required.
'osm'
points Setup points details

Available parameters:
parcel - points with functions send and collect
parcel_send - points with functions send only
parcel_collect - points with functions collect only
{ types: ['pop', 'parcel_locker'], allowedToolTips: ['pok', 'pop'], functions: [] }
mapType Setup map type, available to use Open Street Map or Google Maps.

Available parameters: osm, google

⚠️ For 'google' option map.googleKey is required.
'osm'
map Setup map details. { googleKey: '', useGeolocation: true, initialZoom: 13, detailsMinZoom: 15, /*minimum zoom after marker click*/ autocompleteZoom: 14, visiblePointsMinZoom: 13, defaultLocation: [52.229807, 21.011595], initialTypes: ['pop', 'parcel_locker'], /*which type should be selected by default. Options: parcel_locker_only, parcel_locker, pop */}
mobileSize Screen width below which mobile version is triggered. 768
instance Override default config by config prepared for instance.

Available parameters:
pl
mobileFiltersAsCheckbox Option set to false make filter option as radio in mobile, option true as checkobx. true
locales Languages that will be displayed as list in front layer. They can be dynamically changed. ['pl','uk']
defaultLocale Geowidget language that will be uses in front-end.

Available parameters: pl,uk
'pl'
display Enable/disable visible type filters and search bar { showTypesFilters: true, showSearchBar: true }
langSelection Determines if language selection bar should be displayed. false
filters Determines if filters (functions) bar should be displayed. false
customDetailsCallback Allows to set custom callback for details action

Example: function(point){...}, false
false
customMapAndListInRow Allow to change layout where list of point is below map. Points on list were paginated, number of point per page can be configured. { enabled: false, itemsPerPage: 8 }

Common use-cases

  • If you wants to get point data that user selected on Geowidget, you can configure callback like this:

    var map = easyPack.mapWidget('easypack-map', function(point) {
      alert(point.name);
    });
    

    Example 1 Example 2

  • Show Geowidget inside modal:

    easyPack.modalMap(function(point, modal) {
      modal.closeModal();
      console.log(point);
    }, { width: 500, height: 600 });
    

    Example

  • Show Geowidget as dropdown:

    easyPack.dropdownWidget('easypack-widget', function(point) {
      console.log(point)
    });
    

    Example

  • Enable Google Maps:

    • Google API Key is required. The key should have the following interfaces enabled:

      • Geocoding API
      • Geolocation API
      • Google Cloud APIs
      • Maps JavaScript API
      • Places API
    • Then, you need to initialize the widget like that:

      easyPack.init({
        mapType: 'google',
        searchType: 'google',
        map: {
          googleKey: 'your-google-api-key'
        }
      });
      

    Example

  • Function for search point by name and show it on map:

    map.searchLockerPoint('PointName');
    

    Example

  • Function for search place by name and show it on map:

    map.searchPlace('Wroclaw');
    

    Example

  • Display points with different types

    • PARCEL_LOCKER_ONLY - In results we have points - physical machines only

      points: {
        types: [‘parcel_locker_only']
      },
      map: {
        initialTypes: [‘parcel_locker_only']
      }
      
    • POP - In results we have points with types 'pop' and 'super_pop'

      points: {
        types: [‘pop']
      },
      map: {
        initialTypes: [‘pop']
      }
      
    • PARCEL_LOCKER - In results we have points -physical machines and 'super_pop' type

      points: {
        types: [‘parcel_locker']
      },
      map: {
        initialTypes: [‘parcel_locker']
      }
      
    • PARCEL_LOCKER_SUPERPOP - In results we have points - 'super_pop' type only

      points: {
        types: [‘parcel_locker_superpop']
      },
      map: {
        initialTypes: [‘parcel_locker_superpop']
      }
      
    • PARCEL LOCKER + POP - In results we have points - physical machines, 'pop' and 'super_pop' types

      points: {
        types: [‘parcel_locker', 'pop']
      },
      map: {
        initialTypes: [‘parcel_locker', 'pop']
      }
      
    • PARCEL LOCKER + POP - In results we have points - physical machines, 'pop' and 'super_pop' types but selected is only 'parcel_locker' and 'super_pop' type

      points: {
        types: [‘parcel_locker, pop']
      },
      map: {
        initialTypes: [‘parcel_locker']
      }
      
    • PARCEL LOCKER + POP - In results we have points - physical machines, 'pop' and 'super_pop' types but selected is only 'pop' and 'super_pop' type

      points: {
        types: [‘parcel_locker, pop']
      },
      map: {
        initialTypes: [‘pop']
      }
      
options/{#geocoding}
Request samples
curl -i -X OPTIONS \
  'https://stage-api-shipx-it.easypack24.net/{#geocoding}'

Shipments

The Shipment will be created through the Shipment Shipx API. This API can be invoked in manyways, for the italian market the Simplified Mode is the standard. Some simple informations will be asked, such as: sender, receiver, size of the parcel and the destination.

Other info:

  • In the Locker2Locker service the customer can drop the parcelin whatever Locker or PUDO point he prefers
  • The service in Locker or PUDO are totally equivalent, it just change from the customer experience
  • Technically, in the checkout phase a new Shipment is created considering:
    • The request will be created in simplified mode
    • The origin point is not needed but the destination is mandatory
    • Sender is optional, if it’s not present in the shipment creation, the system will automatically take as sender the Client Configuration
    • The customer can send the reference to be printed in the label and also the customer reference ID for customer support service

Shipment

Request
Security:
path Parameters
organization_id
required
number (organization_id)

Your organization_id provided with the API Token. Read more in the Authentication section.

Example: 23
Request Body schema: application/json
required
object (receiver)
object (receiver)

Sender is optional, if it’s not present in the shipment creation, the system will automatically take as sender the Client Configuration

required
parcels_template (object) or Array of parcels_array (objects)
service
required
string (service)

Service selected by the client.

Enum: "inpost_locker_standard" "inpost_courier_c2c"
required
object (custom_attributes)

Additional shipment attributes.

reference
string (reference) [ 3 .. 100 ] characters

Additional shipment description that will be printed in the label (e.g. order number)

external_customer_id
string (external_customer_id)

ID of the broker generating shipments within a different organization for customer service purpose

post/v1/organizations/{organization_id}/shipments
Request samples
application/json
{
  • "receiver": {
    },
  • "sender": {
    },
  • "parcels": {
    },
  • "service": "inpost_courier_c2c",
  • "custom_attributes": {
    },
  • "reference": "ORDER: #0011001",
  • "external_customer_id": 23
}

Shipment

Get the complete list of shipments for current organization_id.

Request
Security:
path Parameters
organization_id
required
number (organization_id)

Your organization_id provided with the API Token. Read more in the Authentication section.

Example: 23
query Parameters
id
string

Searches for shipment by ID or IDs.

Example: id=44792,44791
created_at
string

Filter by creation date

Example: created_at=2016-01-07
created_at_gteq
string <timestamp>

Filter for shipments created after given date.

Example: created_at_gteq=1451650200
created_at_lteq
string <timestamp>

Filter for shipments created before given date.

Example: created_at_lteq=1451650200
tracking_number
string (tracking_number)

Filter by tracking number

Example: tracking_number=820100559215100015577452
status
string

Filter for shipments with given statuses.

Example: status=confirmed
service
string

Searches for shipments with given service or services.

Example: service=inpost_locker_standard
carrier
string

Searches for shipments with given carrier or carriers.

Example: carrier=InPost%20Kurier
receiver_name
string

Searches for shipments for which the receiver first_name, last_name or company_name starts with the given string.

Example: receiver_name=Smith
receiver_address
string

Searches for shipments for which receiver address starts with the given string.

Example: receiver_address=Zaw
receiver_city
string

Searches for shipments with receivers city matching the given string

Example: receiver_city=Roma
receiver_post_code
string

Searches for shipments which receivers postal code starts with the given string

Example: receiver_post_code=20060
receiver_country_code
string

Searches for shipments with receivers country code matching the given string

Example: receiver_country_code=IT
receiver_phone
string

Searches for shipments with receivers telephone number matching the given string

Example: receiver_phone=320009988
receiver_email
string

Searches for shipments which receivers email starts with the given string

Example: receiver_email=devnull@inpost.pl
sender_name
string

Searches for shipments for which the sender first_name, last_name or company_name starts with the given string.

Example: sender_name=Smith
sender_address
string

Searches for shipments for which sender address starts with the given string.

Example: sender_address=Zaw
sender_city
string

Searches for shipments with senders city matching the given string

Example: sender_city=Roma
sender_post_code
string

Searches for shipments which sender's postal code starts with the given string

Example: sender_post_code=20060
sender_country_code
string

Searches for shipments with senders country code matching the given string

Example: sender_country_code=IT
sender_phone
string

Searches for shipments with sender's telephone number matching the given string

Example: sender_phone=320009988
sender_email
string

Searches for shipments which senders email starts with the given string

Example: sender_email=devnull@inpost.pl
external_customer_id
string

Searches for shipments created by a broker for which the id is identical to the given string

Example: external_customer_id=Broker390
page
number
Default: 1

PAGINATION: Defines the page for which the results should be returned.

Example: page=4
per_page
number <= 500
Default: 25

PAGINATION: Defines the amount of points returned per page.

Example: per_page=100
sort_by
string
Default: "created_at"

SORTING: Sorts results by given parameter.

Enum: "id" "created_at" "tracking_number" "service" "status" "insurance_amount" "cod_amount" "external_customer_id"
Example: sort_by=id
sort_order
string
Default: "asc"

SORTING: Set sort .

Enum: "asc" "desc"
Example: sort_order=desc
Responses
200

Success

get/v1/organizations/{organization_id}/shipments
Request samples
curl -i -X GET \
  'https://stage-api-shipx-it.easypack24.net/v1/organizations/{organization_id}/shipments?id=44792%2C44791&created_at=2016-01-07&created_at_gteq=1451650200&created_at_lteq=1451650200&tracking_number=820100559215100015577452&status=confirmed&service=inpost_locker_standard&carrier=InPost%2520Kurier&receiver_name=Smith&receiver_address=Zaw&receiver_city=Roma&receiver_post_code=20060&receiver_country_code=IT&receiver_phone=320009988&receiver_email=devnull%40inpost.pl&sender_name=Smith&sender_address=Zaw&sender_city=Roma&sender_post_code=20060&sender_country_code=IT&sender_phone=320009988&sender_email=devnull%40inpost.pl&external_customer_id=Broker390&page=4&per_page=100&sort_by=id&sort_order=desc' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "count": 13,
  • "page": 1,
  • "per_page": 100,
  • "items": [
    ]
}

UC/Shipments Hub2Locker

Shipments Hub2Locker

Request
Security:
path Parameters
organization_id_H2L
required
number (organization_id)

Your organization_id provided with the API Token. Read more in the Authentication section.

Example: 23
Request Body schema: application/json

This requestBody contains specific data and information for a H2L shipment use-case.

required
object (receiver)
object (receiver)

If no data are provided, the data of the organization under which the shipment is being created will be used by default (only in case of single warehouse).

required
parcels_template (object) or Array of parcels_array (objects)
service
required
string (service)

For Hub2Locker shipments, this parameter should always be inpost_locker_standard

Enum: "inpost_locker_standard" "inpost_courier_c2c"
required
object (custom_attributes_H2L)

Additional shipment attributes.

reference
string (reference) [ 3 .. 100 ] characters

Additional shipment description that will be printed in the label (e.g. order number)

external_customer_id
string (external_customer_id)

ID of the broker generating shipments within a different organization for customer service purpose

Responses
200

Success

post/v1/organizations/{organization_id_H2L}/shipments
Request samples
application/json
{
  • "receiver": {
    },
  • "sender": {
    },
  • "parcels": {
    },
  • "service": "inpost_locker_standard",
  • "custom_attributes": {
    },
  • "reference": "ORDER: #0011001",
  • "external_customer_id": 23
}
Response samples
application/json
{
  • "id": 44617,
  • "status": "created",
  • "tracking_number": null,
  • "service": "inpost_locker_standard",
  • "reference": "ORDER: #99111000",
  • "is_return": false,
  • "application_id": 27,
  • "created_by_id": null,
  • "external_customer_id": null,
  • "sending_method": null,
  • "end_of_week_collection": false,
  • "comments": null,
  • "mpk": null,
  • "additional_services": [ ],
  • "custom_attributes": {
    },
  • "insurance": {
    },
  • "sender": {
    },
  • "receiver": {
    },
  • "selected_offer": null,
  • "offers": [ ],
  • "transactions": [ ],
  • "parcels": [
    ],
  • "created_at": "2022-02-11T17:30:34.860+01:00",
  • "updated_at": "2022-02-11T17:30:34.860+01:00"
}

UC/Shipments Locker2Locker

Shipments Locker2Locker

Request
Security:
path Parameters
organization_id_L2L
required
number (organization_id)

Your organization_id provided with the API Token. Read more in the Authentication section.

Example: 23
Request Body schema: application/json

This requestBody contains specific data and information for a L2L shipment use-case.

required
object (receiver)
object (receiver)

If no data are provided, the data of the organization under which the shipment is being created will be used by default

required
parcels_template (object) or Array of parcels_array (objects)
service
required
string (service)

For Locker2Locker shipments, this parameter should always be inpost_locker_standard

Enum: "inpost_locker_standard" "inpost_courier_c2c"
required
object (custom_attributes_L2L)

Additional shipment attributes.

reference
string (reference) [ 3 .. 100 ] characters

Additional shipment description that will be printed in the label (e.g. order number)

external_customer_id
string (external_customer_id)

ID of the broker generating shipments within a different organization for customer service purpose

Responses
200

Success

post/v1/organizations/{organization_id_L2L}/shipments
Request samples
application/json
{
  • "receiver": {
    },
  • "sender": {
    },
  • "parcels": {
    },
  • "service": "inpost_locker_standard",
  • "custom_attributes": {
    },
  • "reference": "ORDER: #0011001",
  • "external_customer_id": 23
}
Response samples
application/json
{
  • "id": 44123,
  • "status": "created",
  • "tracking_number": null,
  • "service": "inpost_locker_standard",
  • "reference": "string",
  • "is_return": false,
  • "application_id": 27,
  • "created_by_id": null,
  • "external_customer_id": "23",
  • "sending_method": "parcel_locker",
  • "end_of_week_collection": false,
  • "comments": null,
  • "mpk": null,
  • "additional_services": [ ],
  • "custom_attributes": {
    },
  • "insurance": {
    },
  • "sender": {
    },
  • "receiver": {
    },
  • "selected_offer": null,
  • "offers": [ ],
  • "transactions": [ ],
  • "parcels": [
    ],
  • "created_at": "2022-02-10T11:52:39.613+01:00",
  • "updated_at": "2022-02-10T11:52:39.613+01:00"
}

UC/Shipments Locker2Hub

Shipments Locker2Hub

Request
Security:
path Parameters
organization_id_L2H
required
number (organization_id)

Your organization_id provided with the API Token. Read more in the Authentication section.

Example: 23
Request Body schema: application/json

This requestBody contains specific data and information for a L2H shipment use-case.

required
object (receiver)
object (receiver)

If no data are provided, the data of the organization under which the shipment is being created will be used by default

required
parcels_template (object) or Array of parcels_array (objects)
service
required
string (service)

For Locker2Hub shipments, this parameter should always be inpost_courier_c2c

Enum: "inpost_locker_standard" "inpost_courier_c2c"
required
object (custom_attributes_L2H)

Additional shipment attributes.

reference
string (reference) [ 3 .. 100 ] characters

Additional shipment description that will be printed in the label (e.g. order number)

external_customer_id
string (external_customer_id)

ID of the broker generating shipments within a different organization for customer service purpose

Responses
200

Success

post/v1/organizations/{organization_id_L2H}/shipments
Request samples
application/json
{
  • "receiver": {
    },
  • "sender": {
    },
  • "parcels": {
    },
  • "service": "inpost_courier_c2c",
  • "custom_attributes": {
    },
  • "reference": "ORDER: #0011001",
  • "external_customer_id": 23
}
Response samples
application/json
{
  • "id": 44107,
  • "status": "created",
  • "tracking_number": null,
  • "service": "inpost_courier_c2c",
  • "reference": "ORDER: #00111000",
  • "is_return": false,
  • "application_id": 27,
  • "created_by_id": null,
  • "external_customer_id": null,
  • "sending_method": null,
  • "end_of_week_collection": false,
  • "comments": null,
  • "mpk": null,
  • "additional_services": [ ],
  • "custom_attributes": {
    },
  • "insurance": {
    },
  • "sender": {
    },
  • "receiver": {
    },
  • "selected_offer": null,
  • "offers": [ ],
  • "transactions": [ ],
  • "parcels": [
    ],
  • "created_at": "2022-02-10T11:50:48.228+01:00",
  • "updated_at": "2022-02-10T11:50:48.228+01:00"
}

Shipment Tracking Statuses

STANDARD TRACKING FOR H2L

  1. confirmed
  2. adopted_at_source_branch
  3. ready_to_pickup
  4. pickup_reminder_sent - Optional
  5. delivered

STANDARD TRACKING FOR L2L

  1. confirmed
  2. dispatched_by_sender
  3. taken_by_courier
  4. adopted_at_source_branch
  5. ready_to_pickup
  6. pickup_reminder_sent - Optional
  7. delivered

STANDARD TRACKING FOR L2H

  1. confirmed
  2. dispatched_by_sender
  3. taken_by_courier
  4. adopted_at_source_branch
  5. out_for_delivery - Optional
  6. returned_to_sender
Responses
200

Success

get/v1/statuses
Request samples
curl -i -X GET \
  https://stage-api-shipx-it.easypack24.net/v1/statuses
Response samples
application/json
{
  • "items": [
    ]
}

Labels

The label entity is automatically generated after the creation of a shipment. You can retrieve the shipping label in various formats. Here's an example label with some explanations.

Fields details:

  • 1-7 are automatically calculated by the system

  • 8 corrisponds to the template of the specific parcel

    Template Dimension Weight Description
    small 8 x 38 x 64 cm do 25 kg Size A
    medium 19 x 38 x 64 cm do 25 kg Size B
    large 41 x 38 x 64 cm do 25 kg Size C
  • 9 is the target point (Locker or PUDO name and Hub)

  • 10 - 11 are Name and Adresses for sender and receiver

  • 13 indicates if the parcel will be picked up by a courier or drop off by the customer

  • 17 is the Reference indicated in the specific Shipment (if any)

Shipment Reference Edit

Requirements:

  • this feature is disabled by default. The activation is enabled on-demand by contacting InPost's integration team.
  • in order to change a shipment reference, the parcel should have the pickup_time_expired or stored status.
Request
Security:
path Parameters
shipment_id
required
number (shipment_id)

Shipment ID provided after a Shipment POST action.

Example: 23
query Parameters
reference
required
string (reference) [ 3 .. 100 ] characters

Additional shipment description that will be printed in the label (e.g. order number). The new reference should be encoded (SPACE is encoded as '+' or "%20").

Example: reference=New%20ORDER-CODE:#001000990
put/v1/shipments/{shipment_id}/attributes
Request samples
curl -i -X PUT \
  'https://stage-api-shipx-it.easypack24.net/v1/shipments/{shipment_id}/attributes?reference=ORDER%3A%20%230011001' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Label

Get label in various format.

Request
Security:
path Parameters
shipment_id
required
number (shipment_id)

Shipment ID provided after a Shipment POST action.

Example: 23
query Parameters
format
string
Default: "pdf"

Label's file type

Enum: "pdf" "zpl"
Example: format=pdf
type
string

Label's page format

Enum: "normal" "A6"
Example: type=normal
Responses
200

File

get/v1/shipments/{shipment_id}/label
Request samples
curl -i -X GET \
  'https://stage-api-shipx-it.easypack24.net/v1/shipments/{shipment_id}/label?format=pdf&type=normal' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Tracking

After the Shipment Creation, there are two alternative ways to keep updated about the status of a shipment: Configured a Webhook or invoke Shipment Tracking API.

Useful resources:

Tracking

For implementing an on-demand alignment, the best solution can be request of the tracking via ShipX Tracking API with the tracking number

Tracking resource is an object representing information about the current status of the shipment in the logistics system. It can be utilized to get information about the creation, status change and status history of the shipment

Request
path Parameters
tracking_number
required
string (tracking_number)

Tracking Id provided in all shipments.

Example: 820100559215100015577452
Responses
200

Success

400

uknown_tracking_number

404

resource_not_found

get/v1/tracking/{tracking_number}
Request samples
curl -i -X GET \
  'https://stage-api-shipx-it.easypack24.net/v1/tracking/{tracking_number}'
Response samples
application/json
{
  • "tracking_number": "820100559215100015577452",
  • "service": "inpost_locker_standard",
  • "type": "inpost_locker_standard",
  • "status": "confirmed",
  • "custom_attributes": {
    },
  • "tracking_details": [
    ],
  • "expected_flow": [ ],
  • "created_at": "2022-02-14T12:48:18.926+01:00",
  • "updated_at": "2022-02-14T12:48:19.570+01:00"
}

Webhook Tracking

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

Used to align near real-time a client every time a significant change has occurred.

Available async-events

  • Shipment Confirmation
  • Shipment Status Changed
  • Error

Provided address conditions:

  • Correct URL structure

  • Access to the resource to which the entered URL points

  • Resource should respond with HTTP 200

    Example:
    
      http://www.serwer.pl:8080/catalog1/catalog2/file.xxx
    
      {protocol}://{address}:{port}{file_path}
    

Payload Examples

Payload Example - New shipment created

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

Payload Example - Shipment status 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": null
  }
}

Payload Example - Shipment status changed to offers_prepared

{
  "event_ts": "2020-03-13 10:48:01 +0100",
  "event": "offers_prepared",
  "organization_id": 1,
  "payload": {
    "shipment_id": 349,
    "offers": [
      {
        "id": 481,
        "status": "unavailable",
        "expires_at": null,
        "rate": null,
        "currency": null,
        "additional_services": [],
        "carrier": {
          "id": "inpost_locker",
          "name": "InPost Paczkomaty",
          "description": "InPost Paczkomaty - Przesyłki paczkomatowe"
        },
        "service": {
          "id": "inpost_locker_standard_smart",
          "name": "Paczkomatowa standardowa",
          "description": "Przesyłka paczkomatowa standardowa"
        },
        "unavailability_reasons": [
          {
            "key": "allegro_email_invalid",
            "message": "allegro_email_invalid"
          }
        ]
      },
      {
        "id": 480,
        "status": "unavailable",
        "expires_at": null,
        "rate": null,
        "currency": null,
        "additional_services": [],
        "carrier": {
          "id": "inpost_locker",
          "name": "InPost Paczkomaty",
          "description": "InPost Paczkomaty - Przesyłki paczkomatowe"
        },
        "service": {
          "id": "inpost_locker_allegro_smart",
          "name": "Allegro Paczkomaty24/7 InPost",
          "description": "Przesyłka paczkomatowa Allegro Paczkomaty24/7 InPost"
        },
        "unavailability_reasons": [
          {
            "key": "invalid_target_point_function",
            "message": "Invalid target point function."
          },
          {
            "message": "allegro_email_invalid"
          }
        ]
      },
      {
        "id": 479,
        "status": "available",
        "expires_at": "2020-03-13T10:53:01.852+01:00",
        "rate": null,
        "currency": "PLN",
        "additional_services": [],
        "carrier": {
          "id": "inpost_courier",
          "name": "InPost Kurier",
          "description": "InPost Express - Przesyłki kurierskie"
        },
        "service": {
          "id": "inpost_courier_c2c",
          "name": "Kurier standard",
          "description": "Przesyłka kurierska standardowa"
        },
        "unavailability_reasons": null
      },
      {
        "id": 478,
        "status": "available",
        "expires_at": "2020-03-13T10:53:01.674+01:00",
        "rate": null,
        "currency": "PLN",
        "additional_services": [],
        "carrier": {
          "id": "inpost_courier",
          "name": "InPost Kurier",
          "description": "InPost Express - Przesyłki kurierskie"
        },
        "key": "allegro_email_invalid",
        "service": {
          "id": "inpost_courier_local_super_express",
          "name": "Kurier lokalny SuperExpress",
          "description": "Przesyłka kurierska lokalna super expresowa"
        },
        "unavailability_reasons": null
      },
      {
        "id": 477,
        "status": "available",
        "expires_at": "2020-03-13T10:53:00.941+01:00",
        "rate": null,
        "currency": "PLN",
        "additional_services": [],
        "carrier": {
          "id": "inpost_courier",
          "name": "InPost Kurier",
          "description": "InPost Express - Przesyłki kurierskie"
        },
        "service": {
          "id": "inpost_courier_local_express",
          "name": "Kurier lokalny Express",
          "description": "Przesyłka kurierska lokalna expresowa"
        },
        "unavailability_reasons": null
      },
      {
        "id": 476,
        "status": "available",
        "expires_at": "2020-03-13T10:53:00.344+01:00",
        "rate": null,
        "currency": "PLN",
        "additional_services": [],
        "carrier": {
          "id": "inpost_courier",
          "name": "InPost Kurier",
          "description": "InPost Express - Przesyłki kurierskie"
        },
        "service": {
          "id": "inpost_courier_local_standard",
          "name": "Kurier lokalny Standard",
          "description": "Przesyłka kurierska lokalna standardowa"
        },
        "unavailability_reasons": null
      },
      {
        "id": 475,
        "status": "available",
        "expires_at": "2020-03-13T10:52:59.408+01:00",
        "rate": null,
        "currency": "PLN",
        "additional_services": [],
        "carrier": {
          "id": "inpost_courier",
          "name": "InPost Kurier",
          "description": "InPost Express - Przesyłki kurierskie"
        },
        "service": {
          "id": "inpost_courier_express_1700",
          "name": "Kurier doręczenie 17:00",
          "description": "Przesyłka kurierska z doręczeniem do godziny 17:00 następnego dnia"
        },
        "unavailability_reasons": null
      },
      {
        "id": 474,
        "status": "available",
        "expires_at": "2020-03-13T10:52:59.054+01:00",
        "rate": null,
        "currency": "PLN",
        "additional_services": [],
        "carrier": {
          "id": "inpost_courier",
          "name": "InPost Kurier",
          "description": "InPost Express - Przesyłki kurierskie"
        },
        "service": {
          "id": "inpost_courier_express_1200",
          "name": "Kurier doręczenie 12:00",
          "description": "Przesyłka kurierska z doręczeniem do godziny 12:00 następnego dnia"
        },
        "unavailability_reasons": null
      },
      {
        "id": 473,
        "status": "available",
        "expires_at": "2020-03-13T10:52:57.679+01:00",
        "rate": null,
        "currency": "PLN",
        "additional_services": [],
        "carrier": {
          "id": "inpost_courier",
          "name": "InPost Kurier",
          "description": "InPost Express - Przesyłki kurierskie"
        },
        "service": {
          "id": "inpost_courier_express_1000",
          "name": "Kurier doręczenie 10:00",
          "description": "Przesyłka kurierska z doręczeniem do godziny 10:00 następnego dnia"
        },
        "unavailability_reasons": null
      },
      {
        "id": 472,
        "status": "unavailable",
        "expires_at": null,
        "rate": null,
        "currency": null,
        "additional_services": [],
        "carrier": {
          "id": "inpost_courier",
          "name": "InPost Kurier",
          "description": "InPost Express - Przesyłki kurierskie"
        },
        "service": {
          "id": "inpost_courier_allegro",
          "name": "Allegro Kurier24 InPost",
          "description": "Przesyłka kurierska Allegro Kurier24 InPost"
        },
        "unavailability_reasons": [
          {
            "key": "parcels_size_invalid",
            "message": "Parcel is too large or too heavy."
          },
          {
            "message": "allegro_email_invalid"
          }
        ]
      },
      {
        "id": 471,
        "status": "available",
        "expires_at": "2020-03-13T10:52:57.115+01:00",
        "rate": null,
        "currency": "PLN",
        "additional_services": [],
        "carrier": {
          "key": "allegro_email_invalid",
          "id": "inpost_courier",
          "name": "InPost Kurier",
          "description": "InPost Express - Przesyłki kurierskie"
        },
        "service": {
          "id": "inpost_courier_standard",
          "name": "Kurier standard",
          "description": "Przesyłka kurierska standardowa"
        },
        "unavailability_reasons": null
      },
      {
        "id": 470,
        "status": "unavailable",
        "expires_at": null,
        "rate": null,
        "currency": null,
        "additional_services": [],
        "carrier": {
          "id": "inpost_letter",
          "name": "InPost Listy",
          "description": "Inpost Letter - Przesyłki listowe"
        },
        "service": {
          "id": "inpost_letter_allegro",
          "name": "Allegro miniKurier24 InPost",
          "description": "Przesyłka listowa Allegro miniKurier24 InPost"
        },
        "unavailability_reasons": [
          {
            "key": "parcels_size_invalid",
            "message": "Parcel is too large or too heavy."
          },
          {
            "message": "allegro_email_invalid"
          }
        ]
      },
      {
        "id": 469,
        "status": "unavailable",
        "expires_at": null,
        "rate": null,
        "currency": null,
        "additional_services": [],
        "key": "allegro_email_invalid",
        "carrier": {
          "id": "inpost_locker",
          "name": "InPost Paczkomaty",
          "description": "InPost Paczkomaty - Przesyłki paczkomatowe"
        },
        "service": {
          "id": "inpost_locker_pass_thru",
          "name": "Podaj dalej",
          "description": "Przesyłka paczkomatowa Podaj Dalej"
        },
        "unavailability_reasons": [
          {
            "key": "dropoff_and_target_points_must_be_equal",
            "message": "Dropoff point and target point must be equal for selected service."
          }
        ]
      },
      {
        "id": 468,
        "status": "unavailable",
        "expires_at": null,
        "rate": null,
        "currency": null,
        "additional_services": [],
        "carrier": {
          "id": "inpost_locker",
          "name": "InPost Paczkomaty",
          "description": "InPost Paczkomaty - Przesyłki paczkomatowe"
        },
        "service": {
          "id": "inpost_locker_allegro",
          "name": "Allegro Paczkomaty24/7 InPost",
          "description": "Przesyłka paczkomatowa Allegro Paczkomaty24/7 InPost"
        },
        "unavailability_reasons": [
          {
            "key": "invalid_target_point_function",
            "message": "Invalid target point function."
          },
          {
            "message": "allegro_email_invalid"
          }
        ]
      },
      {
        "key": "allegro_email_invalid",
        "id": 467,
        "status": "unavailable",
        "expires_at": null,
        "rate": null,
        "currency": null,
        "additional_services": [],
        "carrier": {
          "id": "inpost_locker",
          "name": "InPost Paczkomaty",
          "description": "InPost Paczkomaty - Przesyłki paczkomatowe"
        },
        "service": {
          "id": "inpost_locker_standard",
          "name": "Paczkomatowa standardowa",
          "description": "Przesyłka paczkomatowa standardowa"
        },
        "unavailability_reasons": [
          {
            "target_point": "translation missing: keys.errors.attributes.target_point.invalid"
          }
        ]
      }
    ]
  }
}
options/{#tracking_webhook}
Request samples
curl -i -X OPTIONS \
  'https://stage-api-shipx-it.easypack24.net/{#tracking_webhook}'

UC/Points

Common use-cases for Points API

UC/Point list by `relative_post_code`

######################

TRY IT NOT ENABLED

The "try it" feature isn't enabled for this use case due to technical limit (feature not support fixed query parameters). Try this with Postman.

######################

Query parameters

?relative_post_code=20068&max_distance=2000

Use cases couldn't be tested in the right column.

Request
query Parameters
relative_post_code
string

Searches for points closest to the given postcode.

Example: relative_post_code=20068
max_distance
number <meters> <= 50000
Default: 10000

Searches for points in distance up to the given value from relative_point or relative_post_code.

Example: max_distance=2000
Responses
200

Success

get/v1/points{#filterByRelativePostCodeQuery}
Request samples
curl -i -X GET \
  'https://stage-api-shipx-it.easypack24.net/v1/points{?relative_post_code=20068&max_distance=2000#filterByRelativePostCodeQuery}'
Response samples
application/json
{
  • "count": 8,
  • "page": 1,
  • "per_page": 25,
  • "total_pages": 1,
  • "items": [
    ],
  • "meta": {}
}

UC/Shipments

Common use-cases for Shipments API

UC/Shipments Hub2Locker

Shipments Hub2Locker

Request
Security:
path Parameters
organization_id_H2L
required
number (organization_id)

Your organization_id provided with the API Token. Read more in the Authentication section.

Example: 23
Request Body schema: application/json

This requestBody contains specific data and information for a H2L shipment use-case.

required
object (receiver)
object (receiver)

If no data are provided, the data of the organization under which the shipment is being created will be used by default (only in case of single warehouse).

required
parcels_template (object) or Array of parcels_array (objects)
service
required
string (service)

For Hub2Locker shipments, this parameter should always be inpost_locker_standard

Enum: "inpost_locker_standard" "inpost_courier_c2c"
required
object (custom_attributes_H2L)

Additional shipment attributes.

reference
string (reference) [ 3 .. 100 ] characters

Additional shipment description that will be printed in the label (e.g. order number)

external_customer_id
string (external_customer_id)

ID of the broker generating shipments within a different organization for customer service purpose

Responses
200

Success

post/v1/organizations/{organization_id_H2L}/shipments
Request samples
application/json
{
  • "receiver": {