Versions Compared
Key
- This line was added.
- This line was removed.
- Formatting was changed.
Info |
---|
Warning! Resource 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 |
---|
Shipment creation in offer mode
In order to create a shipment within an organization the user has to be its member.
Info |
---|
Attention! Debit customers After creating a shipment we do not return prices for debit clients. The |
Info |
---|
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 the following attributes should be included in the shipment
object.
ParametrParameter | TypType | OpisDescription | WalidacjaValidation | DostępnyAvailability |
---|---|---|---|---|
| Receiver details | The attribute is required.
| PL, IT | |
| Sender details. | The attribute is optional.
| PL, IT | |
| Array[ParcelsSimpleForm] | Details of parcels in the shipment. |
| PL, IT |
| Additional shipment attributes, e.g.
| The attribute is optional.
| PL, IT | |
| Cash collection amount. | The attribute is optional.
| PL | |
| Shipment insurance amount. | The attribute is optional.
| PL | |
| String | Additional shipment description, e.g. order number. | The attribute is optional.
| PL, IT |
| Bool | Determines whether the shipment is a return shipment. | The attribute is optional.
| PL, IT |
| Array[String] | Additional services. Available additional services: | The attribute is optional.
| PL, IT |
| String | ID of the broker generating shipments within a different organization. | The attribute is optional. | PL, IT |
| Boolean | Setting the parameter to | The attribute is optional.
| PL, IT |
| String | Name of cost center. | The attribute is optional.
The cost center must first be added to the organization in order to assign it to the shipment. | PL, IT |
| String | Any comment | The attribute is optional.
| PL, IT |
Example request with one parcel:
Code Block | ||
---|---|---|
| ||
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 | ||
---|---|---|
| ||
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 | ||
---|---|---|
| ||
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):
|
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 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 | ||
---|---|---|
| ||
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 } ] } } |