Versions Compared

Old Version 3

changes.mady.by.user Michał Machowski

Saved on

compared with

New Version Current

changes.mady.by.user Michał Machowski

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
bgColor#f0f0f0titleBGColor#f0f0f0title


title
Info

Warning!

Resource is available only in the following countries: PL, IT

Panel

is available only in the following countries: PL, IT

The shipment object is used to obtain available offers, and at the same time it represents the physical pack (or parcels) which will be sent between the stated addresses.

On this page

Table of Contents
minLevel2
 

Authentication

Access to the resource requires a valid access token.


Shipment creation in offer mode

(info)

In order to create a shipment within an

organisation Uwaga! Klienci debetowi

organization the user has to be its member.

Info
title

Attention! Debit customers

After creating a shipment we do not return prices for debit clients.

The rate attribute is 

The rate attribute is null


Info
titleUwaga! Działanie asynchroniczne.
After creating a shipment an asynchronouss offer preparation process will be started

Attention! Asynchronous operation

After creation of the shipment, the asynchronous process of preparing offers, manifesting and buying the offer will be triggered.


Code Block
POST /v1/organizations/:organization_id/shipments

Parameters

All

of

the following attributes should be included in

the  

the  shipment object.

Parametr

Typ

Opis

Walidacja

Dostępny

receiver

Receiver

ReceiverForm

Receiver details

The attribute is required.

  • In case of a courier service

oofer

  • offer (inpost_courier_c2c

 included

  •  included), at

least 

  • least receiver.company_name

 and

  •  and/

or 

  • or receiver.first_name

 and 

  •  and receiver.last_name

 and address  object

  •  and address  object should be provided

  • In case of parcel locker service

offer 

  • offer receiver.phone_number

 and 

  •  and receiver.email  should be provided

  • Providing all

of

  • the data will allow both types of offers to be presented

  • In case of is_return

=

  • = true,

Attribute 

  • Attribute receiver

 is

  •  is not required

PL, IT

sender

Sender

SenderForm

Sender details.

The attribute is optional.

  • If no data is provided the

organisation

  • organization data for which the shipment is created will be used by default

PL, IT

parcels

Array[

ParcelsSimple

ParcelsSimpleForm]

Details of parcels in the shipment.

  • The attribute is required.

    • Minimum length - 1, maximum length - 1000

PL, IT

custom_attributes

CustomAttributes

CustomAttributesForm

Additional shipment attributes, e.g.

"custom_attributes": {
"target_point": "KRA010"
}

The attribute is optional.

  • The list of available custom attributes has been described in Shipment.

  • Specifying a target point is required in case of a parcel locker service.

PL, IT

cod

Cod

CodForm

Cash collection amount.

The attribute is optional.

  • Attribute validation and requirement is defined at the time of providing a service.

PL

insurance

Insurance

InsuranceForm

Shipment insurance amount.

The attribute is optional.

  • Attribute validation and requirement is defined at the time of providing a service.

PL

reference

String

Additional shipment description, e.g. order number.

The attribute is optional.

  • Minimum length - 3, maximum length - 100, can be empty.

PL, IT

is_return

Bool

Determines whether the shipment is a return shipment.

The attribute is optional.

  • Available values (true, false)

  • Can be empty.

if 

  • If true, marks the shipment as a return shipment. In this case the recipient and sender details will be swapped automatically.

PL, IT

additional_services

Array[String]

Additional services.

Available additional services: sms, email, saturday.

[1.23.0] Shipment sizes and services

and dimensions.

The attribute is optional.

  • Attribute validated once value is provided.

  • When

the 

  • the additional_services

  attribute

  •   attribute is provided, the system checks

the 

  • the service

  attribute

  •   attribute provision, if

the 

  • the service

  attribute

  •   attribute is not provided or

the 

  • the additional_services

  attribute

  •   attribute does not fit in the scope of

the 

  • the service  provided, the user will get an error.

PL, IT

external_customer_id 

String

ID of the broker generating shipments within a different organization.

The attribute is optional.

PL, IT

only_choice_of_offer

Boolean

Setting the parameter

to 

to true

 results

 results in the offer being selected for the given service but not being paid for. The shipment has

to be paid for before the offer expiry.  (Shipment buy offer)

to be paid for before the offer expiry.  [1.23.0] Paying for Shipment. This parameter can also be set for each individual consignment (in this case the parameter set in the consignment has a higher priority).

The attribute is optional.

  • Default false

PL, IT

mpk

String

Name of cost center.

The attribute is optional.

maximum

  • Maximum length - 255

if

  • If the attribute is specified, we verify whether it belongs to the organization which the request is made from

can

  • Can be empty

The cost center must first be added to the organization in order to assign it to the shipment.

PL, IT

comments

String

Any comment

The attribute is optional.

maxiumum

  • Maximum length - 100

can

  • Can be empty

PL, IT

Example request with one parcel:

Code Block
languagejson
curl -X POST https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments -H 'Authorization: Bearer token' -H 'Content-Type: application/json' -d '{
    "mpk":"miejsce_powstania_kosztow",
	"comments": "dowolny komentarz",
    "external_customer_id": "8877xxx",
	"receiver": {
		"first_name": "Jan",
        "last_name": "Kowalski",
		"name": "Nazwa",
		"email": "receiver@example.com",
		"phone": "888000000",
		"address": {
            "id": "123",
            "street": "Malborska",
            "building_number": "130",
            "city": "Kraków",
            "post_code": "30-624",
            "country_code": "PL"
        }
	},
	"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"
	},
	"insurance": {
		"amount": 25,
		"currency": "PLN"
	},
	"cod": {
		"amount": 12.50,
		"currency": "PLN"
	},
	"additional_services": ["email", "sms"],
	"mpk": "Nazwa miejsca powstania kosztów."
}'

