Page tree
Skip to end of metadata
Go to start of metadata

Warning!

The resource is available only in the following countries: PL, IT

The heart of the Integrated Services Platform are shipments. The definition of shipments consists of:

  • sender and recipient data
  • shipment (one or more), which will be physically shipped 
  • selected service (optional added services)
  • other additional attributes dependant on user preference, eg.:
    • Insurance
    • Cash collection

To create a shipment ready for shipping, 3 steps are required:

  1. Creating the shipment, consisting of recipient and sender details and information about the shipment itself (purple figures on the diagram below)
  2. Downloading the information about the available services for the created shipment (blue figures on the diagram below),
  3. Purchasing a label by selecting a service available for the shipment from step 1 (green figure on the diagram below) 

Service prices may differ based on the shipment dimensions and parameters defined upon creation.

The list of all available services can be found in Shipment services and dimensions

Service availability depends on the carriers with which the organisation has signed contracts with.

For Clients whose agreement allows for a debit to be created in the InPost system (debit client), prices will not be returned in the JSON response to the request sent to the API.

On this page

 

Shipment creation diagram

Structure

Shipment resource has the following attributes:

Attribute

Type

Description

Availability

id

Integer

Read only. Shipment identifier in ShipX.

PL, IT

status

String

Read only. Current shipment status.

PL, IT

custom_attributes

CustomAttributes

Additional, optional shipment attributes.

PL, IT

parcels

Array[Parcel]

List of parcels within the shipment.

PL, IT

created_at

DateTime

Read only. Shipment creation date in ShipX.

PL, IT

created_by_id

Integer

If of the user that created the shipment, if logged in.

PL, IT

sender

Peer

Sender details.

PL, IT

receiver

Peer

Recipient details.

PL, IT

cod

MoneyData

Cash collection for the shipment.

PL

insurance

MoneyData

Shipment insurance.

PL

additional_services

Array[String]

Additional services selected when creating the shipment (different offers may contain different additional services).

Available additional services: sms, email, saturday. Shipment services and dimensions

PL, IT

reference

String

Additional shipment description, e.g. order or client ID

PL, IT

is_return

Bool

Determines whether the shipment is a return.

PL, IT

offers

Array[Offer]

List of available services with prices, which can be purchased for the shipment.

PL, IT

selected_offer

Offer

The service selected when buying the label.

PL, IT

transactions

Array[Transaction]

List of payment transactions related to the shipment.

PL, IT

tracking_number

String

Shipment tracking number (logistic system ID).

PL, IT

sending_method

String

Duplicate of custom_attributes.

PL, IT

external_customer_id 

String

ID of the broker generating the shipment within a different organisation.

PL, IT

Parcel object attributes:

Attribute

Type

Description

Availability

id

String

Required when creating a shipment with multiple parcels. Unique parcel ID within the shipment that allows for validation errors to be returned in connection to a specific parcel. ID is not persisted in the database and is not returned as an attribute of an already created shipment.

PL, IT

template

String

Predefined dimension and weight template name. The list of predefined dimension and weight templates can be found in  Shipment services and dimensions.

PL, IT

dimensions

Object

Shipment dimensions.

  • length

  • width

  • height

  • unit - unit of shipment dimensions measure. Currently only mm (milimeters)

Filled automatically when selecting a valid template.

PL, IT

weight

Object

Shipment weight

  • amount - weight,

  • unit - unit of shipment weight measure. Currently only kg (kilograms)

Filled automatically when selecting a valid template.

PL, IT

tracking_number

String

Shipment tracking number. Assigned when buying a selected offer.

PL, IT

is_non_standard

Bool

Set to true when the shipment is non-standard. Parameter available only for courier services.

Parcel handled only within the domestic courier services, in which one of its dimensions exceeds 120 cm, or the sum of the dimensions (length + width + height) exceeds 220 cm. Additionally parcels considered non-standard are: round, cylindrical or oval, irregular shaped and/or with portruding elements.
The option of non-standard parcels does not apply to log parcels.

PL, IT

Offer object attributes:

Attribute

Type

Description

Availability

id

Integer

