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

The shipment object is used to obtain available offers, and at the same time it represents the physical pack (or parcels) which will be sent between the stated addresses.


POST /v1/organizations/:organization_id/shipments

Rights

To create a shipment within the given organization, the user needs to be a member thereof.

All the following parameters should be included in the shipment object.

ParameterTypeDescriptionValidation
receiverReceiverForm

Parcel recipient's data.

The attribute is required.

• if a courier service offer is to be presented, specify at least receiver.company_name and/or receiver.first_name and receiver.last_name and the address object,
if a parcel station offer is to be presented, provide receiver.phone number and receiver.email,
• providing all data will allow both types of offers to be presented.
• if "sms", or "email" are given in additional_services, then it is likewise required to specify phone, or email
• if the is return == true attribute is provided, the receiver attribute will not be required

senderSenderFormParcel sender's data.

The attribute is not required.

• If no data are provided, the data of the organization under which the shipment is being created will be used by default.

parcelsArray[ParcelsSimpleForm]

Data of the parcels included in the shipment.

  • The attribute is required.
    • Collection minimum 1, maximum 1000

custom_attributesCustomAttributesForm

Additional shipment attributes.

The attribute is not required.

• The list of additional attributes has been described in the introduction.
• It is required to specify the parcel station in the case of a parcel station shipment.

codCodFormCollection amount.

The attribute is not required.

• Attribute validation and required provision are defined at the time of providing the service.

insuranceInsuranceFormShipment insurance amount.

The attribute is not required.

• Attribute validation and required provision are defined at the time of providing the service.

referenceStringAdditional shipment description, e.g. order number.

The attribute is not required.
• Minimum 3 characters, maximum 100 characters, possibility to provide an empty attribute.

is_returnBoolDetermines the shipment as a return shipment.

The attribute is not required.

• Acceptable values (true, false)
• Possibility to provide an empty attribute.
• If set to true, specifies the shipment as a return shipment. In such situation, the places of the sender's and the recipient's data will be automatically switched.

additional_servicesArray[String]

Additional services.
Available additional services: sms, e mail, saturday.

Sizes and services for shipments 

The attribute is not required.

• Attribute validated at the time of providing the value.
• When the additional_services attribute is provided, the system checks the service attribute provision, if the service attribute is not provided or the additional_services attribute does not fit in the scope of the service provided, the user will get an error.

external_customer_id
StringID of the broker generating shipments within a different organizationThe attribute is not required.
only_choice_of_offerBoolean

Setting the parameter to true makes the offer in all shipments being selected for the stated service, but it will not be automatically paid. Such shipment has to be paid for before the end of the offer's validity term by completing the operations(Paying for shipment). 

This parameter can also be set separately for each shipment (in such
case the parameter set in the shipment has a higher priority).

The attribute is not required.

• Default value false

mpkStringName of cost center.

The attribute is not required.

• maximum 255 characters
• if the attribute is specified, we verify whether it belongs to the organization which the request is made from
• possibility to provide an empty attribute
The cost center must first be added to the organization in order to assign it to the shipment.


commentsStringAny comment

The attribute is not required.

• maximum 100 characters
• possibility to provide an empty attribute

Note! Debit clients

After creating a shipment, we do not return prices for debit clients.
The rate attribute takes the null value


Sample request

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


In the response the server will return status 201 along with the newly created shipment object.

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

Sample request with many parcels (multi-packs may be created only for 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": {
		"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"
	}
}

Note! Asynchronous action.

After creating a shipment, an asynchronous offer preparation process will be started.

In order to obtain information about completing offer preparation for the shipment, the URL address should be defined in the organization's configuration which information is to be sent to for the offers_prepared event. In this way, the ShipX application will send the following information to the stated address:

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

The prepared offers are valid for 5 minutes. After that time, the offers will change their status to expired and it will not be possible to buy them. To prepare new offers, send a shipment edit request without specifying any data.

Errors which may occur when creating a shipment:

• validation_failed - sent parameters are incorrect. Details contained in the details field,
• resource_not_found - in the event that the user tries to create a shipment for an organization that does not exist or has no right to create it,
• no_carriers - in the event that the organization has no agreement signed with any carrier.

  • No labels