[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

1 Diagram tworzenia przesyłki
2 Struktura
3 Uwierzytelnianie
4 Lista przesyłek Organizacji
- 4.1 Przykładowe zapytanie

Diagram tworzenia przesyłki

Struktura

Zasób Shipment posiada następujące atrybuty:

Atrybut	Typ	Opis

Atrybut	Typ	Opis
`id`	Integer	Tylko do odczytu. Identyfikator przesyłki w platformie Ship X.
`status`	String	Tylko do odczytu. Aktualny status przesyłki.
`custom_attributes`	CustomAttributes	Dodatkowe, opcjonalne atrybuty dla przesyłki.
`parcels`	Array[Parcel]	Lista paczek w ramach przesyłki.
`created_at`	DateTime	Tylko do odczytu. Data utworzenia przesyłki w systemie Ship X.
`created_by_id`	Integer	Id użytkownika, który utworzył przesyłkę, jeśli użytkownik jest zalogowany.
`sender`	Peer	Dane nadawcy.
`receiver`	Peer	Dane odbiorcy.
`cod`	MoneyData	Pobranie za przesyłkę.
`insurance`	MoneyData	Ubezpieczenie przesyłki.
`additional_services`	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: `sms`, `email`, `saturday`. https://dokumentacja-inpost.atlassian.net/wiki/spaces/PL/pages/11731062
`reference`	String	Dodatkowy opis dla przesyłki, np. numer zamówienia lub ID klienta.
`is_return`	Bool	Określa czy przesyłka jest zwrotna.
`offers`	Array[Offer]	Lista dostępnych usług wraz z cenami, które możliwe są do nabycia w ramach tej przesyłki.
`selected_offer`	Offer	Usługa, która została wybrana podczas kupowania etykiety dla przesyłki.
`transactions`	Array[Transaction]	Lista transakcji płatniczych związanych z daną przesyłką.
`tracking_number`	String	Numer trackingowy przesyłki (identyfikator na poziomie systemu logistycznego).
`sending_method`	String	Powielenie pola z `custom_attributes`.
`external_customer_id`	String	Identyfikator broker'a generującego przesyłki w ramach innej organizacji.

Atrybuty obiektu Parcel

Atrybut	Typ	Opis

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 https://dokumentacja-inpost.atlassian.net/wiki/spaces/PL/pages/11731062 .
`dimensions`	Object	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`	Object	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`	String	Numer danej przesyłki. Nadawany w trakcie kupowania wybranej oferty.
`is_non_standard`	Bool	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.

Struktura obiektu Offer

Atrybut	Typ	Opis

Atrybut	Typ	Opis
`id`	Integer	Unikalny identyfikator usługi oferowanej w ramach przesyłki
`service`	Service	Obiekt oferowanej usługi.
`carrier`	Carrier	Obiekt przewoźnika.
`additional_services`	Array[String]	Usługi dodatkowe wybrane przy tworzeniu przesyłki - dostępne w danej ofercie.
`status`	String	Status oferty. Możliwe statusy oferty: `in_preparation`, `available`, `unavailable, selected, bought, expired`
`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.

Struktura obiektu Service

Atrybut	Typ	Opis

Atrybut	Typ	Opis
`id`	String	Identyfikator usługi
`name`	String	Nazwa usługi
`description`	String	Opis usługi

Struktura obiektu Carrier

Atrybut	Typ	Opis

Atrybut	Typ	Opis
`id`	String	Identyfikator przewoźnika
`name`	String	Nazwa przewoźnika
`description`	String	Opis przewoźnika

Struktura obiektu Transaction

Atrybut	Typ	Opis

Atrybut	Typ	Opis
`id`	String	Identyfikator transakcji
`status`	String	Status transakcji. Możliwe statusy: `initiated`, `success`, `failure`
`created_at`	DateTime	Data utworzenia transakcji.
`updated_at`	DateTime	Data ostatniej modyfikacji transakcji.
`offer_id`	Integer	Id oferty, której transakcja dotyczy.

Atrybuty obiektu Peer

Atrybut	Typ	Opis

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`	Address	Adres

Atrybuty obiektu Address

Atrybut line1 i line2 jest jeszcze wspierany, jednak zalecane jest używanie street i building_number.

Atrybut	Typ	Opis

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

Atrybuty obiektu MoneyData

Atrybut	Typ	Opis

Atrybut	Typ	Opis
`amount`	Decimal	Kwota
`currency`	String	Waluta

Atrybuty obiektu CustomAttributes

Atrybut	Typ	Opis

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 Paczkomat®. Tylko przesyłki Paczkomat®.
`sending_method`	String	https://dokumentacja-inpost.atlassian.net/wiki/spaces/PL/pages/11731047 Wymagane dla przesyłek Allegro.
`dropoff_point`	String	Nazwa punktu nadawczego, do którego nadawca dostarczy przesyłkę do wysłania, np. nazwa Paczkomat®. Wymagane przy podaniu metody nadania `pok`, `courier_pok`, `parcel_locker`.
`allegro_transaction_id`	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 `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 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",
}

Uwierzytelnianie

Dostęp do zasobu wymaga podania prawidłowego i ważnego access tokenu.

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.