[1.23.0] API ShipX International Documentation ENG

 

Ship X API is the main interface for exchanging data with the central system.

Access to data is protected, authorization mechanism is based on OAuth 2.0 standard.

Requests are authenticate by Bearer token. API is stateless interface.

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

1 2 3 4 5 6 7 8 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.

1 2 3 4 5 6 7 8 9 10 11 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.