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, np.
| 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.
|
service | String | Wybrana przez klienta usługa. Dostępne wartości patrz API X Rozmiary i usługi dla przesyłek | Atrybut 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 true powoduje że oferta zostanie wybrana dla podanego serwisu, ale nie zostanie automatycznie opłacona. Taka przesyłkę trzeba opłacić przed końcem wygaśnięcia oferty wykonując operacje (Opłacanie przesyłki) | 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 zapytania
Przykładowe zapytanie dla przesyłki kurierskiej
POST /v1/organizations/123/shipments HTTP/1.1 Host: https://api-shipx-pl.easypack24.net Content-Type: application/json Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]... { "receiver": { "name": "Name", "company_name": "Company name", "first_name": "Jan", "last_name": "Kowalski", "email": "receiver@example.com", "phone": "888000000", "address": { "street": "Cybernetyki", "building_number": "10", "city": "Warszawa", "post_code": "02-677", "country_code": "PL" } }, "parcels": [ { "id": "small package", "dimensions": { "length": "80", "width": "360", "height": "640", "unit": "mm" }, "weight": { "amount": "25", "unit": "kg" }, "is_non_standard": false } ], "insurance": { "amount": 25, "currency": "PLN" }, "cod": { "amount": 12.50, "currency": "PLN" }, "service": "inpost_courier_standard", "additional_services": ["email", "sms"], "reference": "Test", "comments": "dowolny komentarz", "external_customer_id": "8877xxx", "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/shipments/1234567890", "id": 1234567890, "status": "created", "tracking_number": null, "service": "inpost_courier_standard", "reference": "Test", "is_return": false, "application_id": 123, "created_by_id": null, "external_customer_id": "8877xxx", "sending_method": null, "mpk": { "id": 1, "name": "Nazwa miejsca powstania kosztów" }, "comments": "dowolny komentarz", "additional_services": [ "email", "sms" ], "custom_attributes": {}, "cod": { "amount": 12.5, "currency": "PLN" }, "insurance": { "amount": 25.0, "currency": "PLN" }, "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", "line1": null, "line2": null "city": "Kraków", "post_code": "30-624", "country_code": "PL" } }, "receiver": { "id": 123, "name": "Name", "company_name": "Company name", "first_name": "Jan", "last_name": "Kowalski", "email": "receiver@example.com", "phone": "888000000", "address": { "id": 123, "street": "Malborska", "building_number": "130", "line1": null, "line2": null, "city": "Kraków", "post_code": "30-624", "country_code": "PL" } }, "selected_offer": null, "offers": [], "transactions": [], "parcels": [ { "id": 123, "tracking_number": null, "is_non_standard": false, "template": null, "dimensions": { "length": 80.0, "width": 360.0, "height": 640.0, "unit": "mm" }, "weight": { "amount": 25.0, "unit": "kg" } } ], "end_of_week_collection": false, "created_at": "2020-02-23T18:07:08.967+01:00", "updated_at": "2020-02-23T18:07:08.967+01:00" }
Przykładowe zapytanie z wieloma paczkami (wielopaki można tworzyć tylko dla inpost_courier):
POST /v1/organizations/123/shipments HTTP/1.1 Host: https://api-shipx-pl.easypack24.net Content-Type: application/json Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]... { "receiver": { "name": "Name", "company_name": "Company name", "first_name": "Jan", "last_name": "Kowalski", "email": "receiver@example.com", "phone": "888000000", "address": { "street": "Cybernetyki", "building_number": "10", "city": "Warszawa", "post_code": "02-677", "country_code": "PL" } }, "parcels": [ { "id": "small package", "dimensions": { "length": "80", "width": "360", "height": "640", "unit": "mm" }, "weight": { "amount": "25", "unit": "kg" }, "is_non_standard": true }, { "id": "big package", "dimensions": { "length": "80", "width": "360", "height": "640", "unit": "mm" }, "weight": { "amount": "25", "unit": "kg" }, "is_non_standard": true } ], "insurance": { "amount": 25, "currency": "PLN" }, "cod": { "amount": 12.50, "currency": "PLN" }, "service": "inpost_courier_standard", "additional_services": ["email", "sms"], "reference": "Test", "comments": "dowolny komentarz", "external_customer_id": "8877xxx", "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/shipments/1234567890", "id": 1234567890, "status": "created", "tracking_number": null, "service": "inpost_courier_standard", "reference": "Test", "is_return": false, "application_id": 123, "created_by_id": null, "external_customer_id": "8877xxx", "sending_method": null, "mpk": { "id": 1, "name": "Nazwa miejsca powstania kosztów" }, "comments": "dowolny komentarz", "additional_services": [ "email", "sms" ], "custom_attributes": {}, "cod": { "amount": 12.5, "currency": "PLN" }, "insurance": { "amount": 25.0, "currency": "PLN" }, "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", "line1": null, "line2": null "city": "Kraków", "post_code": "30-624", "country_code": "PL" } }, "receiver": { "id": 123, "name": "Name", "company_name": "Company name", "first_name": "Jan", "last_name": "Kowalski", "email": "receiver@example.com", "phone": "888000000", "address": { "id": 509576837, "street": "Cybernetyki", "building_number": "10", "line1": null, "line2": null, "city": "Warszawa", "post_code": "02-677", "country_code": "PL" } }, "selected_offer": null, "offers": [], "transactions": [], "parcels": [ { "id": 123, "tracking_number": null, "is_non_standard": true, "template": null, "dimensions": { "length": 80.0, "width": 360.0, "height": 640.0, "unit": "mm" }, "weight": { "amount": 25.0, "unit": "kg" } }, { "id": 123, "tracking_number": null, "is_non_standard": true, "template": null, "dimensions": { "length": 80.0, "width": 360.0, "height": 640.0, "unit": "mm" }, "weight": { "amount": 25.0, "unit": "kg" } } ], "end_of_week_collection": false, "created_at": "2020-02-23T18:22:57.378+01:00", "updated_at": "2020-02-23T18:22:57.378+01:00" }
Przykładowe zapytanie tworzenia przesyłki paczkomatowej standardowej.
POST /v1/organizations/123/shipments HTTP/1.1 Host: https://api-shipx-pl.easypack24.net Content-Type: application/json Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]... { "receiver": { "name": "Name", "company_name": "Company name", "first_name": "Jan", "last_name": "Kowalski", "email": "test@inpost.pl", "phone": "111222333" }, "parcels": { "template": "small" }, "insurance": { "amount": 25, "currency": "PLN" }, "cod": { "amount": 12.50, "currency": "PLN" }, "custom_attributes": { "sending_method": "dispatch_order", "target_point": "KRA012" }, "service": "inpost_locker_standard", "reference": "Test", "external_customer_id": "8877xxx" }
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/shipments/1234567890", "id": 1234567890, "status": "created", "tracking_number": null, "service": "inpost_locker_standard", "reference": "Test", "is_return": false, "application_id": 123, "created_by_id": null, "external_customer_id": "8877xxx", "sending_method": "dispatch_order", "mpk": null, "comments": null, "additional_services": [], "custom_attributes": { "sending_method": "dispatch_order", "target_point": "KRA012" }, "cod": { "amount": 12.5, "currency": "PLN" }, "insurance": { "amount": 25.0, "currency": "PLN" }, "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", "line1": null, "line2": null "city": "Kraków", "post_code": "30-624", "country_code": "PL" } }, "receiver": { "id": 123, "name": "Name", "company_name": "Company name", "first_name": "Jan", "last_name": "Kowalski", "email": "test@inpost.pl", "phone": "111222333", "address": null }, "selected_offer": null, "offers": [], "transactions": [], "parcels": [ { "id": 123, "tracking_number": null, "is_non_standard": false, "template": "small", "dimensions": { "length": 380.0, "width": 640.0, "height": 80.0, "unit": "mm" }, "weight": { "amount": 25.0, "unit": "kg" } } ], "end_of_week_collection": false, "created_at": "2020-02-23T18:17:40.073+01:00", "updated_at": "2020-02-23T18:17:40.073+01:00" }
Przykładowe zapytanie dla przesyłki Allegro Paczkomaty24/7 InPost
POST /v1/organizations/123/shipments HTTP/1.1 Host: https://api-shipx-pl.easypack24.net Content-Type: application/json Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]... { "receiver": { "name": "Name", "company_name": "Company name", "first_name": "Jan", "last_name": "Kowalski", "email": "123abc+123abc@user.allegrogroup.pl", "phone": "111222333" }, "parcels": { "template": "small" }, "custom_attributes": { "target_point": "KRA012", "sending_method": "dispatch_order" }, "service": "inpost_locker_allegro" }
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/shipments/1234567890", "id": 1234567890, "status": "created", "tracking_number": null, "service": "inpost_locker_allegro", "reference": null, "is_return": false, "application_id": 123, "created_by_id": null, "external_customer_id": null, "sending_method": "dispatch_order", "mpk": null, "comments": null, "additional_services": [], "custom_attributes": { "sending_method": "dispatch_order", "target_point": "KRA012" }, "cod": { "amount": null, "currency": null }, "insurance": { "amount": 5000, "currency": "PLN" }, "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", "line1": null, "line2": null "city": "Kraków", "post_code": "30-624", "country_code": "PL" } }, "receiver": { "id": 123, "name": "Name", "company_name": "Company name", "first_name": "Jan", "last_name": "Kowalski", "email": "123abc+123abc@user.allegrogroup.pl", "phone": "111222333", "address": null }, "selected_offer": null, "offers": [], "transactions": [], "parcels": [ { "id": 123, "tracking_number": null, "is_non_standard": false, "template": "small", "dimensions": { "length": 380.0, "width": 640.0, "height": 80.0, "unit": "mm" }, "weight": { "amount": 10.0, "unit": "kg" } } ], "end_of_week_collection": false, "created_at": "2020-02-23T18:52:25.100+01:00", "updated_at": "2020-02-23T18:52:25.100+01:00" }
Przykładowe zapytanie dla przesyłki Allegro miniKurier24 InPost.
POST /v1/organizations/123/shipments HTTP/1.1 Host: https://api-shipx-pl.easypack24.net Content-Type: application/json Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]... { "receiver": { "name": "Name", "company_name": "Company name", "first_name": "Jan", "last_name": "Kowalski", "email": "123abc+123abc@user.allegrogroup.pl", "phone": "888000000", "address": { "street": "Cybernetyki", "building_number": "10", "city": "Warszawa", "post_code": "02-677", "country_code": "PL" } }, "parcels": { "template": "letter_a" }, "custom_attributes": { "sending_method": "dispatch_order" }, "service": "inpost_letter_allegro" }
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/shipments/1234567890", "id": 1234567890 "status": "created", "tracking_number": null, "service": "inpost_letter_allegro", "reference": null, "is_return": false, "application_id": 123, "created_by_id": null, "external_customer_id": null, "sending_method": "dispatch_order", "mpk": null, "comments": null, "additional_services": [], "custom_attributes": { "sending_method": "dispatch_order" }, "cod": { "amount": null, "currency": null }, "insurance": { "amount": 5000, "currency": "PLN" }, "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", "line1": null, "line2": null "city": "Kraków", "post_code": "30-624", "country_code": "PL" } }, "receiver": { "id": 123, "name": "Name", "company_name": "Company name", "first_name": "Jan", "last_name": "Kowalski", "email": "123abc+123abc@user.allegrogroup.pl", "phone": "888000000", "address": { "id": 123, "street": "Cybernetyki", "building_number": "10", "line1": null, "line2": null, "city": "Warszawa", "post_code": "02-677", "country_code": "PL" } }, "selected_offer": null, "offers": [], "transactions": [], "parcels": [ { "id": 123, "tracking_number": null, "is_non_standard": false, "template": "letter_a", "dimensions": { "length": 380.0, "width": 640.0, "height": 80.0, "unit": "mm" }, "weight": { "amount": 10.0, "unit": "kg" } } ], "end_of_week_collection": false, "created_at": "2020-02-23T19:24:51.120+01:00", "updated_at": "2020-02-23T19:24:51.120+01:00" }
Przykładowe zapytanie dla przesyłki Allegro Kurier24 InPost
POST /v1/organizations/123/shipments HTTP/1.1 Host: https://api-shipx-pl.easypack24.net Content-Type: application/json Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]... { "receiver": { "name": "Name", "company_name": "Company name", "first_name": "Jan", "last_name": "Kowalski", "email": "gtcc1rh559+4fe361dc5@user.allegrogroup.pl", "phone": "888000000", "address": { "street": "Cybernetyki", "building_number": "10", "city": "Warszawa", "post_code": "02-677", "country_code": "PL" } }, "parcels": { "dimensions": { "length": "10", "width": "10", "height": "10", "unit": "mm" }, "weight": { "amount": "10", "unit": "kg" } }, "cod": { "amount": 12.50, "currency": "PLN" }, "custom_attributes": { "sending_method": "dispatch_order" }, "service": "inpost_courier_allegro" }
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/shipments/1234567890", "id": 1234567890, "status": "created", "tracking_number": null, "service": "inpost_courier_allegro", "reference": null, "is_return": false, "application_id": 123, "created_by_id": null, "external_customer_id": null, "sending_method": "dispatch_order", "mpk": null, "comments": null, "additional_services": [], "custom_attributes": { "sending_method": "dispatch_order" }, "cod": { "amount": 12.5, "currency": "PLN" }, "insurance": { "amount": 5000, "currency": "PLN" }, "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", "line1": null, "line2": null "city": "Kraków", "post_code": "30-624", "country_code": "PL" } }, "receiver": { "id": 123, "name": "Name", "company_name": "Company name", "first_name": "Jan", "last_name": "Kowalski", "email": "123abc+123abc@user.allegrogroup.pl", "phone": "888000000", "address": { "id": 123, "street": "Cybernetyki", "building_number": "10", "line1": null, "line2": null, "city": "Warszawa", "post_code": "02-677", "country_code": "PL" } }, "selected_offer": null, "offers": [], "transactions": [], "parcels": [ { "id": 123, "tracking_number": null, "is_non_standard": false, "template": null, "dimensions": { "length": 10.0, "width": 10.0, "height": 10.0, "unit": "mm" }, "weight": { "amount": 10.0, "unit": "kg" } } ], "end_of_week_collection": false, "created_at": "2020-02-23T19:09:25.712+01:00", "updated_at": "2020-02-23T19:09:25.712+01:00" }
Uwaga! Działanie asynchroniczne.
Po utworzeniu przesyłki zostanie uruchomiony asynchroniczny proces przygotowywania ofert, manifestacji oraz kupienia oferty.
Aby otrzymać informację o zakończeniu procesu, należy zdefiniować w konfiguracji organizacji adres url (webhook), pod który mają być wysyłane informacje dla zdarzeń offers_prepared i/lub shipment_confirmed
. Dzięki temu, aplikacja ShipX wyśle na podany adres informacje.
Błędy, jakie mogą wystąpić podczas tworzenia przesyłki (poniższe błędy są wysyłane do aplikacji która wysłała żądanie, nie na webhook):
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,carrier_unavailable
- w przypadku gdy organizacja nie ma podpisanej umowy z przewoźnikiem świadczącym wybraną usługę wskazaną w atrybucieservice
Tworzenie rozmiaru przesyłki w trybie uproszczonym, na podtsawie przekazywanych parametrów
Na temat rozmiarów można przczytać w osobnym dokumencie
Aplikacja umożiwia wygenerowanie przesyłki z rozmiarem, bez podawania jego nazwy. Rozmiar generowany jest na podstawie przekazywanych parametrów,
poniżej został umieszczony przykład:
"parcels": { "dimensions": { "length": "120", "width": "34", "height": "81", "unit": "mm" }, "weight": { "amount": "20", "unit": "kg" } }
Znalezienie odpowiedniego rozmiaru przesyłki, bez podawania jego nazwy, uwarunkowane jest przekazaniem wszystkich parametrów obiektów dimensions
oraz weight
Poniższa tabela przedstawia warunki jakie należy spełnić, aby umożliwić wygenerowanie rozmiaru na podstawie przekazywanych parametrów.
Rozmiar przesyłki | Serwis | Parametr: Umowne przedziały i ich wartości |
---|---|---|
letter_a |
|
|
small |
|
|
medium |
|
|
large |
|
|
palette | inpost_courier_palette |
|
parcel | inpost_courier_standard inpost_courier_express_1700 |
|
parcel | pozostałe serwisy |
|