创建订单流程

Owned by tuhao
Last updated: 2021-01-20

在鸟系统中创建订单有三种方法 ：

A 是直接创建订单再添加产品 ,  这种方式一次创建单个订单并处理，适合于订单量少，需要逐条交互的场景。

B 是上传批量订单再转换成标准订单 , 这种方式一次创建多个临时订单及产品，然后批量转换成正式订单，适合于订单量大，需要批量处理的场景。

C 是直接上传订单为待处理状态 , 这种方式一次创建多个正式订单及产品，并自动修改成待处理状态，类似于一键完成的效果，高度自动化，适用于订单量大，需要批量处理的场景。但前提是要确保上传的数据正常无误, 出错时，会自动撤消所插入的订单

三种方案的比较:



 (A) 标准接口(B) 批量订单接口(C) Pending订单接口

地址/client/Consignment/client/consignment-upload/Temp-Consignment-Json/client/Consignment/Post-Pending-Consignment-With-Products-Json

Content-Typeapplication/x-www-form-urlencodedapplication/jsonapplication/json
支持的订单类型本地订单 (LOCAL)√√√
专线订单 (DIRECT)√√√
退货订单 (RETURN)√√√
代理专线订单 (AGENT_DIRECT)√√√
客户专线订单 (CLIENT_DIRECT)√xx
FBA订单 (FBA)√xx
额外支持的产品普通共享产品√√√
定向共享产品√√√

产品参数可用客户SKUx√ (需要客户端设置批量订单产品字段用客户SKU)√ (传id/client_sku/reference参数)

邮递服务参数可用名称x√ (批量订单只能用delivery_service_name)√ (传delivery_service_name参数)

是否可一次传多个订单x√ (传json数组)√ (传json数组)

成功后的订单状态PREPARINGPENDING (只是批量订单，还未创建正式订单, 要处理成本地订单)PENDING

 以下是具体介绍：


一. 建立连接

在创建订单前， 我们先要了解如何建立连接。

鸟系统是使用Restful API与第三方系统交互的。为了识别用户身份，需要在每个请求中包含身份标识，这个动作我们称为建立连接， 可参考链接 ：建立连接

二. 用直接创建订单的方式添加订单

1.直接创建订单

创建订单主要是将订单需要的邮递服务，联系人，邮编，地址等信息post给服务器，

接口如下：

url

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

method

post

body

form 参数如下:

is_urgent

是否是紧急订单


TINYINT(1)

delivery_service_id

邮递服务

必填

INT(4) . 参考接口: 获取邮递服务 . 不同邮递服务有不同的要求，涉及邮编，重量，尺寸，海关属性等，需要事先从客服拿到各渠道的报价和发货限制.

return_consignment_action_type退货服务类型退货订单时必填

ENUM('CONTAINER','SELLER','DISPOSE','CHECK','TRANSFER')

CONTAINER 退货上架,

SELLER 退货等待回国,

DISPOSE 退货销毁

CHECK 退货查验

TRANSFER 退货转运

sales_reference

销售跟踪号



sales_price

销售平台上的订单售价
DECIMAL(10,3)　, 单位美元
sales_order_id

eBay或Amazon订单ID

(注：对eBay订单，如果客户有多个eBay账户，那么请把eBay卖家ID信息

也填在这里，可以按以下格式： “SellerUserID : OrderID” )


VARCHAR(50)
delivery_reference邮递跟踪号
VARCHAR(50)   , 　这个一般不需要填. 是下单成功后，异步返回的运输跟踪号.  如果需要在获取跟踪号后，实时通知ERP, 可使用Webhook. 参考接口: Webhook创建及使用接口 
custom_identity_reference

自定义惟一标识

(注: 如果填写了，会进行检测，同一种类型同一站点下的订单，6个月内不能有重复的标识)

重复的话会返回: {"success":false,"message":"Duplicate consignment identity reference [....]"}


VARCHAR(50)

contact

联系人

必填

VARCHAR(100)

business_name

公司


VARCHAR(255)

address_line1

地址行1

必填

VARCHAR(100)

address_line2

地址行2


VARCHAR(100)

address_line3

地址行3


VARCHAR(100)

city

城市

必填

VARCHAR(50)

county

省/郡


VARCHAR(50)

post_code

邮编


VARCHAR(10)

country_iso

国家

必填

CHAR(2)

telephone

电话


VARCHAR(50)

email

电子邮件


VARCHAR(255)

special_instruction:

备注1


VARCHAR(255)

neighbour_instruction:

备注2


VARCHAR(255)

type

订单类型


ENUM('LOCAL','DIRECT','RETURN','AGENT_DIRECT','FBA','CLIENT_DIRECT')

返回

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

请注意，订单的邮递服务ID，是和你当前所在的仓库和联系人国家相关的，如果在提交的时候发生邮递服务的错误，请优先检查这部分的问题。 

