Page Comparison

List of shipments within the given organization:

The heart of the Integrated Services Platform are shipments. The definition of a shipment includes:

sender's and recipient's data
parcel (one or more) which will be physically sent
the chosen service (optionally additional services)
other additional attributes depending on the user's preferences, e.g.:
- Insurance
- Cash collection

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

Creating a shipment, consisting of providing the details of the sender, recipient as well as information about the pack (purple figures in the following diagram),
Collecting information about available services for the earlier created shipment object (blue figures in the following diagram),
Purchasing a label by indicating a given service, available for the shipment which has been created in step 1 (green figure in the following diagram))

Panel

bgColor	#efefef
title	On this page

Table of Contents

maxLevel	2
minLevel	2

Authentication

In order to gain access to the Shipment resource, it is necessary to specify the valid and right access token.

Shipment creation diagram

Prices for services may vary depending on pack dimensions and shipment parameters defined when it was created.

The list of all services can be found on the page Sizes and services for shipments

The availability of the services depends on the carriers the given organization has signed agreements 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.

Shipments resource is available for the Organization (with organization_id ID)

Code Block
https://api-shipx-pl.easypack24.net/v1/organizations/:organization_id/shipments

Attributes

Atrybut Type Description

href string Read-only. URL address to the resource.

id integer Read-only. Shipment ID in Ship X platform.

status String Read-only. Current shipment status.

custom_attributes CustomAttributes Additional, optional attributes for the shipment.

parcels Array[Parcel] List of parcels within the shipment.

created_at datetime Read-only. Date of creating the shipment in the Ship X system.

created_by_id integer ID of the user who created the shipment if the user is logged in.

sender Peer Sender's data.

receiver Peer Recipient's data.

cod MoneyData Cash collection for the shipment.

insurance MoneyData Shipment insurance.

additional_services

Array[String]

Additional services selected when creating the shipment (different offers may contain different additional services).
Available additional services: sms, email, saturday. Sizes and services for shipments

reference String Additional description for the shipment, e.g. order number or client ID.

is_return Bool Determines whether the shipment is a return shipment.

offers

Object

Lista dostępnych usług wraz z cenami, które możliwe są do nabycia w ramach tej przesyłki.

Struktura obiektu Offer:

Attribute	Type	Description
`id`	Integer	Unique ID of the service offered within the shipment
`service`	Object	Offered service object.
`carrier`	Object	Carrier object.
`additional_services`	Array[String]	Additional services selected when creating the shipment - available in the given offer.
`status`	String	Offer status
expires_at	Datetime	Date and time until when it is possible to purchase the offer.
`rate`	Decimal	Price for the service.
`currency`	String	Currency in which the price for the service is provided.
`unavailability_reasons`	Array	Reasons for unavailability for the given offer.

Possible offer statuses: in_preparation, available, unavailable, selected, bought, expired

service object structure:

Attribute	Type	Description
`id`	String	Service ID
`name`	String	Service name
description	String	Service description

carrier object structure:

Attribute	Type	Description
`id`	String	Carrier ID
`name`	String	Carrier name
description	String	Carrier description

selected_offer Object The service selected when buying a label for the shipment.

transactions

Array[Transaction]

List of payment transactions related to the given shipment.

Transaction object structure:

Attribute	Type	Description
id	String	Transaction ID
`status`	String	Transaction status. Possible statuses:: `initiated`, `success`, `failure`
`created_at`	DateTime	Date of creating the transaction..
`updated_at`	DateTime	Date of the last modification of the transaction.
`offer_id`	Integer	ID of the offer the transaction is concerned with.

tracking_number String Tracking number of the shipment (ID at the logistic system level).

sending_method String Duplication of the field from custom_attributes.

external_customer_id

String

ID of the broker generating shipments within a different organization.

Parcel object attributes::

Atrybut	Type	Description
`id`	String	Required when creating a shipment with many parcels. Unique ID of the given pack within the shipment, which allows for returning information to the user about validation errors assigned to the particular pack. The ID is not saved in the database and is not returned as an attribute of the pack being created.
`template`	String	Name of the predefined pack size and weight template. The list of predefined pack size and dimensions templates can be found on the page API X Rozmiary i usługi dla przesyłek.page Sizes and services for shipments
`dimensions`	Object	Parcel dimensions. `length` - length `width` - width `height` - height `unit` - the unit in which the dimensions are stated. At present only mm (millimeters) Filled automatically when choosing the right template.
`weight`	Object	Parcel weight `amount` - weight, `unit` - the unit in which the pack weight is stated. At present only kg (kilograms) Filled automatically when choosing the right template.
`tracking_number`	String	Shipment number. Assigned when buying the selected offer.
`is_non_standard`	Bool	Set to true if the shipment is non-standard. The parameter can be set only for courier shipments. 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. A non-standard parcel are also: round, cylindrical, or oval elements, with irregular shapes or/and with protruding elements. The option of non-standard parcels does not apply to log parcels.

Peer object attributes:

Attribute	Type	Description
id	String	Peer object ID
name	String	Name
`company_name`	String	Company name
`first_name`	String	First name
`last_name`	String	Last name
`email`	String	E-mail address
`phone`	String	Telephone number
`address`	Object	Address

Address object attributes::

Atrybut	Type	Description
id	String	Address object ID
line1	String	First address line
line2	String	Second address line
street	String	Street name
building_number	String	House number
`city`	String	City
`post_code`	String	Postal code
`country_code`	String	Country code

line1 and line2 attributes are still supported, however, it is recommended to use street and building_number.

MoneyData object attributes:

Attribute	Type	Description
`amount`	decimal	Amount
`currency`	string	Currency

Przygotowując przesyłkę, możliwe jest określenie dodatkowych parametrów w ramach obiektu custom_attributes:

Attribute	Typ	Description
`target_point`	string	Name of the destination point which the shipment is to be delivered to, which it will be collected from by the recipient, e.g. parcel locker name. Only parcel station shipments.
sending_method	string	Sending method. Required for Allegro shipments.
`dropoff_point`	string	Name of the shipping point which the sender will deliver the shipment to be sent to, e.g. parcel locker name. Required when specifying the sending method `pok`, `courier_pok`, `parcel_locker`.
`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.
`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.
dispatch_order_id	integer	Collection order number. Read-only attribute, present when the shipment has a defined collection order.

PSample resource in the JSON format (parcel station shipment).

Code Block

{
	"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",
}

List of the Organization's shipments

List of shipments within the given organization:

Code Block
GET /v1/organizations/:organization/shipments

Rights

To collect the list of shipments for a particular organization the user needs to be a member thereof.

Sample request

Code Block
GET /v1/organizations/12345/shipments HTTP/1.1 Host: api-shipx-pl.easypack24.net Content-Type: application/json Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]...

In reply to a correctly sent request, the server will return a response with HTTP 200 OK code:

Code Block

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/123",
			"id": 123,
			... other attribute omitted for brevity ....
		}
		... other items omitted for brevity ...
	]
}

Errors that may occur when collecting the list of shipments:

resource_not_found - the organization the user wants to collect the list of shipments for does not exist or the user has no access to it.

Versions Compared

Old Version 3

New Version 4

Key

Authentication

Shipment creation diagram

List of the Organization's shipments

Rights

Sample request