- Created by anagorski, last modified by Michał Machowski on Sept 16, 2022
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 8 Next »
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)
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 [1.9.1] 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.
Na tej stronie
Diagram tworzenia przesyłki
Struktura
Zasób Shipment
posiada następujące atrybuty:
Atrybut | Typ | Opis |
---|---|---|
| Integer | Tylko do odczytu. Identyfikator przesyłki w platformie Ship X. |
| String | Tylko do odczytu. Aktualny status przesyłki. |
| CustomAttributes | Dodatkowe, opcjonalne atrybuty dla przesyłki. |
| Array[Parcel] | Lista paczek w ramach przesyłki. |
| DateTime | Tylko do odczytu. Data utworzenia przesyłki w systemie Ship X. |
| Integer | Id użytkownika, który utworzył przesyłkę, jeśli użytkownik jest zalogowany. |
| Peer | Dane nadawcy. |
| Peer | Dane odbiorcy. |
| MoneyData | Pobranie za przesyłkę. |
| MoneyData | Ubezpieczenie przesyłki. |
| 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: |
| String | Dodatkowy opis dla przesyłki, np. numer zamówienia lub ID klienta. |
| Bool | Określa czy przesyłka jest zwrotna. |
| Array[Offer] | Lista dostępnych usług wraz z cenami, które możliwe są do nabycia w ramach tej przesyłki. |
| Offer | Usługa, która została wybrana podczas kupowania etykiety dla przesyłki. |
| Array[Transaction] | Lista transakcji płatniczych związanych z daną przesyłką. |
| String | Numer trackingowy przesyłki (identyfikator na poziomie systemu logistycznego). |
| String | Powielenie pola z |
| String | Identyfikator broker'a generującego przesyłki w ramach innej organizacji. |
Atrybuty obiektu Parcel
Atrybut | Typ | Opis |
---|---|---|
| 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. |
| String | Nazwa predefiniowanego szablonu wymiarów i wagi paczki. Listę predefiniowanych szablonów wymiarów i rozmiarów paczek można znaleźć na stronie [1.9.1] Rozmiary i usługi dla przesyłek . |
| Object | Wymiary paczki.
Uzupełniane automatycznie w przypadku wybrania prawidłowego szablonu |
| Object | Waga paczki
Uzupełniana automatycznie w przypadku wybrania prawidłowego szablonu |
| String | Numer danej przesyłki. Nadawany w trakcie kupowania wybranej oferty. |
| 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. |
Struktura obiektu Offer
Atrybut | Typ | Opis |
---|---|---|
| Integer | Unikalny identyfikator usługi oferowanej w ramach przesyłki |
| Service | Obiekt oferowanej usługi. |
| Carrier | Obiekt przewoźnika. |
| Array[String] | Usługi dodatkowe wybrane przy tworzeniu przesyłki - dostępne w danej ofercie. |
| String | Status oferty. Możliwe statusy oferty: |
| DateTime | Data i godzina do której możliwe jest zakupienie oferty. |
| Decimal | Cena za usługę. |
| String | Waluta, w której podana jest cena za usługę. |
| Array | Przyczyny niedostępności danej oferty. |
Struktura obiektu Service
Atrybut | Typ | Opis |
---|---|---|
| String | Identyfikator usługi |
| String | Nazwa usługi |
| String | Opis usługi |
Struktura obiektu Carrier
Atrybut | Typ | Opis |
---|---|---|
| String | Identyfikator przewoźnika |
| String | Nazwa przewoźnika |
| String | Opis przewoźnika |
Struktura obiektu Transaction
Atrybut | Typ | Opis |
---|---|---|
| String | Identyfikator transakcji |
| String | Status transakcji. Możliwe statusy: |
| DateTime | Data utworzenia transakcji. |
| DateTime | Data ostatniej modyfikacji transakcji. |
| Integer | Id oferty, której transakcja dotyczy. |
Atrybuty obiektu Peer
Atrybut | Typ | Opis |
---|---|---|
| String | Identyfikator obiektu Peer |
| String | Nazwa |
| String | Nazwa firmy |
| String | Imię |
| String | Nazwisko |
| String | Adres e-mail |
| String | Numer telefonu |
| Address | Adres |
Atrybuty obiektu Address
Atrybut line1 i line2 jest jeszcze wspierany, jednak zalecane jest używanie street i building_number.
Atrybut | Typ | Opis |
---|---|---|
| String | Identyfikator obiektu adres |
|
|
|
|
|
|
| String | Nazwa ulicy |
| String | Numer domu |
| String | Miasto |
| String | Kod pocztowy |
| String | Kod kraju |
Atrybuty obiektu MoneyData
Atrybut | Typ | Opis |
---|---|---|
| Decimal | Kwota |
| String | Waluta |
Atrybuty obiektu CustomAttributes
Atrybut | Typ | Opis |
---|---|---|
| String | Nazwa punktu docelowego, do którego ma zostać dostarczona przesyłka, z którego podejmie ją odbiorca, np. nazwa Paczkomat®. Tylko przesyłki Paczkomat®. |
| String | Wymagane dla przesyłek Allegro. |
| String | Nazwa punktu nadawczego, do którego nadawca dostarczy przesyłkę do wysłania, np. nazwa Paczkomat®. Wymagane przy podaniu metody nadania |
| String | Numer transakcji formularza posprzedażowego Allegro, w którym kupujący wybrał formę dostawy Allegro Paczkomat® InPost. Podanie tego parametru skutkuje koniecznością podania parametru |
| String | Numer użytkownika Allegro, w ramach transkacji określonej parameterem |
| Integer | Numer zlecenia odbioru. Atrybut tylko do odczytu, występuje gdy przesyłka posiada zdefiniowane zlecenie odbioru. |
Przykład zasobu Shipment
w formacie JSON (przesyłka Paczkomat®).
{ "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.
Aby pobrać listę przesyłek dla określonej organizacji, użytkownik musi być jej członkiem.
GET /v1/organizations/:organization/shipments |
Przykładowe zapytanie
curl -X GET https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments -H 'Authorization: Bearer token' -H 'Content-Type: application/json' |
Odpowiedź
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/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", }] } |
Informacje o błędach
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.
- No labels