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.


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.

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.