- Created by anagorski, last modified by Michał Machowski on Aug 16, 2023
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 12 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 ShipX. |
| String | Tylko do odczytu. Aktualny status przesyłki. |
| String | Numer trackingowy przesyłki (identyfikator na poziomie systemu logistycznego). |
| String | Numer przesyłki zwrotnej, pojawi się tylko wtedy gdy przesyłka otrzyma status |
| String | Wybrana przez klienta usługa. Dostępne wartości [1.9.1] Rozmiary i usługi dla przesyłek. |
| String | Dodatkowy opis dla przesyłki, np. numer zamówienia lub ID klienta. |
| Boolean | Określa czy przesyłka jest zwrotna. |
| Integer | Unikalny identyfikator aplikacji. |
| Integer | Id użytkownika, który utworzył przesyłkę, jeśli użytkownik jest zalogowany. |
| String | Identyfikator broker'a generującego przesyłki w ramach innej organizacji. |
| String | Powielenie pola z |
| Boolean | Określa czy przesyłka posiada usługę “Paczka w Weekend”. |
| String | Dowolny komentarz. |
| String | Nazwa miejsca powstania kosztów. |
| 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: |
| CustomAttributes | Dodatkowe, opcjonalne atrybuty dla przesyłki. |
| MoneyData | Pobranie za przesyłkę. |
| MoneyData | Ubezpieczenie przesyłki. |
| Peer | Dane nadawcy. |
| Peer | Dane odbiorcy. |
| Offer | Usługa, która została wybrana podczas kupowania etykiety dla przesyłki. |
| Array[Offer] | Lista dostępnych usług wraz z cenami, które możliwe są do nabycia w ramach tej przesyłki. |
| Array[Transaction] | Lista transakcji płatniczych związanych z daną przesyłką. |
| Array[Parcel] | Lista paczek w ramach przesyłki. |
| DateTime | Tylko do odczytu. Data utworzenia przesyłki w systemie ShipX. |
| DateTime | Tylko do odczytu. Data aktualizacji przesyłki w systemie ShipX. |
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 | |
| 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/shipments/12345", "id": 12345, "status": "created", "tracking_number": null, "return_tracking_number": null, "service": "inpost_locker_standard", "reference": "Test", "is_return": false, "application_id": 25, "created_by_id": null, "external_customer_id": "8877xxx", "sending_method": "dispatch_order", "end_of_week_collection": false, "comments": null, "mpk": null, "additional_services": [], "custom_attributes": { "target_point": "KRA012", "sending_method": "dispatch_order" }, "cod": { "amount": 12.5, "currency": "PLN" }, "insurance": { "amount": 25.0, "currency": "PLN" }, "sender": { "id": 12345, "name": "Name", "company_name": "Company_name", "first_name": "first_name", "last_name": "last_name", "email": "test@grupainteger.pl", "phone": "321321321", "address": { "id": 1764397634, "street": "Czerniakowska", "building_number": "87A", "line1": null, "line2": null, "city": "Warszawa", "post_code": "00-718", "country_code": "PL" } }, "receiver": { "id": 12345, "name": "Name", "company_name": "Company name", "first_name": "Jan", "last_name": "Kowalski", "email": "test@inpost.pl", "phone": "111222333", "address": null }, "selected_offer": null, "offers": [], "transactions": [], "parcels": [ { "id": 12345, "identify_number": null, "tracking_number": null, "is_non_standard": false, "template": "small", "dimensions": { "length": 380.0, "width": 640.0, "height": 80.0, "unit": "mm" }, "weight": { "amount": 25.0, "unit": "kg" } } ], "created_at": "2023-08-16T10:53:47.958+02:00", "updated_at": "2023-08-16T10:53:47.958+02:00" } |
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