2. 往订单中添加产品

在上一步的返回结果信息中，我们会包含id字段作为订单ID. 这一步我们往这个ID所表示的订单中添加产品。

url

https://test.birdsystem.com/client/Consignment-Product

method

post

body

form 参数如下:

product_id

产品ID

 必填

INT(10)  . 参考接口: 产品的增删改查  

consignment_id

订单ID

 必填

BINGINT(16)

product_type

产品类型

 必填

ENUM('NORMAL','DIRECTIONAL')

quantity数量 必填SMALLINT(5)

is_directional_shared_product

是否定向共享产品 选填ENUM(1, 0)
返回
{
    "success":true,
    "data":{
		"id":"1124955",
		"consignment_id":"2006143004830001",
		"product_id":"334422",
		"...":"..."
	}
}

请注意，一次请求只能添加一种产品，如果添加多种产品，请发多个请求。

3. 修改订单的状态为待处理

往订单中添加完产品后，我们就可以将订单的状态修改为待处理，待处理即表示提交给仓库处理。

url

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

method

post

body

form 参数如下:

ids

订单ID

 必填

VARCHAR(255) ，多个ID以下划线分隔

status

目标状态

 必填

VARCHAR(10)， 固定为PENDING

返回
{
    "success":true
}

三 用上传批量订单的方式添加订单

1.上传批量订单

批量本地订单上传（接口）

 1、接口说明

批量订单是为了方便进行一次性处理大量订单而提供的一个创建临时处理订单的接口，通过派分处理任务让系统自动处理临时订单并自动生成本地出库订单

接口

url

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

接口功能

批量添加订单

支持格式

JSON

开发人员

method

POST

发布日期

订单请求参数

参数

必选

类型

说明

1

contact

必填

VARCHAR

联系人

2

business_name

选填

VARCHAR

公司名称

3

name_customs

选填

VARCHAR

产品英文名称

4

address_line1

必填

VARCHAR

地址行1

5

address_line2

选填

VARCHAR

地址行2

6

address_line3

选填

VARCHAR

地址行3

7

city

必填

VARCHAR

城市

8

county

选填

VARCHAR

省/郡

9

post_code

必填

VARCHAR

邮编

10

country_name

选填

VARCHAR

国家名称

11

telephone

选填

INT

电话号码

12

email

选填

VARCHAR

电子邮箱

13

sales_order_id

选填 【yodel 出口必填】

VARCHAR

销售订单ID

14

payment_reference

选填

VARCHAR

付款凭证

15

special_instruction

选填

VARCHAR

备注1

16

product_company_ref

必填
产品信息寄存当前字段下

VARCHAR

批量订单产品代码
"#":"//产品sku*产品数量||eBay订单交易号||eBay产品ID，||平台销售单价+产品id*产品数量||eBay订单交易号||eBay产品ID||平台销售单价", "product_company_ref": "1-1996129*1||ebayid||ebatproduct||18+1996125*1||ebayid2||ebatproduct2||20",

17

delivery_service_name

选填

VARCHAR

邮递服务名称 参考接口: 获取邮递服务

18

status

选填

VARCHAR

订单状态：PENDING

19

type

选填

VARCHAR

订单类型：LOCAL

20

thirty_system_id

选填

VARCHAR

21

sales_reference

选填

VARCHAR

销售跟踪号

22

sales_price

选填

VARCHAR

销售平台单价

23

omp_name

选填 【royal mail，yodel 出口必填

VARCHAR

销售平台名称，(必须是英文), ebay, amazon 等

24

omp_vat_number

选填 【yodel 出口必填】

英国发往非英国且公司不为空（“business_name“字段）的DPD订单 要求必填

VARCHAR

销售平台VAT号

25

shipper_eori

选填 【royal mail，dpd 出口必填】

英国发往EU必填

英国发往非英国的DPD服务必填

VARCHAR

客户的EORI号 由国家代码+12位数字组成的vat号. 例如GB000001234567. 必须在鸟系统中有备案, 备案流程详询客服。参考接口: 获取VAT账号

26

reason_for_export

选填 【dpd 出口必填】

VARCHAR

出口原因，值【Sale:销售; ReturnReplacement:退换; Gift:礼物】

27

content_type

选填 【royalmail 出口必填】

VARCHAR

包裹类型，值【Gift 礼物；Documents 文件和 Other 其他】

28

ebay_transaction_id

选填

VARCHAR(50)

eBay订单交易号，加在product_company_ref里边

29

ebay_item_no

选填

VARCHA

eBay产品ID，加在product_company_ref里边

30

ioss_vat_number

必填

VARCHAR(12)

IOSS号，限制填12位字符，格式两位字母+十位数字
订单发往欧盟国家时，必填

31

receiver_eori

收件人EORI

选填（DPD服务按要求必填）

英国发往非英国且公司不为空（“business_name“字段）的DPD订单 要求必填