Response

Code Block
languagejson
HTTP/1.1 201 CREATED
Content-Type: application/json
 {
	"href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments/1234567890",
	"id": "1234567890",
	"status": "created",
	"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
		}
	],
	"external_customer_id": "8877xxx",
	"mpk": {
       "id": 1,
       "name": "miejsce_powstania_kosztow"
    },
	"comments": "dowolny komentarz",
 	"custom_attributes": {
		"target_point": "KRA010",
		"open_code": null,
		"dropoff_point": null,
		"sending_method": "parcel_locker"
	},
	"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": "1234",
		"name": "Nazwa",
		"company_name": null,
		"first_name": "Jan",
		"last_name": "Kowalski",
		"email": "sender@email.com",
		"phone": "888000000",
		"address": null
	},
	"created_at": "2015-09-06T19:21:00.000+02:00",
    "created_by_id": 3,
    "cod_amount": {
		"amount": 12.50,
		"currency": "PLN"
	},
	"insurance": {
		"amount": 25,
		"currency": "PLN"
	},
	"additional_services": ["email", "sms"],
	"reference": "Order No. 12345",
	"is_return": false,
	"tracking_number": null,
	"offers": [],
	"selected_offer": null,
	"transactions": [],
	"mpk": {
        "id": 1,
        "name": "Nazwa miejsca powstania kosztów."
    }
}

Example request for multiple parcels in a single shipment (available only for inpost_courier):

Code Block
languagejson
curl -X POST https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments -H 'Authorization: Bearer token' -H 'Content-Type: application/json' -d '{
	"receiver": {
		"first_name": "Jan",
        "last_name": "Kowalski",
		"email": "receiver@example.com",
		"name": "Nazwa",
		"phone": "888000000",
		"address": {
            "id": "123",
            "street": "Malborska",
            "building_number": "130",
            "city": "Kraków",
            "post_code": "30-624",
            "country_code": "PL"
        }
	},
	"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
		},
		{
			"id": "big package",
			"template": "large",
			"dimensions": {
				"length": "160",
				"width": "720",
				"height": "640",
				"unit": "mm"
			},
			"weight": {
				"amount": "50",
				"unit": "kg"
			},
			"tracking_number": null,
			"is_non_standard": false
		}
	],
	"custom_attributes": {
		"target_point": "KRA010"
	},
	"insurance": {
		"amount": 25,
		"currency": "PLN"
	},
	"cod": {
		"amount": 12.50,
		"currency": "PLN"
	}
}'

Warning

Error information

Errors that may appear when creating a shipment (the following errors are returned as a response to the shipment creation request, not via webhooks):

  • validation_failed - request parameters are incorrect. Details are available in

the 

  • the details,

  • resource_not_found -

 Organisation

  •  Organization for which the shipments creation was requested either doesn't exist or the user has no access to it.

  • no_carriers - In case the

organisation

  • organization has no carriers contracted,

  • carrier_unavailable - In case the

organisation

  • organization has no carriers contracted providing the

requested 

  • requested service

Asynchronous offer preparation

After creating a shipment an asynchronous offer preparation process starts. The offer expires after 5 minutes and they won't be buyable anymore. To generate a new offer, an empty edit request to the shipment should be made.

To receive information about the offers preparation process finishing, a url address should be added to the

organisation

organization configuration to receive the offers_prepared  events. Thanks to that ShipX will send the following information to the url on offers preparation process finishing:

Code Block
languagejson
POST http://{{adres_podany_w_konfiguracji}}
Content-Type: application/json
 {
	"event_ts": "2015-12-09 14:55:06 +0100",
	"event": "offers_prepared",
	"organization_id": 1,
	"payload": {
		"shipment_id": 460,
		"offers": [
    		{
      			"id": 1281,
      			"carrier": {
					"id": "inpost_courier",
        			"name": "InPost Express",
					"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."
      			},
				"additional_services": ["email", "sms"],
      			"status": "available",
				"expires_at": "2016-06-24T12:39:43.734+02:00",
      			"rate": 17,
      			"currency": "PLN",
      			"unavailability_reasons": null
    		},
    		{
      			"id": 1280,
      			"carrier": {
        			"id": "inpost_courier",
        			"name": "InPost Express",
					"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."
      			},
				"additional_services": ["email", "sms"],
      			"status": "available",
				"expires_at": "2016-06-24T12:39:43.734+02:00",
      			"rate": 17,
      			"currency": "PLN",
      			"unavailability_reasons": null
    		},
    		{
      			"id": 1279,
      			"carrier": {
        				"id": "inpost_courier",
        				"name": "InPost Express",
						"description": "InPost Express - Przesyłki kurierskie."
      			},
      			"service": {
        				"id": "inpost_courier_standard",
						"name": "Kurier Standard",
						"description": "Przesyłka kurierska standardowa."
      			},
				"additional_services": ["email", "sms"],
      			"status": "available",
				"expires_at": "2016-06-24T12:39:43.734+02:00",
      			"rate": 17,
      			"currency": "PLN",
      			"unavailability_reasons": null
    		},
    		{
      			"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."
      			},
				// Oferta paczkomatowa nie zawiera wybranych usług dodatkowych, ponieważ są one zawarte w usłudze podstawowej (email, sms) albo są niedostępne (saturday)
				"additional_services": [],
      			"status": "available",
				"expires_at": "2016-06-24T12:39:43.734+02:00",
      			"rate": 2.02,
      			"currency": "PLN",
      			"unavailability_reasons": null
    		}
		]
	}
}