Obiekt przesyłki wykorzystywany jest do uzyskania dostępnych ofert, a jednocześnie reprezentuje ona fizyczną paczkę (lub paczki), która będzie przesłana pomiędzy określonymi adresami.
POST /v1/organizations/:organization_id/shipments
Uprawnienia
Aby utworzyć przesyłkę w ramach określonej organizacji, użytkownik musi być jej członkiem.
Parametry
Wszystkie poniższe parametry powinny być zawarte w obiekcie shipment
.
Parametr | Typ | Opis | Walidacja |
---|---|---|---|
receiver | ReceiverForm | Dane odbiorcy paczki. | Atrybut jest wymagany.
|
sender | SenderForm | Dane nadawcy paczki. | Atrybut nie jest wymagany.
|
parcels | Array[ParcelsSimpleForm] | Dane paczek zawartych w przesyłce. | Atrybut jest wymagany.
|
custom_attributes | CustomAttributesForm | Dodatkowe atrybuty przesyłki. | Atrybut nie jest wymagany.
|
cod | CodForm | Wartość pobrania. | Atrybut nie jest wymagany.
|
insurance | InsuranceForm | Kwota ubezpieczenia przesyłki. | Atrybut nie jest wymagany.
|
reference | String | Dodatkowy opis przesyłki, np. numer zamówienia. | Atrybut nie jest wymagany.
|
is_return | Bool | Określa przesyłkę jako zwrotną. | Atrybut nie jest wymagany.
|
additional_services | Array[String] | Usługi dodatkowe. Dostępne usługi dodatkowe: | Atrybut nie jest wymagany.
|
external_customer_id | String | Identyfikator broker'a generującego przesyłki w ramach innej organizacji | Atrybut nie jest wymagany. |
only_choice_of_offer | Boolean | Ustawienie parametru na | Atrybut nie jest wymagany.
|
mpk | String | Nazwa miejsca powstania kosztów. | Atrybut nie jest wymagany.
Miejsce powstania kosztów musi najpierw być dodane do organizacji, aby można je było przypisać do przesyłki. |
comments | String | Dowolny komentarz | Atrybut nie jest wymagany.
|
Uwaga! Klienci debetowi
Po utworzeniu przesyłki, nie zwracamy cen dla klientów debetowych.
rate
przyjmuje wartość null
Przykładowe zapytanie
POST /v1/organizations/123/shipments HTTP/1.1 Host: api-shipx-pl.easypack24.net Content-Type: application/json Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]... { "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." }
W odpowiedzi serwer zwróci status 201 wraz z obiektem nowo utworzonej przesyłki.
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." } }
Przykładowe zapytanie z wieloma paczkami (wielopaki można tworzyć tylko dla inpost_courier):
POST /v1/organizations/123/shipments HTTP/1.1 Host: api-shipx-pl.easypack24.net Content-Type: application/json Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]... { "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" } }
Uwaga! Działanie asynchroniczne.
Po utworzeniu przesyłki zostanie uruchomiony asynchroniczny proces przygotowywania ofert.
Aby otrzymać informację o zakończeniu przygotowywania ofert dla przesyłki, należy zdefiniować w konfiguracji organizacji adres url, pod który mają być wysyłane informacje dla zdarzenia offers_prepared
. Dzięki temu, aplikacja ShipX wyśle na podany adres następujące informacje:
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 } ] } }
Przygotowane oferty ważne są przez 5 minut. Po tym czasie oferty zmienią swój status na expired
i nie będzie możliwy ich zakup. Aby przygotować nowe oferty, należy wysłać żądanie edycji przesyłki nie podając żadnych danych.
Błędy, jakie mogą wystąpić podczas tworzenia przesyłki:
validation_failed
- przesyłane parametry są niepoprawne. Szczegóły zawarte w poludetails
,resource_not_found
- w przypadku gdy użytkownik próbuje utworzyć przesyłkę dla organizacji, która nie istnieje lub nie ma uprawnień do jej utworzenia,no_carriers
- w przypadku gdy organizacja nie ma podpisanej umowy z żadnym przewoźnikiem.