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

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.
  • Identyfikatory muszę się mieścić w zakresie typu Integer
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

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]...
 
{
	"dispatch_point_id": 1,
	"shipments": ["1", "2"],
	"comment": "Dowolny komentarz do zlecenia odbioru"
}

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

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

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.


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

Przykładowe zapytanie

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:

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