Unique offer identifier in the context of the shipment.

PL, IT

service

Service

Offered service object.

PL, IT

carrier

Carrier

Carrier object.

PL, IT

additional_services

Array[String]

Additional services selected when creating the shipment - available within the offer.

PL, IT

status

String

Offer status. Available offer statuses: in_preparation, available, unavailable, selected, bought, expired  

PL, IT

expires_at 

DateTime

Date and time when the offer expires.

PL, IT

rate

Decimal

Service price.

PL, IT

currency

String

Currency of the service price.

PL, IT

unavailability_reasons

Array

Offer unavailability reasons.

PL, IT

Service object attributes:

Attribute

Type

Description

Availability

id

String

Service ID

PL, IT

name

String

Service name

PL, IT

description 

String

Service description

PL, IT

Carrier object attributes:

Attribute

Type

Description

Availability

id

String

Carrier ID

PL, IT

name 

String

Carrier name

PL, IT

description 

String

Carrier description

PL, IT

Transaction object attributes:

Attribute

Type

Description

Availability

id 

String

Transaction ID

PL, IT

status

String

Transaction status. Available statuses: initiated, success, failure

PL, IT

created_at

DateTime

Transaction creation date and time.

PL, IT

updated_at

DateTime

Last transaction modification date and time.

PL, IT

offer_id

Integer

ID of the offer connected to the transaction.

PL, IT

Peer object attributes:

Attribute

Type

Description

Availability

id 

String

Peer ID

PL, IT

name 

String

Peer name

PL, IT

company_name

String

Company name

PL, IT

first_name

String

First name

PL, IT

last_name

String

Last name

PL, IT

email

String

E-mail address

PL, IT

phone

String

Telephone number

PL, IT

address

Address

Address

PL, IT

Address: object attributes:

(warning) line1 and line2 attributes are still supported, however, usage of street and building number is recommended.

Attribute

Type

Description

Availability

id 

String

Address ID

PL, IT

line1

String

Address first line

PL, IT

line2

String

Address second line

PL, IT

street 

String

Street name

PL, IT

building_number 

String

Building number

PL, IT

city

String

City

PL, IT

post_code

String

Postal code

PL, IT

country_code

String

Country code

PL, IT

MoneyData object attributes:

Attribute

Type

Description

Availability

amount

Decimal

Amount

PL, IT

currency

String

Currency

PL, IT

CustomAttributes object attributes:

Attribute

Type

Description

Availability

target_point

String

Target point name to which the shipment is to be delivered to, from which the recipient will collect it from. e.g. parcel locker name.

Only locker shipments.

PL, IT

sending_method 

String

[1.23.0] Sending Method.

Required for Allegro shipments.

PL, IT

dropoff_point

String

Dropoff point name to which the sender will deliver the shipment, e.g. parcel locker name.

Required for the following sending methods: pok, courier_pok, parcel_locker.

PL, IT

allegro_transaction_id

String

Transaction number of the Allegro after-sale form in which the buyer has chosen the Allegro Paczkomaty InPost delivery method. The provision of this parameter will require provision of the allegro_user_id  parameter.

PL

allegro_user_id

String

Allegro user number within the transaction specified by the allegro_user_id  parameter, which is the seller. The provision of this parameter will require provision of the allegro_transaction_id parameter.

PL

dispatch_order_id 

Integer

Dispatch order id.

Read-only attribute, present when the shipment has a defined dispatch order.

PL

Shipment resource example in JSON format (parcel locker shipment). 

