Tworzenie przesyłki w trybie ofertowym

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.

Na tej stronie

1 Uwierzytelnianie
2 Tworzenie przesyłki w trybie ofertowym
3 Asynchroniczne przygotowanie ofert

Uwierzytelnianie

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

Tworzenie przesyłki w trybie ofertowym

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

Po utworzeniu przesyłki nie zwracamy cen dla klientów debetowych. Atrybut rate przyjmuje wartość null

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

POST /v1/organizations/:organization_id/shipments

Parametry

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

Parametr	Typ	Opis	Walidacja

Parametr	Typ	Opis	Walidacja
`receiver`	ReceiverForm	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 Paczkomat® należy podać `receiver.phone_number` i `receiver.email`, Podanie wszystkich danych umożliwi przedstawienie ofert obu typów. Jeśli w `additional_services` podane zostaną "sms", lub "email", to analigocznie wymagane jest podanie `phone`, lub `email` Jeśli zostanie przekazany atrybut `is_return = true`, atrybut `receiver` nie będzie wymagany
`sender`	SenderForm	Dane 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.
`parcels`	Array[ParcelsSimpleForm]	Dane paczek zawartych w przesyłce.	Atrybut jest wymagany. Kolekcja minimum 1, maksimum 1000
`custom_attributes`	CustomAttributesForm	Dodatkowe atrybuty przesyłki.	Atrybut nie jest wymagany. Lista dodatkowych atrybutów została opisana we wstępie. Wymagane jest podanie Paczkomat® w przypadku przesyłki Paczkomat®.
`cod`	CodForm	Wartość pobrania.	Atrybut nie jest wymagany. Walidacja oraz wymagalność przekazania atrybutu występuje w momencie przekazania serwisu.
`insurance`	InsuranceForm	Kwota ubezpieczenia przesyłki.	Atrybut jest wymagany dla poniższych serwisów: `inpost_courier_standard`, `inpost_courier_express_1000`, `inpost_courier_express_1200`, `inpost_courier_express_1700`, `inpost_courier_palette` w przypadku przekazania atrybutu `COD`. Walidacja oraz wymagalność przekazania atrybutu występuje w momencie przekazania serwisu.
`reference`	String	Dodatkowy opis przesyłki, np. numer zamówienia.	Atrybut nie jest wymagany. Minimum 3 znaki, maksimum 100 znaków, możliwość przekazania pustego atrybutu.
`is_return`	Bool	Okreś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.
`additional_services`	Array[String]	Usługi dodatkowe. Dostępne usługi dodatkowe: `sms`, `email`, `saturday`. 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`	String	Identyfikator broker'a generującego przesyłki w ramach innej organizacji	Atrybut nie jest wymagany.
`only_choice_of_offer`	`Boolean`	Ustawienie parametru na `true` powoduje, że oferta we wszystkich przesyłkach zostanie wybrana dla podanego serwisu, ale nie zostanie automatycznie opłacona. Taką przesyłkę należy opłacić przed końcem wygaśnięcia oferty, wykonując operacje Opłacanie przesyłki. Parametr ten można ustawić również dla każdej przesyłki z osobna (w takim przypadku parametr ustawiony w przesyłce ma wyższy priorytet).	Atrybut nie jest wymagany. Defoultowa wartość `false`
`mpk`	String	Nazwa miejsca 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.
`comments`	String	Dowolny komentarz	Atrybut nie jest wymagany. Maksymalnie 100 znaków Minimalnie 3 znaki Możliwość przekazania pustego atrybutu

Przykładowe zapytanie

Przykładowe zapytanie z jedną paczką:

curl -X POST https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments -H 'Authorization: Bearer token' -H 'Content-Type: application/json' -d '{
    "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"
	},
	"additional_services": ["email", "sms"]
}'

Odpowiedź

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
		}
	],
	"external_customer_id": "8877xxx",
	"mpk": {
       "id": 1,
       "name": "miejsce_powstania_kosztow"
    },
	"comments": "dowolny komentarz",
 	"custom_attributes": {
		"target_point": "KRA010",
		"open_code": null,
		"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": "1234",
		"name": "Nazwa",
		"company_name": null,
		"first_name": "Jan",
		"last_name": "Kowalski",
		"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": [],
	"mpk": {
        "id": 1,
        "name": "Nazwa miejsca powstania kosztów."
    }
}

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

curl -X POST https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments -H 'Authorization: Bearer token' -H 'Content-Type: application/json' -d '{
	"receiver": {
		"first_name": "Jan",
        "last_name": "Kowalski",
		"email": "receiver@example.com",
		"name": "Nazwa",
		"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
		},
		{
			"id": "big package",
			"template": "large",
			"dimensions": {
				"length": "160",
				"width": "720",
				"height": "640",
				"unit": "mm"
			},
			"weight": {
				"amount": "50",
				"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"
	}
}'

Informacje o błędach

Błędy, jakie mogą wystąpić podczas tworzenia przesyłki:

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.

Asynchroniczne przygotowanie ofert

Po utworzeniu przesyłki zostanie uruchomiony asynchroniczny proces przygotowywania ofert. Przygotowane oferty ważne są przez 5 minut. Po tym czasie oferty zmienią swój status na expired i nie będzie możliwy ich zakup. Aby przygotować nowe oferty, należy wysłać żądanie edycji przesyłki nie podając żadnych danych.

Aby otrzymać informację o zakończeniu przygotowywania ofert dla przesyłki, należy zdefiniować w konfiguracji organizacji adres url, pod który mają być wysyłane informacje dla zdarzenia offers_prepared. Dzięki temu aplikacja ShipX wyśle na podany adres następujące informacje:

POST http://{{adres_podany_w_konfiguracji}}
Content-Type: application/json
 {
	"event_ts": "2015-12-09 14:55:06 +0100",
	"event": "offers_prepared",
	"organization_id": 1,
	"payload": {
		"shipment_id": 460,
		"offers": [
    		{
      			"id": 1281,
      			"carrier": {
					"id": "inpost_courier",
        			"name": "InPost Express",
					"description": "InPost Express - Przesyłki kurierskie."
      			},
      			"service": {
        			"id": "inpost_courier_express_1200",
        			"name": "Kurier Doręczenie 12:00",
					"description": "Przesyłka kurierska z doręczeniem do godziny 12:00 następnego dnia."
      			},
				"additional_services": ["email", "sms"],
      			"status": "available",
				"expires_at": "2016-06-24T12:39:43.734+02:00",
      			"rate": 17,
      			"currency": "PLN",
      			"unavailability_reasons": null
    		},
    		{
      			"id": 1280,
      			"carrier": {
        			"id": "inpost_courier",
        			"name": "InPost Express",
					"description": "InPost Express - Przesyłki kurierskie."
      			},
      			"service": {
        			"id": "inpost_courier_express_1700",
        			"name": "Kurier Doręczenie 17:00",
					"description": "Przesyłka kurierska z doręczeniem do godziny 17:00 następnego dnia."
      			},
				"additional_services": ["email", "sms"],
      			"status": "available",
				"expires_at": "2016-06-24T12:39:43.734+02:00",
      			"rate": 17,
      			"currency": "PLN",
      			"unavailability_reasons": null
    		},
    		{
      			"id": 1279,
      			"carrier": {
        				"id": "inpost_courier",
        				"name": "InPost Express",
						"description": "InPost Express - Przesyłki kurierskie."
      			},
      			"service": {
        				"id": "inpost_courier_standard",
						"name": "Kurier Standard",
						"description": "Przesyłka kurierska standardowa."
      			},
				"additional_services": ["email", "sms"],
      			"status": "available",
				"expires_at": "2016-06-24T12:39:43.734+02:00",
      			"rate": 17,
      			"currency": "PLN",
      			"unavailability_reasons": null
    		},
    		{
      			"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."
      			},
				// Oferta paczkomatowa nie zawiera wybranych usług dodatkowych, ponieważ są one zawarte w usłudze podstawowej (email, sms) albo są niedostępne (saturday)
				"additional_services": [],
      			"status": "available",
				"expires_at": "2016-06-24T12:39:43.734+02:00",
      			"rate": 2.02,
      			"currency": "PLN",
      			"unavailability_reasons": null
    		}
		]
	}
}