[1.3.0] Opłacanie przesyłki

Owned by anagorski (Unlicensed)
Jan 25, 2018
2 min read

 

Opłacanie przesyłki stworzonej w trybie ofertowym

POST /v1/shipments/:shipment/buy

Parametry

ParametrTypOpisWalidacja
offer_idintegerID oferty, która dostępna jest dla opłacanej przesyłki.

Atrybut jest wymagany

  • Oferta musi mieć status available lub selected (jeśli wcześniej podjęta była próba zakupu zakończona niepowodzeniem).
  • Dopuszczalny format integer

Przykładowe zapytanie

POST /v1/shipments/12345/buy HTTP/1.1
Host: api-shipx-pl.easypack24.net
Content-Type: application/json
Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]...
 
{
	"offer_id": 1456
}

W odpowiedzi serwer zwróci status 200 wraz z obiektem przesyłki:

HTTP/1.1 200 OK
Content-Type: application/json
 
{
	"href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments/1234567890",
	"id": "1234567890",
	"parcels": [
		{
			"id": "small package",
			"template": "small",
			"dimensions": {
				"length": "80",
				"width": "360",
				"height": "640",
				"unit": "mm"
			},
			"weight": {
				"amount": "25",
				"unit": "kg"
			},
			"tracking_number": null
		}
	],
	"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": {
		"amount": 12.50,
		"currency": "PLN"
	},
	"insurance": {
		"amount": 25,
		"currency": "PLN"
	},
	"reference": "Order No. 12345",
	"is_return": false,
	"tracking_number": null,
    "external_customer_id": "8877xxx",
	"offers": [
		{
    		"id": 1456,
    		"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": "selected",
			"valid_to": null,
    		"rate": 2.02,
    		"currency": "PLN",
    		"unavailability_reasons": null
		}
	],
	"selected_offer": {
    	"id": 1456,
    	"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": "selected",
		"valid_to": null,
    	"rate": 2.02,
    	"currency": "PLN",
    	"unavailability_reasons": null
	},
	"transactions": []
}

W momencie wyboru oferty, pozostałe - niewybrane oferty są usuwane.

Uwaga! Działanie asynchroniczne.

 Ponieważ zakup przesyłki działa asynchronicznie, serwer w odpowiedzi zwróci informacje o przesyłce nie uwzględniające zmian wywołanych przez zakup (zmiana statusu, nadanie numeru przewozowego), gdyż informacje te będą dostępne dopiero po pewnym czasie.

Aby otrzymać informację o pomyślnym zakupieniu przesyłki, należy zdefiniować w konfiguracji organizacji adres url, pod który mają być wysyłane informacje dla zdarzenia shipment_confirmed. 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-08 19:42:42 +0100",
	"event":"shipment_confirmed",
	"organization_id":1,
	"payload": {
		"shipment_id":1234567890,
		"tracking_number":"681549342531876019900138"
	}
}

 

Lista błędów, które mogą wystąpić przy opłacaniu przesyłki:

  • resource_not_found - może wystąpić gdy określona przesyłka nie istnieje lub użytkownik nie ma do niej dostępu,
  • offer_unavailable - występuje jeśli podejmowana próba opłacenia oferty w statusie innym niż available albo selected,
  • transaction_failed - może wystąpić jeżeli nie uda się opłacić przesyłki,
  • offer_expired - oferta nie może być zakupiona, ponieważ jej ważność wygasła (oferty ważne są przez 5 minut od ich przygotowania)