[1.9.0] 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)
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 https://dokumentacja-inpost.atlassian.net/wiki/spaces/PL/pages/11731062
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:
| 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
| 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 https://dokumentacja-inpost.atlassian.net/wiki/spaces/PL/pages/11731062 . |
| 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
| 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
| String | Identyfikator usługi |
| String | Nazwa usługi |
| String | Opis usługi |
Struktura obiektu Carrier
| String | Identyfikator przewoźnika |
| String | Nazwa przewoźnika |
| String | Opis przewoźnika |
Struktura obiektu Transaction
| 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
| 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.
| String | Identyfikator obiektu adres |
line1 | String | Pierwsza linia adresu |
line2 | String | Druga linia adresu |
| String | Nazwa ulicy |
| String | Numer domu |
| String | Miasto |
| String | Kod pocztowy |
| String | Kod kraju |
Atrybuty obiektu MoneyData
| Decimal | Kwota |
| String | Waluta |
Atrybuty obiektu CustomAttributes
| 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. |
| String | https://dokumentacja-inpost.atlassian.net/wiki/spaces/PL/pages/11731047 Wymagane dla przesyłek Allegro. |
| String | Nazwa punktu nadawczego, do którego nadawca dostarczy przesyłkę do wysłania, np. nazwa paczkomatu. Wymagane przy podaniu metody nadania |
| 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 |
| 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 paczkomatowa).
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
{
"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.
1
GET /v1/organizations/:organization/shipments |
Przykładowe zapytanie
1
curl -X GET https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments -H 'Authorization: Bearer token' -H 'Content-Type: application/json' |
Odpowiedź
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
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.