[1.3.0] API General Information

Production environment

 

Address of production environment https://api-shipx-pl.easypack24.net

Access generation

Download a guide explaining how to quickly generate access to the ShipX API on your own,  Instrukcja konfiguracji konta API.


Test environment


Test environment address: https://sandbox-api-shipx-pl.easypack24.net

Address of the Parcel Manager test environment: https://sandbox-manager.paczkomaty.pl/

Access generation

https://sandbox-manager.paczkomaty.pl/ > My Account > API tab.

To generate a Token and Organisation ID you need to complete all the details, including invoice details under My Account > Data. To create a parcel shipment you need funds on your account, you can top up your account virtually in the Payments tab.


 

Query collection and environment profiles

 

Below we share a sample collection and environment profiles for the Postman application. To run, download the files and import them.

 

Query collection

 

Production environment

 

Sandbox environment

 

 

Request headers

The following headers can be specified when executing a request

Header

Description

Header

Description

Authorization 

Authorization header, where all authorization data should be sent. Details can be found in the Authorization chapter.

X-User-Agent 

This header allows you to specify the client/platform name and/or other information related to it.

X-User-Agent-Version 

This header allows you to specify the client/platform number of the request. Its content does not affect the functioning of the API.

X-Request-ID 

This header allows you to specify the name of the request. It is useful for debugging bugs and problems that may occur during API integration. Its application does not impact the functioning of the API.

Accept-Language 

This header allows you to change the editing of errors. Available values:

  • keys (some_error_message)

  • en_GB (Some error message)

  • pl_PL (Przykładowy komunikat o błędzie)


 

Response header

In response, the server returns the following header:

Header

Description

Header

Description

X-Request-ID 

Request ID. It is useful for debugging bugs and problems that may occur during API integration.
If it is specified during the request, the API will not generate its own IID, and the one provided during the request will be returned to the response.


 

Authorization

All requests which are sent to the server requires passing a valid access token, which belongs to the owner of the organization.

The access token should be provided in the header Authorization.

The organization ID should be passed in Path Parameters:

1 GET /v1/organizations/:id

Request Example:

1 2 3 4 GET /v1/organizations/1 HTTP/1.1 Host: api-shipx-pl.easypack24.net Content-Type: application/json Authorization: Bearer W-TYM-MIEJSCU-NALEZY-UMIESCIC-TOKEN

 

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 HTTP/1.1 200 OK  Content-Type: application/json  {   "href": "https://api.shipx.pl.easypack24.net/v1/organizations/34",   "id": 34,   "owner_id": 1,   "tax_id": "3973902075",   "name": "Random org name39739020755741",   "created_at": "2016-10-04T10:36:49.631+02:00",   "updated_at": "2016-10-04T10:36:49.631+02:00",   "services": [     "inpost_locker_standard",     "inpost_courier_standard"   ],   "address": {     "id": 808,     "line1": null,     "line2": null,     "street": "Ulica jakaś39739020755741",     "building_number": "Budynek39739020755741",     "city": "Szczecin39739020755741",     "post_code": "22-100",     "country_code": "PL"   } }

 

Collections

Collection attributes

Attribute

Type

Description

Attribute

Type

Description

href 

String

Absolute URL address to the collection.

count

Integer

A total number of items in the collection.

page

Integer

The current collection results page.

per_page

Integer

A number of results (per page) returned to the response.

items

Array

Elements of the collection.

Collection example in JSON:

1 2 3 4 5 6 7 8 9 10 11 12 13 { "href": "https://api-pl-shipx.easypack24.net/v1/points", "count": 1024, "page": 10, "per_page": 100, "items": [ { "href": "https://api-shipx-pl.easypack24.net/v1/points/KRA010", "id": "KRA010", ... other resource's params ... } ] }

 

Paging

Collections support paging (unless stated otherwise in the resource-specific documentation).

Scrolling through the pages of the collection is done by passing query parameters (page) and/or (page_page) in the request. Request example:

1 2 3 GET /v1/points?page=10 HTTP/1.1 Host: api-shipx-pl.easypack24.net Content-Type: application/json

 

Errors

Errors example

1 2 3 4 5 6 7 8 9 HTTP/1.1 400 Bad Request Content-Type: application/json   { "status": 400, "error": "invalid_parameter", "description": "Passed unsupported value (value of the parameter here) to parameter (parameter name)", "details": null }

List of error keys that may occur:

Key

Description

Key

Description

resource_not_found

The resource you are looking for was not found.

access_forbidden

Access to the specified resource is denied.

invalid_parameter

An invalid value was passed for a parameter in the URI. Details are available under the description key of the error response.

validation_failed

Validation error. The data sent in the payload of the POST request is incorrect. Details of the error are in the response under the details key.

offer_expired

The offer cannot be purchased, because its validity has expired.

Error example

1 2 3 4 5 6 7 8 9 10 11 HTTP/1.1 400 Bad Request Content-Type: application/json   { "status": 400, "error": "validation_failed", "description": "Some of data sent in payload are invalid. Check details for more information.", "details": { "email": ["invalid"] } }

The details object contains a collection in which the keys correspond to the names of parameters sent in the payload of the request, while the values ​​are an array with keys specifying which validation errors occurred for a given parameter.

Possible validation errors:

Validation error

Description

Validation error

Description

required

The value for the specified parameter is required.

too_short

The number of characters is too small. Check the resource documentation for details.

too_long

The number of characters is too large. Check the resource documentation for details.

not_a_number

The entered value should be a number.

not_an_integer

The entered value should be an integer number.

invalid

The entered value is invalid. Check the resource documentation for details.