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

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

Atrybut	Typ	Opis

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

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

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

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

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

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