{
	"href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments/1234567890",
	"id": "1234567890",
	"status": "offers_prepared",
	"parcels": [
		{
			"id": "small package",
			"template": "small",
			"dimensions": {
				"length": "80",
				"width": "360",
				"height": "640",
				"unit": "mm"
			},
			"weight": {
				"amount": "25",
				"unit": "kg"
			},
			"tracking_number": null,
			"is_non_standard": false
		}
	],
	"custom_attributes": {
		"target_point": "KRA010",
		"dropoff_point": null,
		"sending_method": "parcel_locker",
		"dispatch_order_id": 1
	},
	"sender": {
		"id": "123",
		"name": "Nazwa",
		"company_name": "InPost S.A.",
		"first_name": "Jan",
		"last_name": "Nowak",
		"email": "sender@email.com",
		"phone": "888000000",
		"address": {
			"id": "123",
			"street": "Malborska",
			"building_number": "130",
			"city": "Kraków",
			"post_code": "30-624",
			"country_code": "PL"
		}
	},
	"receiver": {
		"id": "123",
		"name": "Nazwa",
		"company_name": null,
		"first_name": null,
		"last_name": null,
		"email": "sender@email.com",
		"phone": "888000000",
		"address": null
	},
	"created_at": "2015-09-06T19:21:00.000+02:00",
	"cod": {
		"amount": 12.50,
		"currency": "PLN"
	},
	"insurance": {
		"amount": 25,
		"currency": "PLN"
	},
	"additional_services": [],
	"reference": "Order No. 12345",
	"is_return": false,
	"tracking_number": null,
	"created_by_id": 3,
	"offers": [
		{
			"id": 1278,
			"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."
			},
			"status": "available",
			"expires_at": "2015-09-06T19:21:00.000+02:00",
			"rate": 2.02,
			"currency": "PLN",
			"unavailability_reasons": null
		}
	],
	"selected_offer": null,
	"transactions": [],
	"sending_method": "parcel_locker",
	"external_customer_id": "8877xxx",
}



Authentication

Access to the resource requires a valid access tokenu.



Shipment List

Shipment List within the organisation.

(info) To retrieve the shipment list for a given organisation the user has to be its member.

GET /v1/organizations/:organization_id/shipments

Example request

curl -X GET https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments -H 'Authorization: Bearer token' -H 'Content-Type: application/json'

Response

HTTP/1.1 200 OK 
Content-Type: application/json  
{ 
"href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments", 
  "count": 15, 
  "per_page": 30, 
  "page": 1, 
  "items": [{
    "href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments/1234567890",
    "id": "1234567890",
    "status": "offers_prepared",
    "parcels": [
        {
            "id": "small package",
            "template": "small",
            "dimensions": {
                "length": "80",
                "width": "360",
                "height": "640",
                "unit": "mm"
            },
            "weight": {
                "amount": "25",
                "unit": "kg"
            },
            "tracking_number": null,
            "is_non_standard": false
        }
    ],
    "custom_attributes": {
        "target_point": "KRA010",
        "dropoff_point": null,
        "sending_method": "parcel_locker",
        "dispatch_order_id": 1
    },
    "sender": {
        "id": "123",
        "name": "Nazwa",
        "company_name": "InPost S.A.",
        "first_name": "Jan",
        "last_name": "Nowak",
        "email": "sender@email.com",
        "phone": "888000000",
        "address": {
            "id": "123",
            "street": "Malborska",
            "building_number": "130",
            "city": "Kraków",
            "post_code": "30-624",
            "country_code": "PL"
        }
    },
    "receiver": {
        "id": "123",
        "name": "Nazwa",
        "company_name": null,
        "first_name": null,
        "last_name": null,
        "email": "sender@email.com",
        "phone": "888000000",
        "address": null
    },
    "created_at": "2015-09-06T19:21:00.000+02:00",
    "cod": {
        "amount": 12.50,
        "currency": "PLN"
    },
    "insurance": {
        "amount": 25,
        "currency": "PLN"
    },
    "additional_services": [],
    "reference": "Order No. 12345",
    "is_return": false,
    "tracking_number": null,
    "created_by_id": 3,
    "offers": [
        {
            "id": 1278,
            "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."
            },
            "status": "available",
            "expires_at": "2015-09-06T19:21:00.000+02:00",
            "rate": 2.02,
            "currency": "PLN",
            "unavailability_reasons": null
        }
    ],
    "selected_offer": null,
    "transactions": [],
    "sending_method": "parcel_locker",
    "external_customer_id": "8877xxx",
  }]
}

Error information

Errors that may occur when retrieving the list of shipments

  • resource_not_found - Organisation for which the shipments list was requested either doesn't exist or the user has no access to it.



  • No labels