Zasób DispatchOrder
posiada następujące atrybuty:
Atrybut | Typ | Opis |
---|---|---|
href | string | URI do zasobu. |
id | string | ID Zlecenia Odbioru. Tylko do odczytu. |
status | string | Status zlecenia odbioru. |
created_at | Time | Czas utworzenia zlecenia odbioru. |
address | Object | Adres, z które ma nastąpić odbiór. |
shipments | Array[Shipment] | Tablica przesyłek, których dotyczy zlecenie odbioru. Obiekt
|
comment | string | Opcjonalny komentarz do zlecenia odbioru |
Przykład zasobu DispatchOrder
w formacie JSON:
{ "href": "https://api-shipx-pl.easypack24.net/v1/dispatch_orders/1", "id": 1, "status": "sent", "address": { "id": "123", "street": "Malborska", "building_number": "130", "post_code": "30-624", "city": "Kraków", "country_code": "PL", }, "shipments": [ { "href": "https://api-shipx-pl.easypack24.net/v1/shipments/8", "id": 8, "tracking_number": "622111081631876319900026" } ], "comments": [ { "24", "comment": "Some Test Comment", "created_at": "2018-02-14T11:37:07.852+01:00" } ], "created_at": "2018-02-14T11:37:07.843+01:00", "updated_at": "2018-02-14T11:37:08.340+01:00" }
Uwierzytelnianie
Dostęp do zasobu i jego metod wymaga podania aktualne i ważnego access token.
Uwaga! Klienci debetowi
Po utworzeniu zlecenia odbioru, nie zwracamy cen dla klientów debetowych.
price
przyjmuje wartość null
Tworzenie nowego zlecenia odbioru
POST /v1/organizations/:org_id/dispatch_orders
Parametry
Parametr | Typ | Opis | Walidacja |
---|---|---|---|
dispatch_point_id | integer | Identyfikator punktu odbioru, z którego przesyłka ma być odebrana (adres punkty odbioru stanie się adresem zlecenia odbioru). | Atrybut nie jest wymagany. Wymagalność pojawia się w momencie kiedy nie zostanie przekazany atrybut |
shipments | Array | Lista ID przesyłek, dla których ma zostać utworzone zlecenia odbioru. | Atrybut jest wymagany.
|
comment | string | Opcjonalny komentarz do zlecenia odbioru | Atrybut nie jest wymagany do tworzenia zlecenia odbioru. Wymagalność pojawia się z chwilą tworzenia komentarza do już istniejącego zlecenia odbioru. |
address | AddressForm | Adres zlecenia odbioru | Atrybut nie jest wymagany. Wymagalność pojawia się w momencie kiedy nie zostanie przekazany atrybut |
office_hours | string | Godziny funkcjonowania punktu | Atrybut nie jest wymagany. Określa godziny funkcjonowania punktu, jeżeli tworzymy zlecenie odbioru na adres. |
name | string | Nazwa punktu. Wykorzystywana do stworzenia dispatch_point. | Atrybut nie jest wymagany. |
phone | string | Kontakt telefoniczny. Wykorzystywany do stworzenia dispatch_point. | Atrybut nie jest wymagany. |
string | Kontakt mailowy. Wykorzystywany do stworzenia dispatch_point. | Atrybut nie jest wymagany. |
Przykład zapytania
POST /v1/organizations/:org_id/dispatch_orders HTTP/1.1 Host: api-shipx-pl.easypack24.net Content-Type: application/json Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]... { "shipments": ["1", "2"], "comment": "Dowolny komentarz do zlecenia odbioru", "name": "Przykładowa nazwa DispatchPoint", "phone": "505404202", "email": "sample@email.com", "address": { "street": "Malborska", "building_number": "130", "city": "Krakow", "post_code": "31-209", "country_code": "PL" } }
Odpowiedź
HTTP/1.1 201 Created Content-Type: application/json { "href": "https://api-shipx-pl.easypack24.net/v1/dispatch_orders/1", "id": 1, "status": "sent", "address": { "id": "123", "street": "Malborska", "building_number": "130", "post_code": "30-624", "city": "Kraków", "country_code": "PL", }, "shipments": [ { "href": "https://api-shipx-pl.easypack24.net/v1/shipments/8", "id": 8, "tracking_number": "622111081631876319900026" } ], "comments": [ { "id": 24, "comment": "Dowolny komentarz do zlecenia odbioru", "created_at": "2018-02-14T11:37:07.852+01:00" } ], "created_at": "2018-02-14T11:37:07.843+01:00", "updated_at": "2018-02-14T11:37:08.340+01:00" }
Zlecenie odbioru przesyłek na adres
Generowanie zlecenia na adres wymusza przekazanie adresu poprzez atrybut address
Obiekt Address
System generuje sumę kontrolną z przekazanych informacji, należy zwrócić uwagę aby adres był dokładny i bez błędów (tzw. literówek)
Na podstawie sumy kontrolnej system sprawdza, czy istnieje w bazie punkt odbioru o takim samym adresie, jeśli nie istnieje, automatycznie generowany jest nowy punkt odbioru (dotyczy wyłącznie przesyłek paczkomatowych).
Na nowo wygenerowany punkt odbioru (DipstachPoint
) realizowane jest zlecenie odbioru (DispatchOrder
).
Błędy
validation_failed
- przesłane dane są niepoprawne, np. podany punkt odbioru lub któraś z przesyłek ma niepoprawny statusinvalid_range
- podano nieprawidłowy zakres identyfikatora przesyłki, zakres nie mieści się w zakresie typu Integerdispatch_point_and_address_cannot_be_mixed
- Nie można jednocześnie nadawać zlecenia odbioru na adres oraz id punktu odbioru
Pobieranie informacji o zleceniu odbioru
GET /v1/dispatch_orders/:order_id
Przykład zapytania
GET /v1/dispatch_orders/1 HTTP/1.1 Host: api-shipx-pl.easypack24.net Content-Type: application/json Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]...
Odpowiedź
HTTP/1.1 200 OK Content-Type: application/json { "href": "https://api-shipx-pl.easypack24.net/v1/dispatch_orders/1", "id": 1, "status": "sent", "address": { "id": "123", "street": "Malborska", "building_number": "130", "post_code": "30-624", "city": "Kraków", "country_code": "PL", }, "shipments": [ { "href": "https://api-shipx-pl.easypack24.net/v1/shipments/8", "id": 8, "tracking_number": "622111081631876319900026" } ], "comments": [ { "id": 24, "comment": "Dowolny komentarz do zlecenia odbioru", "created_at": "2018-02-14T11:37:07.852+01:00" } ], "created_at": "2018-02-14T11:37:07.843+01:00", "updated_at": "2018-02-14T11:37:08.340+01:00" } }
Błędy
resource_not_found
- w przypadku gdy zlecenie o podanym ID nie zostanie odnalezione,
Usuwanie zlecenia odbioru
Zlecenie odbioru można usunąć jeśli jest ono w statusie new
lub sent
.
DELETE /v1/dispatch_orders/1
Przykład zapytania
DELETE /v1/dispatch_orders/1 HTTP/1.1 Host: api-shipx-pl.easypack24.net Content-Type: application/json Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]...
Odpowiedź
HTTP/1.1 204 No Content Content-Type: application/json
Błędy
resource_not_found
- w przypadku gdy zlecenie o podanym ID nie zostanie odnalezione,invalid_status
- w przypadku gdy zlecenie o podanym ID będzie w statusie innym niżnew
lubsent
,
Lista zleceń odbioru
Listę zleceń odbioru w ramach określonej organizacji można pobrać pod adresem:
GET /v1/organizations/:organization_id/dispatch_orders
Przykładowe zapytanie
GET /v1/organizations/12345/dispatch_orders HTTP/1.1 Host: api-shipx-pl.easypack24.net Content-Type: application/json Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]...
W odpowiedzi na poprawnie przesłane zapytanie, serwer zwróci odpowiedź z kodem HTTP 200 OK:
HTTP/1.1 200 OK Content-Type: application/json { "href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/dispatch_orders", "count": 15, "per_page": 30, "page": 1, "created_at": "2016-03-21T10:13:58.625+01:00", "items": [ { "href": "https://api-shipx-pl.easypack24.net/v1/dispatch_orders/3", "id": 123, ... other attribute omitted for brevity .... } ... other items omitted for brevity ... ] }
Błędy jakie mogą wystąpić podczas pobierania listy zleceń odbioru:
resource_not_found
- organizacja, dla której użytkownik chce pobrać listę zleceń odbioru nie istnieje,forbidden
- token nie uprawnia do do pobrania listy zleceń odbioru dla wybranej organizacji.
Tworzenie komentarza do zlecenia odbioru
Tworząc zlecenie odbioru, umożliwiamy przekazanie opcjonalnego komentarza.
Dodatkowo umożliwiamy dodawanie innych komentarzy do już istniejącego zlecenia odbioru.
POST /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment
Przykładowe zapytanie
POST /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment HTTP/1.1 Host: api-shipx-pl.easypack24.net Content-Type: application/json Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]... { "comment": "Dodatkowy dowolny komentarz do zlecenia odbioru" }
W odpowiedzi na poprawnie przesłane zapytanie, serwer zwróci odpowiedź z kodem HTTP 201 Created:
HTTP/1.1 201 Created Content-Type: application/json { "id": 37, "href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/dispatch_orders/17/comment", "comment": "To jest jakis nastepny testowy komentarz", "created_at": "2018-02-15T10:32:31.345+01:00" }
Aktualizacja komentarza do zlecenia odbioru
Do istniejącego zlecenia odbioru, umożliwiamy przekazanie dodatkowych komentarzy.
Dodatkowo umożliwiamy aktualizacje komentarza przynależnego do konkretnego zlecenia odbioru.
PUT /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment
Przykładowe zapytanie
PUT /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment HTTP/1.1 Host: api-shipx-pl.easypack24.net Content-Type: application/json Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]... { "id": 37, "comment": "Aktualizacja komentarza" }
W odpowiedzi na poprawnie przesłane zapytanie, serwer zwróci odpowiedź z kodem HTTP 201 Created:
HTTP/1.1 201 Created Content-Type: application/json { "id": 37, "href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/dispatch_orders/17/comment", "comment": "Aktualizacja komentarza", "created_at": "2018-02-15T10:32:31.345+01:00" }
Błędy jakie mogą wystąpić podczas pobierania listy zleceń odbioru:
resource_not_found
- organizacja, dla której użytkownik chce pobrać listę zleceń odbioru nie istnieje,forbidden
- token nie uprawnia do do pobrania listy zleceń odbioru dla wybranej organizacji.
Usunięcie komentarza do zlecenia odbioru
Do istniejącego zlecenia odbioru, umożliwiamy usunięcie komentarza lub ich kolekcji.
Code Block
DELETE /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment
Przykładowe zapytanie
Code Block
DELETE /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment HTTP/1.1 Host: api-shipx-pl.easypack24.net Content-Type: application/json Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]... { "comment_ids": [20,21] }
W odpowiedzi na poprawnie przesłane zapytanie, serwer zwróci odpowiedź z kodem HTTP 200 Created:
Code Block
HTTP/1.1 201 Created Content-Type: application/json { "href": "https://api-shipx-pl.easypack24.net/v1/dispatch_orders/2", "id": 2, "status": "sent", "external_id": 2000000001, "price": null, "address": { "id": 211, "street": "Malborska", "building_number": "130", "line1": null, "line2": null, "city": "Krakow", "post_code": "31-209", "country_code": "PL" }, "statuses": [], "shipments": [ { "href": "https://api-shipx-pl.easypack24.net/v1/shipments/103", "id": 103, "tracking_number": "520000017830390003050784" } ], "comments": [ { "id": 24, "comment": "Test 22", "created_at": "2018-05-15T11:34:54.119+02:00" }, { "id": 23, "comment": "Test 21", "created_at": "2018-05-15T11:34:51.438+02:00" }, { "id": 22, "comment": "Test 20", "created_at": "2018-05-15T11:34:48.637+02:00" } ], "created_at": "2018-05-15T09:19:32.317+02:00", "updated_at": "2018-05-15T09:19:32.448+02:00" }