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)
Panel | ||||||
---|---|---|---|---|---|---|
| ||||||
|
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)
Code Block |
---|
https://api-shipx-pl.easypack24.net/v1/organizations/:organization_id/shipments |
Atrybuty
href
id
status
Diagram tworzenia przesyłki
parcels
created_at
created_by_id
cod
insurance
additional_services
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
is_return
offers
selected_offer
transactions
Lista transakcji płatniczych związanych z daną przesyłką.
Struktura obiektuTransaction
: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 |
status
initiated
, success
, failure
created_at
updated_at
offer_id
tracking_number
sending_method
custom_attributes
.external_customer_id
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.
Uzupełniane automatycznie w przypadku wybrania prawidłowego szablonu |
weight | Object | Waga paczki
Uzupełniana automatycznie w przypadku wybrania prawidłowego szablonu |
tracking_number | String | Numer danej przesyłki. Nadawany w trakcie kupowania wybranej oferty. |
is_non_standard | Bool | Ustawiany na 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. |
Peer
:Object:_codecountry_code
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 | 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 |
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).
Lista przesyłek Organizacji
Lista przesyłek w ramach określonej organizacji:
Code Block |
---|
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
Code Block |
---|
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: