[1.9.1] 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:

  1. Utworzenie przesyłki, na co składa się podanie danych nadawcy, odbiorcy oraz informacji o paczce (fioletowe figury na poniższym diagramie),
  2. Pobranie informacji o dostępnych usługach dla utworzonego wcześniej obiektu przesyłki (niebieskie figury na poniższym diagramie),
  3. 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 API X 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

AtrybutTypOpis
hrefstringTylko do odczytu. Adres URL do zasobu.
idintegerTylko do odczytu. Identyfikator przesyłki w platformie Ship X.
statusStringTylko do odczytu. Aktualny status przesyłki.
custom_attributesCustomAttributesDodatkowe, opcjonalne atrybuty dla przesyłki.
parcelsArray[Parcel]Lista paczek w ramach przesyłki.
created_atdatetimeTylko do odczytu. Data utworzenia przesyłki w systemie Ship X.
created_by_idintegerId użytkownika, który utworzył przesyłkę, jeśli użytkownik jest zalogowany.
senderPeerDane nadawcy.
receiverPeerDane odbiorcy.
codMoneyDataPobranie za przesyłkę.
insuranceMoneyDataUbezpieczenie przesyłki.
additional_servicesArray[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

referenceStringDodatkowy opis dla przesyłki, np. numer zamówienia lub ID klienta.
is_returnBoolOkreśla czy przesyłka jest zwrotna.
offersObject

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

Struktura obiektu Offer:

AtrybutTypOpis
idIntegerUnikalny identyfikator usługi oferowanej w ramach przesyłki
serviceObjectObiekt oferowanej usługi.
carrierObjectObiekt przewoźnika.
additional_servicesArray[String]Usługi dodatkowe wybrane przy tworzeniu przesyłki - dostępne w danej ofercie.
statusStringStatus oferty
expires_at
DatetimeData i godzina do której możliwe jest zakupienie oferty.
rateDecimalCena za usługę.
currencyStringWaluta, w której podana jest cena za usługę.
unavailability_reasonsArrayPrzyczyny niedostępności danej oferty.

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

Struktura obiektu service:

AtrybutTypOpis
idStringIdentyfikator usługi
nameStringNazwa usługi
descriptionStringOpis usługi

Struktura obiektu carrier:

AtrybutTypOpis
idStringIdentyfikator przewoźnika
nameStringNazwa przewoźnika
descriptionStringOpis przewoźnika


selected_offerObjectUsługa, która została wybrana podczas kupowania etykiety dla przesyłki.
transactionsArray[Transaction]

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

Struktura obiektu Transaction:

AtrybutTypOpis
idStringIdentyfikator transakcji
statusStringStatus transakcji. Możliwe statusy: initiated, success, failure
created_atDateTimeData utworzenia transakcji.
updated_atDateTimeData ostatniej modyfikacji transakcji.
offer_idIntegerId oferty, której transakcja dotyczy.
tracking_numberStringNumer trackingowy przesyłki (identyfikator na poziomie systemu logistycznego).
sending_methodStringPowielenie pola z custom_attributes.
external_customer_id
StringIdentyfikator broker'a generującego przesyłki w ramach innej organizacji.

Atrybuty obiektu Parcel:

AtrybutTypOpis
idStringWymagany 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.
templateString

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.

dimensionsObject

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.

weightObject

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_numberStringNumer danej przesyłki. Nadawany w trakcie kupowania wybranej oferty.
is_non_standardBool

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:

AtrybutTypOpis
idStringIdentyfikator obiektu Peer
nameStringNazwa
company_nameStringNazwa firmy
first_nameStringImię
last_nameStringNazwisko
emailStringAdres e-mail
phoneStringNumer telefonu
addressObjectAdres

Atrybuty obiektu Address:

AtrybutTypOpis
idStringIdentyfikator obiektu adres
line1StringPierwsza linia adresu
line2StringDruga linia adresu
streetStringNazwa ulicy
building_numberStringNumer domu
cityStringMiasto
post_codeStringKod pocztowy
country_codeStringKod kraju

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


Atrybuty obiektu MoneyData:

AtrybutTypOpis
amountdecimalKwota
currencystringWaluta

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

AtrybutTypOpis
target_pointstringNazwa punktu docelowego, do którego ma zostać dostarczona przesyłka, z którego podejmie ją odbiorca, np. nazwa paczkomatu.
Tylko przesyłki paczkomatowe.
sending_methodstring

Sposób Nadania Przesyłki

Wymagane dla przesyłek Allegro.

dropoff_pointstring

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_idstringNumer 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_idstringNumer 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_idinteger

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.