Form validation

When sending a request, the values provided are subject to validation, ensuring that the transferred data are consistent with the assumptions of the platform receiving the request.

Data that does not fulfil the validation assumptions are not saved by the platform. In such case, the user is informed by a legible return message.

The resource has information concerning validation of the forms used in ShipX.

On this page

1 Custom Attributes Form
2 Insurance Form
3 Parcels Simple Form
4 Dimensions Simple Form
5 Weight Simple Form
6 Receiver Form
7 Sender Form
8 Address Form
9 Create Address Form
10 Cod Form
11 Shipment Select Offers Form
12 Bulk Buy Shipments Form
13 Format Parameters Form
14 Mapping Form
15 HTTP Status codes
16 Errors
- 16.1 Error Keys
- 16.2 Validation error keys

Custom Attributes Form

Attribute	Type	Validation

Attribute

Type

Validation

target_point

String

The attribute is required for the following services:
inpost_locker_standard, inpost_locker_allegro, inpost_locker_pass_thru, inpost_letter_allegro.

dropoff_point

String

The attribute is required for the following services:
inpost_locker_pass_thru inpost_letter_allegro.

Attribute is not required, dropoff_point attribute is required together with sending_method attribute

The above condition is required only for the following values of sending_method attribute (parcel_locker, pok, courier_pok)

sending_method

String

Attribute is not required, acceptable values (parcel_locker, pok, pop, courier_pok, branch, dispatch_order), empty value allowed

Insurance Form

Attribute	Type	Validation

Attribute

Type

Validation

insurance_amount

Decimal

The attribute is required for the following services:
inpost_courier_standard, inpost_courier_express_1000, inpost_courier_express_1200, inpost_courier_express_1700, inpost_courier_palette when passing the COD attribute.

Attribute is not required, greater than or equal to 1, less than 10000000

insurance_currency

String

Attribute is not required, default value: PLN

Parcels Simple Form

Attribute	Type	Validation

Attribute	Type	Validation
`template`	String	Attribute is not required
`dimensions`	Dimensions Simple Form	Attribute is not required, it becomes required when the `template` attribute is not provided
`weight`	Weight Simple Form	Attribute is not required, it becomes required when the `template` attribute is not provided
`id`	String	Attribute is not required When passing a collection of parcels, it is required to pass the `id` attribute. If the `id` attribute is not passed, or if it is not unique in scope of the request, the user will receive validation message.
`is_non_standard`	Boolean	Attribute is not required, default value: `null`

Dimensions Simple Form

Attribute	Type	Validation

Attribute	Type	Validation
`height`	Float	Attribute is required, greater than or equal to 1, less than 1000000, empty value allowed
`length`	Float	Attribute is required, greater than or equal to 1, less than 1000000, empty value allowed
`width`	Float	Attribute is required, greater than or equal to 1, less than 1000000, empty value allowed
`unit`	String	Attribute is not required, default value: mm

Weight Simple Form

Attribute	Type	Validation

Attribute	Type	Validation
`amount`	Float	Attribute is required, greater than or equal to 1, less than 10000000, empty value allowed
`unit`	String	Attribute is not required, default value: kg

Receiver Form

Attribute	Type	Validation

Attribute	Type	Validation
`company_name`	String	Attribute is not required, it becomes required when `first_name,last_name,` `address` attributes are not provided maximum length 255.
`email`	String	Attribute is required only for parcel locker shipments, in other cases attribute is not required
`phone`	String	Attribute is required. Only 9 digits (333222111)
`address`	Address Form	Attribute is required
`first_name`	String	Attribute is not required, it becomes required when `company_name`, `email,` `phone` attributes are not provided
`last_name`	String	Attribute is not required, it becomes required when `company_name`, `email,` `phone` attributes are not provided

Sender Form

Attribute	Type	Validation

Attribute	Type	Validation
`company_name`	String	Attribute is not required, it becomes required when `first_name,` `last_name` attributes are not provided
`email`	String	Attribute is not required, empty value allowed
`phone`	String	Attribute is required. Only 9 digits (333222111)
`address`	Address Form	Attribute is required
`first_name`	String	Attribute is not required, it becomes required when `company_name,` `first_name,` `last_name` attributes are not provided
`last_name`	String	Attribute is not required, it becomes required when `company_name,` `first_name,` `last_name` attributes are not provided

Address Form

Attribute	Type	Validation

Attribute	Type	Validation
`line1`	String	Attribute is not required
`city`	String	Attribute is not required
post_code	String	Attribute is not required
country_code	String	Attribute is not required
street	String	Attribute is not required
building_number	String	Attribute is not required

Create Address Form

Attribute	Type	Validation

