Versions Compared

Old Version 17

changes.mady.by.user Michał Machowski

Saved on

compared with

New Version 19

changes.mady.by.user Michał Machowski

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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 jego 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,

Na tej stronie

Table of Contents

Struktura

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

Atrybut

Typ

Opis

id

String

ID Zlecenia Odbioru. Tylko do odczytu.

status

String

Status zlecenia odbioru.

created_at

DateTime

Czas utworzenia zlecenia odbioru.

address

Address

Adres, z którego ma nastąpić odbiór.

shipments

Array[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.

comment

String

Opcjonalny komentarz do zlecenia odbioru

Przykład zasobu DispatchOrder w formacie JSON:

Code Block
languagejson
{
	"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 wymaga podania prawidłowego i ważnego access tokenu.

Tworzenie zlecenia odbioru

Generowanie zlecenia na adres wymusza przekazanie adresu poprzez atrybut 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 paczkomatowychPaczkomat®).

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

Info

Działanie asynchroniczne, aby pobrać numer zlecenia należy skorzystać z https://dokumentacja-inpost.atlassian.net/wiki/spaces/PL/pages/11731045/1.6.0+Zlecenia+odbioru#Szczeg%C3%B3%C5%82y-zlecenia-odbioru, numer zlecenia znajduje się w parametrze "external_id".

Po utworzeniu zlecenia odbioru nie zwracamy cen dla klientów debetowych.
Atrybut price przyjmuje wartość null

Code Block
languagejson
POST /v1/organizations/:organization_id/dispatch_orders

Parametry

Parametr

Typ

Opis

Walidacja

shipments

Array

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 muszą być to paczki tego samego przewoźnika.

  • 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.

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

Address

Adres zlecenia odbioru

Atrybut jest wymagany.

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 jest wymagany.

phone

String

Kontakt telefoniczny. Wykorzystywany do stworzenia dispatch_point.

Atrybut jest wymagany.

email 

String

Kontakt mailowy. Wykorzystywany do stworzenia dispatch_point.

Atrybut nie jest wymagany.

Przykład zapytania

Code Block
languagejson
curl -X POST https://api-shipx-pl.easypack24.net/v1/organizations/1/dispatch_orders -H 'Authorization: Bearer token' -H 'Content-Type: application/json' -d '{
	"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
languagejson
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"
}
Warning

Informacje o błędach

  • 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

Usuwanie zlecenia odbioru

Zlecenie odbioru można usunąć jeśli jest ono w statusie new lub sent.

Code Block
languagejson
DELETE /v1/dispatch_orders/:id

Przykład zapytania

Code Block
languagejson
curl -X DELETE https://api-shipx-pl.easypack24.net/v1/dispatch_orders/1 -H 'Authorization: Bearer token' -H 'Content-Type: application/json'

Odpowiedź

Code Block
languagejson
HTTP/1.1 204 No Content
Content-Type: application/json
Warning

Informacje o błędach

  • 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:

Code Block
languagejson
GET /v1/organizations/:organization_id/dispatch_orders

Odpowiedź

Code Block
languagejson
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 ...
	]
}
Warning

Informacja o błędach

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 pobrania listy zleceń odbioru dla wybranej organizacji

Szczegóły zlecenia odbioru

Code Block
languagejson
GET /v1/dispatch_orders/:id

Przykład zapytania

Code Block
languagejson
curl -X GET https://api-shipx-pl.easypack24.net/v1/dispatch_orders/1 -H 'Authorization: Bearer token' -H 'Content-Type: application/json'

Odpowiedź

Code Block
languagejson
HTTP/1.1 200 OK
Content-Type: application/json
 {
  	  "href": "https://api-shipx-pl.easypack24.net/v1/dispatch_orders/13223738",
	    "id": 13223738,
    	"status": "sent",
	"address": {
		"    "external_id": "123"2003222292,
  		  "streetprice": "Malborska"null,
    	"building_numberaddress": "130",
		{
        "id": 1192036131,
        "street": "Malborska",
        "building_number": "130",
        "line1": null,
        "line2": null,
        "city": "Krakow",
        "post_code": "3031-624209",
		"city
        "country_code": "Kraków",
		"country_code": "PL",
	},
	PL"
    },
    "statuses": [],
    "shipments": [
        {
            "href": "https://api-shipx-pl.easypack24.net/v1/shipments/8793374228",
            "id": 8793374228,
            "tracking_number": "622111081631876319900026602677358231630337744964"
        }
    ],
	"comments
    "comments": [
        {
            "id": [3198262,
        { 		 "id": 24, 		 "comment": "Dowolny komentarz do zlecenia odbioru",
            "created_at": "20182022-0205-14T1127T10:3715:0731.852765+0102:00"
        }
    ],
 	   "created_at": "20182022-0205-14T1127T10:3715:0731.843756+0102:00",
    "updated_at": "20182022-0205-14T1127T10:3715:0832.340122+0102:00"
}
Warning

Informacje o błędach

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

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
languagejson
curl -X POST https://api-shipx-pl.easypack24.net//v1/organizations/1/dispatch_orders/1/comment -H 'Authorization: Bearer token' -H 'Content-Type: application/json' -d '{
	"comment": "Dodatkowy dowolny komentarz do zlecenia odbioru"
}'

Odpowiedź

Code Block
languagejson
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": "Dodatkowy dowolny komentarz do zlecenia odbioru",
    "created_at": "2018-02-15T10:32:31.345+01:00"
}

Aktualizowanie 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
languagejson
PUT /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment

Przykładowe zapytanie

Code Block
curl -X PUT https://api-shipx-pl.easypack24.net/v1/organizations/1/dispatch_orders/1/comment -H 'Authorization: Bearer token' -H 'Content-Type: application/json' -d '{
	"id": 37,
	"comment": "Aktualizacja komentarza"
}

Odpowiedź

Code Block
languagejson
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"
}
Warning

Informacje o błędach

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 pobrania listy zleceń odbioru dla wybranej organizacji

Usuwanie komentarza do zlecenia odbioru

Do istniejącego zlecenia odbioru, umożliwiamy usunięcie komentarza lub ich kolekcji.

Code Block
languagejson
DELETE /v1/organizations/:organization_id/dispatch_orders/:dispatch_order_id/comment

Przykładowe zapytanie 

Code Block
languagejson
curl -X DELETE https://api-shipx-pl.easypack24.net/v1/organizations/1/dispatch_orders/1/comment -H 'Authorization: Bearer token' -H 'Content-Type: application/json'

Odpowiedź

Code Block
languagejson
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"
}