Developer Documentations
Page tree
Skip to end of metadata
Go to start of metadata

Zlecenia odbioru pozwalają na zamówienie podjazdu kuriera w celu odebrania wcześniej przygotowanych przesyłek.

Każde zlecenie odbioru posiada status, który określa jest stan. Obsługiwane statusy to:

  • new - nowe zlecenie odbioru, które nie zostało jeszcze przekazane do realizacji,
  • sent - zlecenie odbioru zostało przekazane do realizacji, ale nie jest jeszcze przyjęte,
  • accepted - zlecenie zostało przyjęte do realizacji przez kuriera,
  • done - zlecenie odbioru zostało zrealizowane,
  • rejected - zlecenie odbioru zostało odrzucone przez kuriera,
  • canceled - zlecenie zostało anulowane,
Na tej stronie

 

Zasób DispatchOrder posiada następujące atrybuty:

AtrybutTypOpis
hrefstringURI do zasobu.
idstringID Zlecenia Odbioru. Tylko do odczytu.
statusstringStatus zlecenia odbioru.
created_atTimeCzas utworzenia zlecenia odbioru.
addressObjectAdres, z które ma nastąpić odbiór.
shipmentsArray[Shipment]

Tablica przesyłek, których dotyczy zlecenie odbioru. Obiekt Shipment zawiera atrybuty:

  • href - adres uri przesyłki,
  • id - id przesyłki,
  • tracking_number - numer trackingowy przesyłki.
commentstringOpcjonalny 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.

Atrybut price przyjmuje wartość null

Tworzenie nowego zlecenia odbioru

POST /v1/organizations/:org_id/dispatch_orders

Parametry

ParametrTypOpisWalidacja
dispatch_point_idintegerIdentyfikator 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 address

shipmentsArray

Lista ID przesyłek, 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 możliwości utworzenia jednego zlecenia odbioru dla przesyłek allegro i innych.
  • Przesyłki mogą być albo dla allegro, albo każde inne.
commentstringOpcjonalny 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.

addressAddressFormAdres zlecenia odbioru

Atrybut nie jest wymagany.

Wymagalność pojawia się w momencie kiedy nie zostanie przekazany atrybut dispatch_point_id

office_hoursstringGodziny funkcjonowania punktu

Atrybut nie jest wymagany.

Określa godziny funkcjonowania punktu, jeżeli tworzymy zlecenie odbioru na adres.

namestringNazwa punktu. Wykorzystywana do stworzenia dispatch_point.Atrybut nie jest wymagany.
phonestringKontakt telefoniczny. Wykorzystywany do stworzenia dispatch_point.Atrybut nie jest wymagany.
emailstringKontakt 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 status
  • invalid_range - podano nieprawidłowy zakres identyfikatora przesyłki, zakres nie mieści się w zakresie typu Integer
  • dispatch_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 lub sent,

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




  • No labels