Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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:

  1. 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),
  2. Collecting information about available services for the earlier created shipment object (blue figures in the following diagram),
  3. 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
titleOn this page

Table of Contents
maxLevel2
minLevel2
 


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

AtrybutTypeDescription
hrefstringRead-only. URL address to the resource.
idintegerRead-only. Shipment ID in Ship X platform.
statusStringRead-only. Current shipment status.
custom_attributesCustomAttributesAdditional, optional attributes for the shipment.
parcelsArray[Parcel]List of parcels within the shipment.
created_atdatetimeRead-only. Date of creating the shipment in the Ship X system.
created_by_idintegerID of the user who created the shipment if the user is logged in.
senderPeerSender's data.
receiverPeerRecipient's data.
codMoneyDataCash collection for the shipment.
insuranceMoneyDataShipment insurance.
additional_servicesArray[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

referenceStringAdditional description for the shipment, e.g. order number or client ID.
is_returnBoolDetermines whether the shipment is a return shipment.
offersObject

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

Struktura obiektu Offer:


AttributeTypeDescription
idIntegerUnique ID of the service offered within the shipment
serviceObjectOffered service object.
carrierObjectCarrier object.
additional_servicesArray[String]Additional services selected when creating the shipment - available in the given offer.
statusStringOffer status
expires_at
DatetimeDate and time until when it is possible to purchase the offer.
rateDecimalPrice for the service.
currencyStringCurrency in which the price for the service is provided.
unavailability_reasonsArrayReasons for unavailability for the given offer.

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

service object structure:

AttributeTypeDescription
idStringService ID
nameStringService name
descriptionStringService description

carrier object structure:

AttributeTypeDescription
idStringCarrier ID
nameStringCarrier name
descriptionStringCarrier description


selected_offerObjectThe service selected when buying a label for the shipment.
transactionsArray[Transaction]

List of payment transactions related to the given shipment.


Transaction object structure:

AttributeTypeDescription
idStringTransaction ID
statusStringTransaction status. Possible statuses:: initiated, success, failure
created_atDateTimeDate of creating the transaction..
updated_atDateTimeDate of the last modification of the transaction.
offer_idIntegerID of the offer the transaction is concerned with.


tracking_numberStringTracking number of the shipment (ID at the logistic system level).
sending_methodStringDuplication of the field from custom_attributes.
external_customer_id
StringID of the broker generating shipments within a different organization.

Parcel object attributes::

AtrybutTypeDescription
idStringRequired 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.
templateString

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

dimensionsObject

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.

weightObject

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_numberStringShipment number. Assigned when buying the selected offer.
is_non_standardBool

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:

AttributeTypeDescription
idStringPeer object ID
nameStringName
company_nameStringCompany name
first_nameStringFirst name
last_nameStringLast name
emailStringE-mail address
phoneStringTelephone number
addressObjectAddress

Address object attributes::

AtrybutTypeDescription
idStringAddress object ID
line1StringFirst address line
line2StringSecond address line
streetStringStreet name
building_numberStringHouse number
cityStringCity
post_codeStringPostal code
country_codeStringCountry code

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


MoneyData object attributes:

AttributeTypeDescription
amountdecimalAmount
currencystringCurrency

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

AttributeTypDescription
target_pointstring

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_methodstring

Sending method.

Required for Allegro shipments.

dropoff_pointstring

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_idstringTransaction 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_idstringAllegro 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_idinteger

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.