[1.6.0] Zlecenia odbioru

(1)

[1.6.0] Zlecenia odbioru

Zlecenia odbioru pozwalaj na zamówienie podjazdu kuriera w celu odebrania wczeniej przygotowanych przesyek.

Kade zlecenie odbioru posiada status, który okrela jest stan. Obsugiwane statusy to:

new - nowe zlecenie odbioru, które nie zostao jeszcze przekazane do realizacji, sent - zlecenie odbioru zostao przekazane do realizacji, ale nie jest jeszcze przyjte,

Na tej stronie

Uwierzytelnianie Tworzenie nowego zlecenia odbioru Pobieranie informacji o zleceniu odbioru

Usuwanie zlecenia odbioru Lista zlece odbioru

Przykadowe zapytanie Tworzenie komentarza do zlecenia odbioru

Przykadowe zapytanie Aktualizacja komentarza do zlecenia odbioru

Przykadowe zapytanie Usunicie komentarza do zlecenia odbioru

Przykadowe zapytanie

Zasób DispatchOrderposiada nastpujce 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 nastpi odbiór.

shipments Array[Shipment] Tablica przesyek, których dotyczy zlecenie odbioru. Obiekt Shipment zawiera atrybuty:

href - adres uri przesyki, id - id przesyki,

tracking_number - numer trackingowy przesyki.

comment string Opcjonalny komentarz do zlecenia odbioru

Przykad zasobu DispatchOrder w formacie JSON:

(2)

{

"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

Dostp do zasobu i jego metod wymaga podania aktualne i wanego access token.

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 przesyka 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 address

shipments Array Lista ID przesyek, dla których ma zosta utworzone zlecenia odbioru.

Atrybut jest wymagany.

Paczki musz by w statusie confirmed i nie mog by przypisane do innego zlecenia odbioru w statusie new, sent, accepted lub done.

Dodatkowo musza byc to paczki tego samego carriera.

Nie ma moliwoci utworzenia jednego zlecenia odbioru dla przesyek allegro i innych.

Przesyki mog by albo dla allegro, albo kade inne.

comment string Opcjonalny komentarz do zlecenia odbioru Atrybut nie jest wymagany do tworzenia zlecenia odbioru.

Wymagalno pojawia si z chwil tworzenia komentarza do ju istniejcego zlecenia odbioru.

Uwaga! Klienci debetowi

Po utworzeniu zlecenia odbioru, nie zwracamy cen dla klientów debetowych.

Atrybut price przyjmuje warto null

(3)

address Addre ssForm

Adres zlecenia odbioru Atrybut nie jest wymagany.

Wymagalno pojawia si w momencie kiedy nie zostanie przekazany atrybut dispatch_point_id

office_hours string Godziny funkcjonowania punktu Atrybut nie jest wymagany.

Okrela godziny funkcjonowania punktu, jeeli 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.

email string Kontakt mailowy. Wykorzystywany do stworzenia dispatch_point.

Przykad 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": "Przykadowa nazwa DispatchPoint",

"phone": "505404202", "email": "sample@email.com", "address": {

"street": "Malborska", "building_number": "130", "city": "Krakow",

"post_code": "31-209", "country_code": "PL"

} }

Odpowied

(4)

HTTP/1.1 201 Created

Content-Type: application/json {

"id": "123",

"shipments": [ {

"tracking_number": "622111081631876319900026"

} ],

"comments": [ {

"id": 24,

"comment": "Dowolny komentarz do zlecenia odbioru", "created_at": "2018-02-14T11:37:07.852+01:00"

} ],

}

Zlecenie odbioru przesyek na adres

Generowanie zlecenia na adres wymusza przekazanie adresu poprzez atrybut addressObiekt Address

System generuje sum kontroln z przekazanych informacji, naley zwróci uwag aby adres by dokadny i bez bdów (tzw. literówek)

Na podstawie sumy kontrolnej system sprawdza, czy istnieje w bazie punkt odbioru o takim samym adresie, jeli nie istnieje, automatycznie generowany jest nowy punkt odbioru (dotyczy wycznie przesyek paczkomatowych).

Na nowo wygenerowany punkt odbioru (DipstachPoint) realizowane jest zlecenie odbioru (DispatchOrder).

Bdy

validation_failed - przesane dane s niepoprawne, np. podany punkt odbioru lub która z przesyek ma niepoprawny status invalid_range - podano nieprawidowy zakres identyfikatora przesyki, zakres nie mieci si w zakresie typu Integer

