Page Comparison

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

Table of Contents

Tworzenie przesyłki w trybie ofertowym

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

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

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

Code Block

language	json

POST /v1/organizations/:organization_id/shipments

Parametry

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

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 paczkomatowa 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 paczkomatu w przypadku przesyłki paczkomatowej.
`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 nie jest wymagany. 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`. [1.9.1] 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 [1.3] 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 Możliwość przekazania pustego atrybutu

Przykładowe zapytanie

Przykładowe zapytanie z jedną paczką:

Code Block

language	json

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"],
	"mpk": "Nazwa miejsca powstania kosztów."
}'

Odpowiedź

Code Block

language	json

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):

Code Block

language	json

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"
	}
}'

Warning

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:

Code Block

language	json

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
    		}
		]
	}
}

Versions Compared

Old Version 7

New Version 8

Key

Uwierzytelnianie

Tworzenie przesyłki w trybie ofertowym

Asynchroniczne przygotowanie ofert