Consignment API

There are three ways to create Consignments in system :

1. To create a Consignment firstly, then add one or more SKUs to the Consignment, Finally updating the Status of Consignment to the PENDING, which is a status system ready to process.

2. The second way is, to create the Batch Consignments temporarily first, then batch converting those Batch Consignments to the final Consignments.

3. The third way is, to create a Consignment in a all-in-one API Request. This way is simplest way to create and manage Consignments via API, In addtion, under this way, the Status of Consignment will be updated to the PENDING straightway.

The detail of reference below :

1. Request and Credential

To interact with system's API you'll need both api_key and company_id, both are mandatory in all cases.

Get API Key

To create an API KEY please log on the Client web interface (http://{domain}/client) first with your given username and password.

Go to Settings → User

Double click the record line or click icon to open the detail view window.

If there no existing API Key you'll need to click the 'Generate a new key' button to create one.

Once the API Key is generated, you need to add api_key HTTP Header with according value in your RESTFul requests.

Get company_id

Visit the URL http://{domain}/client/public/company-list to get a list of companies , alternatively you can use your preferred RESTFul tools to get the list.

(In the example below we are using PostMan REST Client)

Create Request (GET)

You are all set to request to our server now.

For example, to lease all Client Users under current account:

Linux CURL request

curl -H "api_key: fd7ee0f2f86b41c0b00dd0f5c2281a61" -H "company_id: 1" http://{domain}/client/Client-User

You can also use PostMan to request for pretty response print out:

Create Request (POST)

You can submit your POST request either in HTTP Form format or JSON format.

To send request in Form format you need to add 'Content-Type:application/x-www-form-urlencoded' in your HTTP Header.

To send request in JSON format you need to add 'Content-Type:application/json' in your HTTP Header.

Form format:

JSON Format

Please note the in the above example we used an existed username so the server prompted error message, this is to demonstrate how server would response errors:

A 500 HTTP status code would be returned
Server will return "success":false in the returned JSON
A detailed explanation message is returned.

2. Creating a Consignment one step by one step

1) Creating a Consignment

Post a request with params below：

url

http://{domain}/client/Consignment

method

post

body

form parmas:

Field	Description	Mandatory	Date Type
is_urgent	Is urgent?		TINYINT(1)
delivery_service_id	Delivery Service ID	Yes	INT(4)
sales_reference	Sale Reference		VARCHAR(50)
sales_price	Order Sales Price		DECIMAL(10, 3)
sales_order_id	eBay or Amazon order ID		VARCHAR(50)
delivery_reference	Tracking Reference No.		VARCHAR(50)
contact	Contact Name	Yes	VARCHAR(100)
business_name	Business Name		VARCHAR(255)
address_line1	Address Line 1	Yes	VARCHAR(100)
address_line2	Address Line 2		VARCHAR(100)
address_line3	Address Line 3		VARCHAR(100)
city	City	Yes	VARCHAR(50)
county	County		VARCHAR(50)
post_code	Postcode		VARCHAR(10)
country_iso	Country ISO	Yes	CHAR(2)
telephone	Telephone		VARCHAR(50)
email	Email		VARCHAR(255)
special_instruction:	Note1		VARCHAR(255)
neighbour_instruction:	Note2		VARCHAR(255)
type	Consignment Type		ENUM('LOCAL','DIRECT','RETURN','AGENT_DIRECT')

Return

{
    "success":true,
    "data":{
		"id":"2006143004830001",
		"delivery_service_id":"12010433",
		"...":"..."
	}
}

Notice: Please check if a proper Delivery Service ID is attached, this is the most common cause for a error response

2) Add SKUs to Consignment

This Step is to attach SKU to the Consignment just created.

url

http://{domain}/client/Consignment-Product

method

post

body

form params:

Field	Description	Mandatory	Date Type
product_id	SKU ID	Yes	INT(10)
consignment_id	Consignment ID	Yes	BINGINT(16)
product_type	SKU Type	Yes	ENUM('NORMAL','DIRECTIONAL')
quantity	SKU Quantity	Yes	SMALLINT(5)

Return

{
    "success":true,
    "data":{
		"id":"1124955",
		"consignment_id":"2006143004830001",
		"product_id":"334422",
		"...":"..."
	}
}

Notice: Adding one kind of SKU only each Request.

3) Update the Status of Consignment to the PENDING

The final step is to update the Status of Consignment to the PENDING, which is the status system ready to process.

url

http://{domain}/client/Consignment/Batch-Update-Status