dispatch_point_and_address_cannot_be_mixed - Nie mona jednoczenie nadawa zlecenia odbioru na adres oraz id punktu odbioru

Pobieranie informacji o zleceniu odbioru

GET /v1/dispatch_orders/:order_id

GET /v1/dispatch_orders/1 HTTP/1.1 Host: api-shipx-pl.easypack24.net Content-Type: application/json

Odpowied

(5)

HTTP/1.1 200 OK

"id": "123",

"shipments": [ {

"tracking_number": "622111081631876319900026"

} ],

"comments": [ {

"id": 24,

"comment": "Dowolny komentarz do zlecenia odbioru", "created_at": "2018-02-14T11:37:07.852+01:00"

} ],

} }

Bdy

resource_not_found - w przypadku gdy zlecenie o podanym ID nie zostanie odnalezione,

Usuwanie zlecenia odbioru

Zlecenie odbioru mona usun jeli jest ono w statusie new lub sent.

DELETE /v1/dispatch_orders/1

DELETE /v1/dispatch_orders/1 HTTP/1.1 Host: api-shipx-pl.easypack24.net Content-Type: application/json

Odpowied

HTTP/1.1 204 No Content Content-Type: application/json

Bdy

resource_not_found - w przypadku gdy zlecenie o podanym ID nie zostanie odnalezione, invalid_status - w przypadku gdy zlecenie o podanym ID bdzie w statusie innym ni new lub sent,

Lista zlece odbioru

(6)

List zlece odbioru w ramach okrelonej organizacji mona pobra pod adresem:

GET /v1/organizations/:organization_id/dispatch_orders

Przykadowe zapytanie

GET /v1/organizations/12345/dispatch_orders HTTP/1.1 Host: api-shipx-pl.easypack24.net

W odpowiedzi na poprawnie przesane zapytanie, serwer zwróci odpowied z kodem HTTP 200 OK:

HTTP/1.1 200 OK

"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": [

{

... other attribute omitted for brevity ....

}

... other items omitted for brevity ...

] }

Bdy jakie mog wystpi podczas pobierania listy zlece odbioru:

resource_not_found - organizacja, dla której uytkownik 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

Tworzc zlecenie odbioru, umoliwiamy przekazanie opcjonalnego komentarza.

Dodatkowo umoliwiamy dodawanie innych komentarzy do ju istniejcego zlecenia odbioru.

POST /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment

Przykadowe zapytanie

POST /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment HTTP/1.1 Host: api-shipx-pl.easypack24.net

{

"comment": "Dodatkowy dowolny komentarz do zlecenia odbioru"

}

W odpowiedzi na poprawnie przesane zapytanie, serwer zwróci odpowied z kodem HTTP 201 Created:

(7)

"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 istniejcego zlecenia odbioru, umoliwiamy przekazanie dodatkowych komentarzy.

Dodatkowo umoliwiamy aktualizacje komentarza przynalenego do konkretnego zlecenia odbioru.

PUT /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment

Przykadowe zapytanie

PUT /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment HTTP/1.1 Host: api-shipx-pl.easypack24.net

{

"id": 37,

"comment": "Aktualizacja komentarza"

}

"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"

}

Bdy jakie mog wystpi podczas pobierania listy zlece odbioru:

resource_not_found - organizacja, dla której uytkownik chce pobra list zlece odbioru nie istnieje, forbidden - token nie uprawnia do do pobrania listy zlece odbioru dla wybranej organizacji.

Usunicie komentarza do zlecenia odbioru

Do istniejcego zlecenia odbioru, umoliwiamy usunicie komentarza lub ich kolekcji.

Code Block

DELETE /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment

Przykadowe zapytanie

(8)

Code Block

DELETE /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment HTTP/1.1 Host: api-shipx-pl.easypack24.net

{

"comment_ids": [20,21]

}

Code Block

"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": [ {

"tracking_number": "520000017830390003050784"

} ],

"comments": [ {

"id": 24,

"comment": "Test 22",

"created_at": "2018-05-15T11:34:54.119+02:00"

}, {

"id": 23,

"created_at": "2018-05-15T11:34:51.438+02:00"

}, {

"id": 22,

"created_at": "2018-05-15T11:34:48.637+02:00"

} ],

}