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
custom_attributes
parcels
created_at
created_by_id
sender
receiver
cod
insurance
additional_services
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
Lista dostępnych usług wraz z cenami, które możliwe są do nabycia w ramach tej przesyłki.
Struktura obiektuOffer
:Diagram tworzenia przesyłki
in_preparation
, available
, unavailable, selected, bought, expired
service
: carrier
:selected_offer
transactions
Lista transakcji płatniczych związanych z daną przesyłką.
Struktura obiektu Transaction
:
tracking_number
sending_method
custom_attributes
.external_customer_id
Atrybuty obiektu Parcel
:
id
template
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
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
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
is_non_standard
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
:
target_point
Tylko przesyłki paczkomatowe.
Wymagane dla przesyłek Allegro.
dropoff_point
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
allegro_user_id
.allegro_user_id
allegro_user_id
, który jest sprzedającym. Podanie tego parametru skutkuje koniecznością podania parametru allegro_transaction_id
.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: