Page tree
Skip to end of metadata
Go to start of metadata

 

Obiekt przesyłki wykorzystywany jest do uzyskania dostępnych ofert, a jednocześnie reprezentuje ona fizyczną paczkę (lub paczki), która będzie przesłana pomiędzy określonymi adresami. 

POST /v1/organizations/:organization_id/shipments

Uprawnienia

Aby utworzyć przesyłkę w ramach określonej organizacji, użytkownik musi być jej członkiem.

Parametry

Wszystkie poniższe parametry powinny być zawarte w obiekcie shipment.

ParametrTypOpisWalidacja
receiverReceiverForm

Dane odbiorcy paczki

Atrybut jest wymagany.

  • jeśli ma być przedstawiona oferta usługi kurierskiej, należy podać co najmniej receiver.company_name i/lub receiver.first_name i receiver.last_name oraz obiekt address
  • jeśli ma być przedstawiona oferta paczkomatowa należy podać receiver.phone_number i receiver.email
  • podanie wszystkich danych umożliwi przedstawienie ofert obu typów
  • jeśli zostanie przekazany atrybut is_return == true, atrybut receiver nie będzie wymagany
senderSenderFormDane nadawcy paczki.

Atrybut nie jest wymagany.

  • Jeśli nie zostaną podane żadne dane, domyślnie zostaną użyte dane organizacji, w ramach której tworzona jest przesyłka.
parcelsArray[ParcelsSimpleForm]

Dane paczek zawartych w przesyłce.

Atrybut jest wymagany.

  • Kolekcja minimum 1, maksimum 1000
custom_attributesCustomAttributesForm

Dodatkowe atrybuty przesyłki, np.

"custom_attributes": {
"target_point": "KRA010"
}

Atrybut nie jest wymagany.

  • Lista dodatkowych atrybutów została opisana we wstępie.
  • Wymagane jest podanie paczkomatu w przypadku przesyłki paczkomatowej.
codCodFormWartość pobrania.

Atrybut nie jest wymagany.

  • Walidacja oraz wymagalność przekazania atrybutu występuje w momencie przekazania serwisu.
insuranceInsuranceFormKwota ubezpieczenia przesyłki.

Atrybut nie jest wymagany.

  • Walidacja oraz wymagalność przekazania atrybutu występuje w momencie przekazania serwisu.
referenceStringDodatkowy opis przesyłki, np. numer zamówienia.

Atrybut nie jest wymagany.

  • Minimum 3 znaki, maksimum 100 znaków, możliwość przekazania pustego atrybutu.
is_returnBoolOkreśla przesyłkę jako zwrotną.

Atrybut nie jest wymagany.

  • Dopuszczalne wartości (true, false)
  • Możliwość przekazania pustego atrybutu.
  • Jeśli ustawione na true, określa przesyłkę jako zwrotną. W takiej sytuacji dane nadawcy i odbiorcy zostaną automatycznie zamienione miejscami.
serviceString

Wybrana przez klienta usługa.

Dostępne wartości patrz API X Rozmiary i usługi dla przesyłek.

Atrybut jest wymagany.

 

additional_servicesArray[String]

Usługi dodatkowe.

Dostępne usługi dodatkowe: smsemailsaturday.

API X Rozmiary i usługi dla przesyłek 

Atrybut nie jest wymagany.

  • Atrybut walidowany w momencie przekazania wartości.
  • Przekazując atrybut additional_services system sprawdza przekazanie atrybutu service, jeśli atrybut service nie zostanie przekazany lub przekazany atrybut additional_services nie mieści się w zakresie przekazanego serwisu, użytkownik otrzyma błąd.
external_customer_id
StringIdentyfikator broker'a generującego przesyłki w ramach innej organizacji.Atrybut nie jest wymagany.
only_choice_of_offerBooleanUstawienie parametru na truepowoduje że oferta zostanie wybrana dla podanego serwisu, ale nie zostanie automatycznie opłacona. Taka przesyłkę trzeba opłacić przed końcem wygaśnięcia oferty wykonując operacje (Opłacanie przesyłki)

Atrybut nie jest wymagany.

 

 

tracking_number

 

String

Numer paczki.
Aby móc nadawać numer paczki, należy posiadać odpowiednie uprawnienia.
Numery paczek można nadawać tylko dla przesyłek paczkomatowych. 

Atrybut nie jest wymagany.

  • Atrybut walidowany w momencie przekazania wartości.
  • Możliwość przekazania pustego atrybutu.
  • Atrybut jest walidowany na podstawie przypisanego do organizacji wyrażenia regularnego, jeśli ogranizacja posiada odpowiednie uprawnienia.
mpkStringMiejsce powstania kosztów

Atrybut nie jest wymagany.

  • maksymalnie 255 znaków
  • jeśli atrybut jest podany, weryfikujemy czy przynależy do organizacji, z której wykonywane jest żądanie
  • możliwość przekazania pustego atrybutu

Miejsce powstania kosztów musi najpierw być dodane do organizacji, aby można je było przypisać do przesyłki.

commentsStringDowolny komentarz

Atrybut nie jest wymagany

  • maksymalnie 100 znaków
  • możliwość przekazania pustego atrybutu

 

Przykładowe zapytanie

POST /v1/organizations/123/shipments HTTP/1.1
Host: api-shipx-pl.easypack24.net
Content-Type: application/json
Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]...
 
{
	"mpk":"miejsce_powstania_kosztow",
	"comments": "dowolny komentarz",
    "external_customer_id": "8877xxx",
	"receiver": {
		"first_name": "Jan",
        "last_name": "Kowalski",
		"name": "Nazwa",
		"email": "receiver@example.com",
		"phone": "888000000",
		"address": {
            "id": "123",
            "street": "Malborska",
            "building_number": "130",
            "city": "Kraków",
            "post_code": "30-624",
            "country_code": "PL"
        }
	},
	"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"
	},
	"insurance": {
		"amount": 25,
		"currency": "PLN"
	},
	"cod": {
		"amount": 12.50,
		"currency": "PLN"
	},
    "service": "inpost_courier_standard",
	"additional_services": ["email", "sms"],
	"mpk": "Nazwa miejsca powstania kosztów."
}

 

W odpowiedzi serwer zwróci status 201 wraz z obiektem nowo utworzonej przesyłki.

HTTP/1.1 201 CREATED
Content-Type: application/json
 
{
	"href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments/1234567890",
	"id": "1234567890",
	"status": "created",
	"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
		}
	],
 	"mpk": {
       "id": 1,
       "name": "miejsce_powstania_kosztow"
    },
	"comments": "dowolny komentarz",
	"custom_attributes": {
		"target_point": "KRA010",
		"dropoff_point": null,
		"sending_method": "parcel_locker"
	},
	"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",
    "created_by_id": 3,
    "cod_amount": {
		"amount": 12.50,
		"currency": "PLN"
	},
	"insurance": {
		"amount": 25,
		"currency": "PLN"
	},
    "additional_services": ["email", "sms"],
	"reference": "Order No. 12345",
	"is_return": false,
	"tracking_number": null,
	"offers": [],
	"selected_offer": null,
	"transactions": [],
    "external_customer_id": "8877xxx"
}

Przykładowe zapytanie z wieloma paczkami (wielopaki można tworzyć tylko dla inpost_courier):

POST /v1/organizations/123/shipments HTTP/1.1
Host: api-shipx-pl.easypack24.net
Content-Type: application/json
Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]...
 
{
	"receiver": {
		"email": "receiver@example.com",
		"phone": "888000000",
		"name": "Nazwa"
	},
	"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
		},
		{
			"id": "big package",
			"template": "large",
			"dimensions": {
				"length": "160",
				"width": "720",
				"height": "840",
				"unit": "mm"
			},
			"weight": {
				"amount": "50",
				"unit": "kg"
			},
			"tracking_number": null,
            "is_non_standard": false
		}
	],
	"custom_attributes": {
		"target_point": "KRA010",
		"sending_method": "parcel_locker"
	},
	"insurance": {
		"amount": 25,
		"currency": "PLN"
	},
	"cod": {
		"amount": 12.50,
		"currency": "PLN"
	},
    "service": "inpost_courier_standard"
}

Uwaga! Działanie asynchroniczne.

Po utworzeniu przesyłki zostanie uruchomiony asynchroniczny proces przygotowywania ofert, manifestacji oraz kupienia oferty.

 

Aby otrzymać informację o zakończeniu procesu, należy zdefiniować w konfiguracji organizacji adres url (webhook), pod który mają być wysyłane informacje dla zdarzeń offers_prepared i/lub shipment_confirmed. Dzięki temu, aplikacja ShipX wyśle na podany adres informacje.

 

Błędy, jakie mogą wystąpić podczas tworzenia przesyłki (poniższe błędy są wysyłane do aplikacji która wysłała żądanie, nie na webhook):

  • validation_failed - przesyłane parametry są niepoprawne. Szczegóły zawarte w polu details,
  • resource_not_found - w przypadku gdy użytkownik próbuje utworzyć przesyłkę dla organizacji, która nie istnieje lub nie ma uprawnień do jej utworzenia,
  • no_carriers - w przypadku gdy organizacja nie ma podpisanej umowy z żadnym przewoźnikiem,
  • carrier_unavailable - w przypadku gdy organizacja nie ma podpisanej umowy z przewoźnikiem świadczącym wybraną usługę wskazaną w atrybucie service

 

Tworzenie rozmiaru przesyłki w trybie uproszczonym, na podtsawie przekazywanych parametrów

Na temat rozmiarów można przczytać w osobnym dokumencie

Aplikacja umożiwia wygenerowanie przesyłki z rozmiarem, bez podawania jego nazwy. Rozmiar generowany jest na podstawie przekazywanych parametrów,

poniżej został umieszczony przykład:

 "parcels": { 
    	"dimensions": {
            "length": "120",
            "width": "34",
            "height": "81",
            "unit": "mm"
            },
            "weight": {
                "amount": "20",
                "unit": "kg"
            } }

Znalezienie odpowiedniego rozmiaru przesyłki, bez podawania jego nazwy, uwarunkowane jest przekazaniem wszystkich parametrów obiektów dimensions oraz weight

Poniższa tabela przedstawia warunki jakie należy spełnić, aby umożliwić wygenerowanie rozmiaru na podstawie przekazywanych parametrów.


Rozmiar przesyłkiSerwisParametr: Umowne przedziały i ich wartości
letter_a

inpost_letter_allegro

inpost_letter_ecommerce

lenght: 1 - 325

width: 1 - 230

height: 1 - 80

weight: 1 - 2

small

inpost_locker_standard

inpost_locker_allegro

inpost_locker_pass_thru

lenght: 1 - 380

width: 1 - 640

height: 1 - 80 (mniejsze lub równe 80)

weight: 0 - 25

medium

inpost_locker_standard

inpost_locker_allegro

inpost_locker_pass_thru

lenght: 1 - 380

width: 1 - 640

height: 81 - 190 (mniejsze lub równe 190)

weight: 0 - 25

large

inpost_locker_standard

inpost_locker_allegro

inpost_locker_pass_thru

lenght: 1 - 380

width: 1 - 640

height: 191 - 410 (mniejsze lub równe 410)

weight: 0 - 25

paletteinpost_courier_palette

lenght: 1 - 1800

width: 1 - 800

height: 1 - 1200

weight: 50 - 800

parcel

inpost_courier_standard

inpost_courier_express_1700

lenght: 1 - 2400

width: 1 - 2400

height: 411 - 3500 (mniejsze lub równe 3500)

weight: 0 - 50

parcelpozostałe serwisy

lenght: 1 - 2400

width: 1 - 2400

height: 411 - 3500 (mniejsze lub równe 3500)

weight: 0 - 30


 

 

  • No labels