[1.9.0] Przesyłka

Sercem Platformy Usług Zintegrowanych są przesyłki. Na definicję przesyłki składają się:

dane nadawcy i odbiorcy
paczka (jedna lub więcej), która będzie fizycznie przesyłana
wybrana usługa (opcjonalnie usługi dodatkowe)
inne dodatkowe atrybuty w zależności od preferencji użytkownika, np.:
- Ubezpieczenie
- Pobranie

Aby utworzyć przesyłkę gotową do nadania, wymagane są 3 kroki:

Utworzenie przesyłki, na co składa się podanie danych nadawcy, odbiorcy oraz informacji o paczce (fioletowe figury na poniższym diagramie),
Pobranie informacji o dostępnych usługach dla utworzonego wcześniej obiektu przesyłki (niebieskie figury na poniższym diagramie),
Zakupienie etykiety poprzez wskazanie określonej usługi, dostępnej dla przesyłki, która została utworzona w kroku 1 (zielona figura na poniższym diagramie)

Na tej stronie

Uwierzytelnianie

Aby uzyskać dostęp do zasobu Shipment wymagane jest podanie aktualnego i prawidłowego access tokenu.

Diagram tworzenia przesyłki

Ceny usług mogą różnić się w zależności od wymiarów paczki oraz parametrów przesyłki, zdefiniowanych podczas jej tworzenia.

Listę wszystkich usług można znaleźć na stronie Rozmiary i usługi dla przesyłek

Dostępność usług zależy od przewoźników z którymi dana organizacja podpisała umowy.

Dla Klientów, których umowa pozwala na utworzenie debetu w systemie InPost (klient debetowy), nie będą zwracane ceny w odpowiedzi JSON, na wysłane żądanie do API.

Zasób Shipments dostępny jest dla Organizacji (z ID organization_id)

https://api-shipx-pl.easypack24.net/v1/organizations/:organization_id/shipments

Atrybuty

Atrybut Typ Opis

href string Tylko do odczytu. Adres URL do zasobu.

id integer Tylko do odczytu. Identyfikator przesyłki w platformie Ship X.

status String Tylko do odczytu. Aktualny status przesyłki.

custom_attributes CustomAttributes Dodatkowe, opcjonalne atrybuty dla przesyłki.

parcels Array[Parcel] Lista paczek w ramach przesyłki.

created_at datetime Tylko do odczytu. Data utworzenia przesyłki w systemie Ship X.

created_by_id integer Id użytkownika, który utworzył przesyłkę, jeśli użytkownik jest zalogowany.

sender Peer Dane nadawcy.

receiver Peer Dane odbiorcy.

cod MoneyData Pobranie za przesyłkę.

insurance MoneyData Ubezpieczenie przesyłki.

additional_services

Array[String]

Usługi dodatkowe wybrane przy tworzeniu przesyłki (różne oferty mogą zawierać różne usługi dodatkowe).

Dostępne usługi dodatkowe: sms, email, saturday. API X Rozmiary i usługi dla przesyłek

reference String Dodatkowy opis dla przesyłki, np. numer zamówienia lub ID klienta.

is_return Bool Określa czy przesyłka jest zwrotna.

offers

Object

Lista dostępnych usług wraz z cenami, które możliwe są do nabycia w ramach tej przesyłki.

Struktura obiektu Offer:

Atrybut	Typ	Opis
`id`	Integer	Unikalny identyfikator usługi oferowanej w ramach przesyłki
`service`	Object	Obiekt oferowanej usługi.
`carrier`	Object	Obiekt przewoźnika.
`additional_services`	Array[String]	Usługi dodatkowe wybrane przy tworzeniu przesyłki - dostępne w danej ofercie.
`status`	String	Status oferty
expires_at	Datetime	Data i godzina do której możliwe jest zakupienie oferty.
`rate`	Decimal	Cena za usługę.
`currency`	String	Waluta, w której podana jest cena za usługę.
`unavailability_reasons`	Array	Przyczyny niedostępności danej oferty.

Możliwe statusy oferty: in_preparation, available, unavailable, selected, bought, expired

Struktura obiektu service:

Atrybut	Typ	Opis
`id`	String	Identyfikator usługi
`name`	String	Nazwa usługi
description	String	Opis usługi

Struktura obiektu carrier:

Atrybut	Typ	Opis
`id`	String	Identyfikator przewoźnika
`name`	String	Nazwa przewoźnika
description	String	Opis przewoźnika

selected_offer Object Usługa, która została wybrana podczas kupowania etykiety dla przesyłki.

transactions

Array[Transaction]

Lista transakcji płatniczych związanych z daną przesyłką.

Struktura obiektu Transaction:

Atrybut	Typ	Opis
id	String	Identyfikator transakcji
`status`	String	Status transakcji. Możliwe statusy: `initiated`, `success`, `failure`
`created_at`	DateTime	Data utworzenia transakcji.
`updated_at`	DateTime	Data ostatniej modyfikacji transakcji.
`offer_id`	Integer	Id oferty, której transakcja dotyczy.

tracking_number String Numer trackingowy przesyłki (identyfikator na poziomie systemu logistycznego).

sending_method String Powielenie pola z custom_attributes.

external_customer_id

String

Identyfikator broker'a generującego przesyłki w ramach innej organizacji.

Atrybuty obiektu Parcel:

Atrybut	Typ	Opis
`id`	String	Wymagany przy tworzeniu przesyłki z wieloma paczkami. Unikalny identyfikator danej paczki w ramach przesyłki, który pozwala zwrócić użytkownikowi informację o błędach walidacji przypisanych do konkretnej paczki. Id nie jest zapisywany w bazie danych i nie jest zwracany jak atrybut utworzonej paczki.
`template`	String	Nazwa predefiniowanego szablonu wymiarów i wagi paczki. Listę predefiniowanych szablonów wymiarów i rozmiarów paczek można znaleźć na stronie API X Rozmiary i usługi dla przesyłek.
`dimensions`	Object	Wymiary paczki. `length` - długość `width` - szerokość `height` - wysokość `unit` - jednostka, w której podane są wymiary. Aktualnie tylko mm (millimetry) Uzupełniane automatycznie w przypadku wybrania prawidłowego szablonu `template`.
`weight`	Object	Waga paczki `amount` - waga, `unit` - jednostka, w której podana jest waga paczki. Aktualnie tylko kg (kilogramy) Uzupełniana automatycznie w przypadku wybrania prawidłowego szablonu `template`.
`tracking_number`	String	Numer danej przesyłki. Nadawany w trakcie kupowania wybranej oferty.
`is_non_standard`	Bool	Ustawiany na `true` jeżeli przesyłka jest niestandardowa. Parametr można ustawić tylko dla przesyłek kurierskich. Paczka realizowana tylko w ramach usług kurierskich w serwisie krajowym, której jeden z wymiarów przekracza 120 cm lub której suma wymiarów (długość + szerokość + wysokość) przekracza 220 cm. Paczką niestandardową są również: elementy o kształcie okrągłym, cylindrycznym lub owalnym, o nieregularnych kształtach lub/i z wystającymi elementami. Opcja paczek niestandardowych nie dotyczy paczek dłużycowych.

Atrybuty obiektu Peer:

Atrybut	Typ	Opis
id	String	Identyfikator obiektu Peer
name	String	Nazwa
`company_name`	String	Nazwa firmy
`first_name`	String	Imię
`last_name`	String	Nazwisko
`email`	String	Adres e-mail
`phone`	String	Numer telefonu
`address`	Object	Adres

Atrybuty obiektu Address:

Atrybut	Typ	Opis
id	String	Identyfikator obiektu adres
line1	String	Pierwsza linia adresu
line2	String	Druga linia adresu
street	String	Nazwa ulicy
building_number	String	Numer domu
`city`	String	Miasto
`post_code`	String	Kod pocztowy
`country_code`	String	Kod kraju

Atrybut line1 i line2 jest jeszcze wspierany, jednak zalecane jest używanie street i building_number.

Atrybuty obiektu MoneyData:

Atrybut	Typ	Opis
`amount`	decimal	Kwota
`currency`	string	Waluta

Przygotowując przesyłkę, możliwe jest określenie dodatkowych parametrów w ramach obiektu custom_attributes:

Atrybut	Typ	Opis
`target_point`	string	Nazwa punktu docelowego, do którego ma zostać dostarczona przesyłka, z którego podejmie ją odbiorca, np. nazwa paczkomatu. Tylko przesyłki paczkomatowe.
sending_method	string	Sposób nadania przesyłki. Wymagane dla przesyłek Allegro.
`dropoff_point`	string	Nazwa punktu nadawczego, do którego nadawca dostarczy przesyłkę do wysłania, np. nazwa paczkomatu. Wymagane przy podaniu metody nadania `pok`, `courier_pok`, `parcel_locker`.
`allegro_transaction_id`	string	Numer transakcji formularza posprzedażowego Allegro, w którym kupujący wybrał formę dostawy Allegro Paczkomaty InPost. Podanie tego parametru skutkuje koniecznością podania parametru `allegro_user_id`.
`allegro_user_id`	string	Numer użytkownika Allegro, w ramach transkacji określonej parameterem `allegro_user_id`, który jest sprzedającym. Podanie tego parametru skutkuje koniecznością podania parametru `allegro_transaction_id`.
dispatch_order_id	integer	Numer zlecenia odbioru. Atrybut tylko do odczytu, występuje gdy przesyłka posiada zdefiniowane zlecenie odbioru.

Przykład zasobu w formacie JSON (przesyłka paczkomatowa).

{
	"href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments/1234567890",
	"id": "1234567890",
	"status": "offers_prepared",
	"parcels": [
		{
			"id": "small package",
			"template": "small",
			"dimensions": {
				"length": "80",
				"width": "360",
				"height": "640",
				"unit": "mm"
			},
			"weight": {
				"amount": "25",
				"unit": "kg"
			},
			"tracking_number": null,
            "is_non_standard": false
		}
	],
	"custom_attributes": {
		"target_point": "KRA010",
		"dropoff_point": null,
		"sending_method": "parcel_locker",
        "dispatch_order_id": 1
	},
	"sender": {
		"id": "123",
		"name": "Nazwa",
		"company_name": "InPost S.A.",
		"first_name": "Jan",
		"last_name": "Nowak",
		"email": "sender@email.com",
		"phone": "888000000",
		"address": {
			"id": "123",
			"street": "Malborska",
			"building_number": "130",
			"city": "Kraków",
			"post_code": "30-624",
			"country_code": "PL"
		}
	},
	"receiver": {
		"id": "123",
		"name": "Nazwa",
		"company_name": null,
		"first_name": null,
		"last_name": null,
		"email": "sender@email.com",
		"phone": "888000000",
		"address": null
	},
	"created_at": "2015-09-06T19:21:00.000+02:00",
	"cod": {
		"amount": 12.50,
		"currency": "PLN"
	},
	"insurance": {
		"amount": 25,
		"currency": "PLN"
	},
	"additional_services": [],
	"reference": "Order No. 12345",
	"is_return": false,
	"tracking_number": null,
    "created_by_id": 3,
    "offers": [
        {
          "id": 1278,
          "carrier": {
              "id": "inpost_locker",
              "name": "InPost Paczkomaty",
			  "description": "InPost Paczkomaty - Przesyłki paczkomatowe."
          },
          "service": {
              "id": "inpost_locker_standard",
              "name": "Paczkomatowa Standardowa",
			  "description": "Przesyłka paczkomatowa standardowa."
          },
          "status": "available",
          "expires_at": "2015-09-06T19:21:00.000+02:00",
          "rate": 2.02,
          "currency": "PLN",
          "unavailability_reasons": null
        }
	],
	"selected_offer": null,
	"transactions": [],
	"sending_method": "parcel_locker",
	"external_customer_id": "8877xxx",
}

Lista przesyłek Organizacji

Lista przesyłek w ramach określonej organizacji:

GET /v1/organizations/:organization/shipments

Uprawnienia

Aby pobrać listę przesyłek dla określonej organizacji użytkownik musi być jej członkiem.

Przykładowe zapytanie

GET /v1/organizations/12345/shipments 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/shipments",
	"count": 15,
	"per_page": 30,
	"page": 1,
	"items": [
		{
			"href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments/123",
			"id": 123,
			... other attribute omitted for brevity ....
		}
		... other items omitted for brevity ...
	]
}

Błędy jakie mogą wystąpić podczas pobierania listy przesyłek:

resource_not_found - organizacja, dla której użytkownik chce pobrać listę przesyłek nie istnieje lub nie ma do niej dostępu.