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:
Code Block |
---|
{ "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.
Info | ||
---|---|---|
| ||
Po utworzeniu zlecenia odbioru, nie zwracamy cen dla klientów debetowych. Atrybut price przyjmuje wartość null |
Tworzenie nowego zlecenia odbioru
Code Block |
---|
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
Code Block |
---|
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ź
Code Block |
---|
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
Code Block |
---|
GET /v1/dispatch_orders/:order_id |
Przykład zapytania
Code Block |
---|
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ź
Code Block |
---|
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
.
Code Block |
---|
DELETE /v1/dispatch_orders/1 |
Przykład zapytania
Code Block |
---|
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ź
Code Block |
---|
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:
Code Block |
---|
GET /v1/organizations/:organization_id/dispatch_orders |
Przykładowe zapytanie
Code Block |
---|
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:
Code Block |
---|
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.
Code Block |
---|
POST /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment |
Przykładowe zapytanie
Code Block |
---|
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:
Code Block |
---|
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.
Code Block |
---|
PUT /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment |
Przykładowe zapytanie
Code Block |
---|
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:
Code Block |
---|
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" }