method

post

body

form params:

Field	Description	Mandatory	Date Type
ids	Consignment ID. For multiple consignment, join those IDs with a underscore, for example 123_124.	Yes	VARCHAR(255)
status	Consignment Status	Yes	VARCHAR(10)

Response

{
    "success":true
}

3. Creating Temporary Consignments and then batch converting to Consignments

1) Creating temporary Consignments

Temporary Consignments allows pre-process Consignments and correct some fields for Consignment, then batch converting those Consignment to the final Consignments in system

url

http://{domain}/client/consignment-upload/Temp-Consignment-Json

method

post

body

Fields:


Field	Description	Mandatory	Date Type
delivery_service_name	Delivery Service Name	Yes	INT(4)
sales_reference	Sales Reference		VARCHAR(50)
sales_price	Order Sales Price		DECIMAL(10, 3)
sales_order_id	eBay or Amazon order ID		VARCHAR(50)
delivery_reference	Tracking Reference No.		VARCHAR(50)
contact	Contact Name	Yes	VARCHAR(100)
business_name	Business Name		VARCHAR(255)
address_line1	Address Line 1	Yes	VARCHAR(100)
address_line2	Address Line 2		VARCHAR(100)
address_line3	Address Line 3		VARCHAR(100)
city	City	Yes	VARCHAR(50)
county	County		VARCHAR(50)
post_code	Postcode	Yes	VARCHAR(10)
country_name	Country ISO	Yes	CHAR(2)
telephone	Telephone		VARCHAR(50)
product_company_ref	SKUs and Quantity	Yes	VARCHAR(255)
email	Email		VARCHAR(255)
special_instruction:	Note 1		VARCHAR(255)
neighbour_instruction:	Note 2		VARCHAR(255)

[
    { 
        "contact": "Norman Drury", 
        "business_name": null, 
        "address_line1": "3, Northam Close", 
        "address_line2": "Marshside", 
        "address_line3": null, 
        "city": "Southport", 
        "county": "Merseyside", 
        "post_code": "PR9 9GA", 
        "country_name": "United Kingdom", 
        "telephone": "01704 226830", 
        "email": null, 
        "sales_reference": "2", 
		"sales_order_id": "110222319566-0",
        "payment_reference": "Royal Mail 1st Class Standard", 
        "special_instruction": null, 
        "product_company_ref": "15591*1+215312*1", 
        "delivery_service_name": "Royal Mail 1st Class Standard", 
        "status": "PENDING", 
        "type": "LOCAL", 
        "thirty_system_id":"2222" 
    } 
]

Response

{
    "success":true,
    "message":"File successfully uploaded! 1 records has been imported.",
    "data":{"2222":"12010433"}
}

2) Batch converting Temporary Consignments to the final Consignments

The Status of Consignment will be the PENDING

url	http://{domain}/client/Temp-Consignment-Info/Convert-Into-Consignment/?ids=12010436_12010437&type=LOCAL&start=0
method	get
body	-
Response	[Response with error ] { "numberOfTotalConsignmentsToProcess": 1, "numberOfConsignmentsProcessed": 1, "finished": true, "data": null, "errorIdList": [ { "id": 12010439, "message": "Can't find delivery service." } ], "success": true, "refresh": false } [Success] { "numberOfTotalConsignmentsToProcess": 1, "numberOfConsignmentsProcessed": 1, "finished": true, "data": { "12010439": "1507310110000001" }, "errorIdList": [], "success": true, "refresh": false }
Description of Response Fields	numberOfTotalConsignmentsToProcess: Total Number of Consignment to Process numberOfConsignmentsProcessed: Processed Number of Consigment for this Request finished: Have all temporary Consignments converted to the final Consignments data: The key pairs of temporary Consignments and the fianl Consignment Conventionaly system process 25 temporary Consignemnt for each Request. So when 'finished' in response is with 'false', then set param of 'start ' += numberOfConsignmentsProcessed to do another Request, until all temporary Consignment processed
Params	ids: Temporary Consignment IDs, join IDs with underscore when multiple. for example: 123_124_125 [Optional] type: Consignment Type. [Required] start: The start offset of temporary Consignments to Process [Required]

4 Creating a Consignment in a all-in-one API Request

url

http://{domain}/client/Consignment/Post-Pending-Consignment-With-Products-Json

method

post

body