32

receiver_pid_number

收件人个人证件号

选填（DPD服务按要求必填）

英国发往挪威、西班牙、意大利的DPD订单 要求必填

33

is_compensation_for_delay

选填

是否需要“晚必赔”服务（只支持部分邮递服务，偏远地区除外）

BOOL

晚必赔服务，传0/1，默认为0，非0传1

2、接口示例

接口请求示例

地址：http://branch.birdsystem.com/client/consignment-upload/temp-consignment-json

[
     {
          "contact": "Norman Drury",
          "business_name": 1,
          "address_line1": "3Northam Close",
          "address_line2": "Marshside",
          "address_line3": null,
          "city": "Southport",
          "county": "Merseyside",
          "post_code": "12345",
          "country_name": "Norway",
          "telephone": "01704 226830",
          "email": null,
          "delivery_service_id": "5315",
          "sales_reference": "2",
          "sales_order_id": "1234567654",
          "special_instruction": null,
          "product_company_ref": "1-1*1||ebayid||ebatproduct||18+1996125*1||ebayid2||ebatproduct2||20",
          "type": "LOCAL",
          "sender_contact": "123",
          "omp_name": "ebay",
          "omp_vat_number": "12345",
          "shipper_eori": "12345600",
          "reason_for_export": "Sale",
          "content_type": "Gift",
          "ioss_vat_number": 172848,
          "receiver_eori":"123456",
          "receiver_pid_number":"12",
          "sender_address_line1": "SHENZHENG BANTIAN",
          "sender_city": "SHENZHEN",
          "sender_post_code": 12345,
          "sender_country_iso": "CN",
          "sender_telephone": "155465751714",
          "is_compensation_for_delay": "1"
     }
]

接口返回示例

{
    "message": "File successfully uploaded! 1 records has been imported.",
    "success": true,
    "moduleName": "client"
}

返回异常示例:

报错时需检查字段填写是否完整。contact, post_code, city, country_name, product sku, quantity, address_line1.

{
    "success": false,
    "message": "Accounted the following exceptions:<br>  Row: 1 : Bulk Order with required the following fields:contact, post_code, city, country_name, product sku, quantity, address_line1.<br>"
}

 变更记录

Jira编号

上线日期

开发

改动前

改动后

 

 

 

 

 

 

 

 

 

2.处理批量订单

批量处理临时本地订单

接口说明：

URL

http://test.birdsystem.com/client/Temp-Consignment-Info/Convert-Into-Consignment/?type=LOCAL&ids=XXX

接口功能

处理批量临时本地订单到正式订单

支持格式

JSON

开发人员


请求方式

GET

发布日期


参数说明：

参数

必填

说明

type

必填

订单类型，取值为'LOCAL'，代表本地订单

ids

选填

要处理的临时订单id列表，多个订单用下划线分隔；如果不传的话，默认取所有待处理的订单

includeProblemConsignments

选填

是否包含有问题的订单，传1时表示包括有问题的订单；不传或者传其他值表示忽略有问题的订单

请求示例：

处理批量本地订单请求示例

http://test.birdsystem.com/client/Temp-Consignment-Info/Convert-Into-Consignment/?type=LOCAL&ids=XXX


返回示例：

处理批量本地订单返回示例
{
    "numberOfTotalConsignmentsToProcess": 1,
    "taskId": 1,
    "success": true,
    "refresh": false
}

其中taskId是当前正在运行的后台任务的id。（目前 convert-into-consignment 使用后台任务模式, 开启一个后台任务后, 不等后台完成, 就返回后台任务的id）

1-3-3 后台任务处理临时本地订单详情

四 用直接上传订单为待处理状态的方式添加订单

Unable to render {include} The included page could not be found.

五 获取面单

订单到待处理后, 会在后台异步对接, 大约5-10分钟内会对接服务商.

获取面单的接口,参考  打印地址贴

为了让客户能第一时间知晓 您的订单已经对接好服务商,生成了面单, 我们提供 了webhook来通知客户. Webhook创建及使用接口

六 等待仓库处理订单

经过上面步骤二或者步骤三或者步骤四以后，订单已提交到仓库进行处理，用户只需隔一段时间后刷新查询结果即可.

仓库处理状态流依次是： 待处理->待拣货->拣货中->完成

七 常见错误

1.添加订单时报余额不足

这是由于客户帐户中可用余额不足造成的，不能再发订单，需要充值后再使用

2.往订单添加产品时报库存不足

这是由于指定产品的库存不够造成的，只能设法补货

3.往订单添加产品时报邮递服务不合适

造成这类问题原因通常有：

  (1)  邮递服务在目标国家没有开通服务、

  (2)  订单中产品重量、规格超过该邮递服务所能处理的范围

  (3)  订单中产品包含有海关禁运属性

遇到邮递服务不合适的情况时，请咨询我们客服，以便获得详细的解答