Attribute	Type	Validation
`street`	String	Attribute is required, maximum length 255, It is a condition for attribute validation that attributes are not passed `line1` / `line2` or `building_number`
`building_number`	String	Attribute is required, maximum length 255, It is a condition for attribute validation that attributes are not passed `line1` / `line2` or `street`
`line1`	String	Attribute is required, maximum length 255, It is a condition for attribute validation that attributes are not passed `line2`
`line2`	String	Attribute is not required, maximum length 255
`city`	String	Attribute is required, maximum length 255
`post_code`	String	Attribute is required, address format according to the address convention of the post office in the user's country
`country_code`	String	Attribute is not required, minimum length 2, maximum length 3

Cod Form

Attribute	Type	Validation

Attribute	Type	Validation
`cod_amount`	Decimal	Attribute is not required, greater than or equal to 1, less than `10000000`
`cod_currency`	String	Attribute is not required, default value: PLN

Shipment Select Offers Form

Attribute	Type	Validation

Attribute	Type	Validation
`id`	String	Attribute is not required
`shipment_id`	Integer	Attribute is required, acceptable format `Integer`
`offer_id`	Integer	Attribute is required, acceptable format `Integer`

Bulk Buy Shipments Form

Attribute	Type	Validation

Attribute	Type	Validation
`id`	String	Attribute is not required
`shipment_id`	Integer	Attribute is required
`offer_id`	Integer	Attribute is required

Format Parameters Form

Attribute	Type	Validation

Attribute	Type	Validation
`field_separator`	String	Attribute is not required
`character_encoding`	String	Attribute is not required
`text_qualifier`	String	Attribute is not required
`sheets_index`	Array[Integer]	Attribute is not required

Mapping Form

Attribute	Type	Validation

Attribute	Type	Validation
`custom_attributes`	String	Attribute is not required, default value: null
`insurance`	String	Attribute is not required, default value: null
`cod`	String	Attribute is not required, default value: null
`additional_services`	String	Attribute is not required, default value: null
`service`	String	Attribute is not required, default value: null
`parcels`	String	Attribute is not required, default value: null
`receiver`	String	Attribute is not required, default value: null
`sender`	String	Attribute is not required, default value: null

HTTP Status codes

List of HTTP status codes which may occurs in response:

HTTP status code	Description

HTTP status code	Description
`200 OK`	Successful request.
`201 CREATED`	New resource is created.
`204 NO CONTENT`	Server successfully processed the request, and is not returning any content.
`400 BAD REQUEST`	Server cannot process the request. More info in response.
`401 UNAUTHORIZED`	Proper authorization is required to access this resource.
`403 FORBIDDEN`	Access to the requested resource is forbidden
`404 NOT FOUND`	Resource is not found.
`500 SERVER ERROR`	The server failed to fulfil a request

Errors

If error occurs, API will return object with following attributes:

Attribute	Type	Description

Attribute	Type	Description
`status`	Integer	HTTP status code
`error`	String	Error key
`message`	String	Easy to understand description of error. It may change - do not base on it in your code.
`details`	Object	Details of the error which occurred.

Response example

HTTP/1.1 404 Not Found
 
{
	"status": 404,
	"error": "resource_not_found",
	"message": "Resource you are looking for are not found",
	"details: {}
}

In POST or PUT query - validation errors may occur. Details about them are placed in "details" attribute.

HTTP/1.1 400 Bad Request
 
{
	"status": 400,
	"error": "validation_failed",
	"message": "Data sent by POST or PUT request are not valid. Check details for more info",
	"details: {
		"name": ["required", "too_short"],
		"post_code": ["invalid_format"]
	}
}

Names of attributes with validation errors are keys for details object. Their value is a table with error keys which occured. Error keys are described below.

Error Keys

The table below shows the error keys that may occurs with possible HTTP codes.

Error key	HTTP Code	Description

Error key	HTTP Code	Description
`resource_not_found`	`404`	The resource you are looking for was not found
`validation_failed`	`400`	There were validation errors when sending data via POST or PUT. More info in "details".
`unauthorized`	`401`	Access to the resource is impossible due to lack of or incorrect access token.
`access_forbidden`	`403`	Access to the specified resource is denied due to lack of or incorrect permissions.

Validation error keys

The table below shows the validation error keys that may occurs in details attribute if validation is failed.

Error key	Description

Error key	Description
`required`	Value is required.
`invalid`	Value is invalid, more info in resource documentation.
`too_short`	Value is too short, more info in resource documentation.
`too_long`	Value is too long.
`too_small`	Value is too small, it concerns to numerical value.
`too_big`	Value is too big, it concerns to numerical value.
`invalid_format`	Given value has an invalid format, e.g word in phone number field.

Besides the above errors, there may be others, for specific resources. More details in documentation specific to these resources.