Consignment API

Owned by Shawn Wang (Unlicensed)
Last updated: 2021-10-25 by Seven Zhang
6 min read

There are three ways to create Consignments in Birdsystem :

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 BirdSystem 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

Please refer to the link ：Create Request

2. Creating a Consignment one step by one step

1) Creating a Consignment

Post a request with params below：

url

http://test.birdsystem.com/client/Consignment

method

post

body

form parmas:

FieldDescriptionMandatoryDate 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_referenceTracking 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://test.birdsystem.com/client/Consignment-Product

method

post

body

form params:

FieldDescriptionMandatoryDate Type

product_id

SKU ID

 Yes

INT(10)

consignment_id

Consignment ID

 Yes

BINGINT(16)

product_type

SKU Type

 Yes

ENUM('NORMAL','DIRECTIONAL')

quantitySKU Quantity YesSMALLINT(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 BirdSystem ready to process.

url

http://test.birdsystem.com/client/Consignment/Batch-Update-Status

method

post

body

form params:

FieldDescriptionMandatoryDate 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 BirdSystem

url

http://test.birdsystem.com/client/consignment-upload/Temp-Consignment-Json

method

post

body

Fields:





FieldDescriptionMandatoryDate 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_referenceTracking 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_refSKUs and QuantityYesVARCHAR(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://test.birdsystem.com/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 Birdsystem 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://test.birdsystem.com/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

FieldDescriptionMandatoryDate 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_priceOrder 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_piecesparcel piece informationOptional

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)

typeconsignment typeOption

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 BirdSystem 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.