[
    {
        "contact": "Norman Drury",
        "business_name": null,
        "address_line1": "3, Northam Close",
        "address_line2": "Marshside",
        "address_line3": null,
        "city": "Southport",
        "county": "Merseyside",
        "post_code": "PR9 9GA",
        "country_iso": "GB",
        "telephone": "01704 226830",
        "email": null,
        "delivery_service_id": "1471",
        "sales_reference": "2",
		"sales_price": 21.99
		"sales_order_id": "110222319566-0",
        "special_instruction": null,
        "products":[
        	{"client_sku":"IP-XX3355","quantity":5},
        	{"id":2,"quantity":4}
        ]
    }
]

Response

{
  "success": true,
  "data": [
    {
      "id": 1612120020000011,
      "company_id": 2,
      "client_id": 1,
      "consignment_product_quantity": 9,
      "consignment_product_reference": "1,2",
      "delivery_service_id": 1471,
      "delivery_service_id_internal": 1471,
      "delivery_package_size_id": 432,
      "delivery_package_size_id_internal": 432,
      "total_price": "0.00",
      "total_cost": "0.00",
      "...": "...",
	  "contact": "Norman Drury",
      "business_name": null,
      "address_line1": "3, Northam Close",
      "address_line2": "Marshside",
      "address_line3": null,
      "city": "Southport",
      "county": "Merseyside",
      "post_code": "PR9 9GA",
      "country_iso": "GB",
      "telephone": "01704 226830",
      "email": null,
      "sales_reference": "2",
	  "sales_order_id": "110222319566-0",
    }
  ]
}

Params

Field	Description	Mandatory	Date Type
is_urgent	Is Urgent ?		TINYINT(1)
delivery_service_id OR delivery_service_name	ID or Name of Delivery Service	Yes	INT(4)/VARCHAR(50)
sales_reference	Sales Reference		VARCHAR(50)
sales_price	Order Sales Price		DECIMAL(10, 3)
sales_order_id	eBay or Amazon order ID		VARCHAR(50)
delivery_reference	Tracking Reference No.		VARCHAR(50)
contact	Contact Name	Yes	VARCHAR(100)
business_name	Business Name		VARCHAR(255)
address_line1	Address Line 1		VARCHAR(100)
address_line2	Address Line 2		VARCHAR(100)
address_line3	Address Line 3		VARCHAR(100)
city	City		VARCHAR(50)
county	County		VARCHAR(50)
post_code	Postcode		VARCHAR(10)
country_iso	Country ISO	Yes	CHAR(2)
telephone	Telephone		VARCHAR(50)
email	Email		VARCHAR(255)
special_instruction:	Note 1		VARCHAR(255)
neighbour_instruction:	Note 2		VARCHAR(255)
products	SKU Reference or ID	Yes	LOCAL type Example: [ {"client_sku":”IP-XX3355”,"quantity":5}, {"id":2,"quantity":4} ] Agent Direct type Example: [ `{` `"product_name":` `"3apple297777777",` `"product_name_cn":"3苹果2955555555",` `"brand":"asd brand",` `"client_ref":"a4624777777",` `"price_customs_export":` `"3",` `"sales_price":"10",` `//sales unit price, required` `"weight":` `"300",` `"quantity":` `"1",` `"product_customs_property":["其它"],` `"attachment-url":"http://www.qqma.com/imgpic2/cpimagenew/2018/4/5/6e1de60ce43d4bf4b9671d7661024e7a.jpg",` `"hs_code":"172848"` } ]
parcel_pieces	parcel piece information	Optional	Example： [ {"weight":500, "length":25, "width":20, "depth":15, "description":"table"}, {"weight":400, "length":22, "width":18, "depth":13, "description":"chair"}, ] Note：Unit of Weight: g (gram)，Unit of Dimension: mm (millimetre)
type	consignment type	Option	Default is 'LOCAL' valid values ['LOCAL', 'AGENT_DIRECT']

5 Waiting Warehouse to process Consignment

Once Client Create a Consignment via API, and set the Status of Consignment to the PENDING, Warehouse operators will process that Consignment as soon as possible. so Client can make request to query those Consignment's Status periodically via API or system Web interface.

The Main Status of Consignment for Processing： PENDING → PICKING → PROCESSING → FINISHED

6 Common Error

1) Insufficient balance

Please top up some money then continue process

2) Insufficient Stock

Please send more goods to warehouse to top up stock

3) inproper delivery service chosen

Common Causes：

(1) The Chosen Delivery Service is not open for that Country、

(2) The Weight or Dimension of Consignment may not be suitable for that Delivery Service

(3) The SKU in Consignment is prohibitted by the Country.