订单上传接口
此接口每次上传一个订单信息到云帆,如果有订单更新(不能变更和增减订单的商品的交易明细id),也使用本接口直接推送订单到云帆,开发者请注意严格遵守报文结构要求。
订单状态Status的取值说明:
WAIT_SELLER_SEND_GOODS:等待卖家发货,即:买家已付款
WAIT_BUYER_CONFIRM_GOODS :等待买家确认收货,即:卖家已发货
TRADE_SUCCESS:买家已签收或交易成功
TRADE_CLOSED:交易关闭
订单上传状态流转顺序: 注意:订单状态变更重复推送时,请保证 【tid】和【oid】保持一致
等待卖家发货—>交易成功;
等待卖家发货—>交易关闭;
等待卖家发货—>等待买家确认收货—>交易成功;
等待卖家发货—>等待买家确认收货—>交易关闭;
接口请求地址
测试地址:http://erppushtest.kuaidaoyun.com/api/yunfan/extopentrade
正式地址:(联系云帆技术支持获取,官方微信号:19180611683对接联调)
测试账号
【app_id】: i1hY3vOmCBWAB9ddDSDTN1RL
【appSecret】: 37f2af0405eaea09c363115273eb02df05cdba7f
正式环境的请求地址及账号信息,请在云帆ERP系统中进行申请。
请求参数
字段 |
类型 |
必需 |
默认 |
注释 |
sign |
String |
是 |
|
签名,MD5(app_id + PostBody + appSecret) |
PostBody数据
参数名称 |
参数类型 |
必需 |
参数说明 |
示例值 |
app_id |
String |
是 |
系统中申请的appId |
10001 |
msg_id |
String |
是 |
请求消息Id |
1000168313316464 |
data |
Data |
是 |
订单详情结构体Data数据 |
详见下面【订单详情结构体Data】的说明 |
timestamp |
Long |
是 |
毫秒级时间戳 |
1603070658889 |
签名说明:
sign=MD5(app_id + PostBody + appSecret)转小写
注意:由于JSON没有明确的跨语言规范,因此对JSON解析之后再进行重新编码,并不一定能还原原始JSON字符串。所以请严格按照原始报文进行签名和验签!
订单详情结构体 Data
参数名称 |
参数类型 |
必需 |
参数说明 |
示例值 |
order_info |
OrderInfo |
是 |
订单详情 |
|
address_info |
AddressInfo |
是 |
收件人地址详情 |
|
pay_info |
PayInfo |
是 |
支付详情 |
|
orders |
Orders[] |
是 |
商品明细详情 |
|
remark_info |
RemarkInfo |
否 |
订单备注 |
null |
订单详情结构体 OrderInfo
参数名称 |
参数类型 |
必需 |
参数说明 |
示例值 |
tid |
String |
是 |
订单编号 30位长度以内,仅允许字母数字与中横线 |
C20190729143007187567 |
pay_time |
String |
是 |
订单支付时间 |
2019-08-20 19:09:37 |
created |
String |
是 |
订单创建时间 |
2019-08-20 20:09:37 |
type |
Integer |
是 |
主订单类型 0:普通订单; 1:送礼订单; 2:代付; 3:分销采购单; 4:赠品; 5:心愿单; 10:拼团; 15:返利; 35:酒店; 40:外卖; 71:美业预约单; 72:美业服务单; 81:礼品卡 |
0 |
status |
String |
是 |
主订单状态: WAIT_SELLER_SEND_GOODS:等待卖家发货,即:买家已付款, WAIT_BUYER_CONFIRM_GOODS 等待买家确认收货,即:卖家已发货, TRADE_SUCCESS:买家已签收以及订单成功, TRADE_CLOSED:交易关闭 |
WAIT_SELLER_SEND_GOODS |
consign_time |
String |
否 |
订单发货时间(当所有商品发货后才会更新) |
2019-08-20 20:09:37 |
success_time |
String |
否 |
交易完成时间 |
2019-08-20 17:20:28 |
confirm_time |
String |
否 |
订单确认时间 |
2019-08-21 20:09:37 |
offline_id |
Long |
否 |
云帆网点编码 |
2546481 |
update_time |
String |
否 |
订单更新时间 |
2019-08-20 10:19:52 |
is_retail_order |
String |
否 |
是否零售订单,true:是,false:否 |
false |
pay_type |
Integer |
否 |
订单支付类型 0:默认值 |
0 |
close_type |
Integer |
否 |
订单关闭类型 0:默认值,0:未关闭; 1:过期关闭; 2:标记退款; 3:订单取消; 4:买家取消; 5:卖家取消; 6:部分退款; 18:扣款失败; 19:0元关单; 22:拒单退款; |
1 |
地址详情结构体 AddressInfo
参数名称 |
参数类型 |
必需 |
参数说明 |
示例值 |
receiver_name |
String |
是 |
收货人姓名 |
帆宝 |
delivery_address |
String |
是 |
详细地址 |
翠苑街道黄龙万科中心18楼 |
delivery_province |
String |
是 |
省 |
四川省 |
delivery_city |
String |
是 |
市 |
成都市 |
delivery_district |
String |
是 |
区 |
温江区 |
receiver_tel |
String |
是 |
收货人手机号 |
13700000000 |
delivery_postal_code |
String |
否 |
邮政编码 |
330106 |
支付结构体 PayInfo
参数名称 |
参数类型 |
必需 |
参数说明 |
示例值 |
payment |
Integer |
是 |
订单实付金额,订单上每个商品最终均摊价,单位:分 |
5 |
total_fee |
Integer |
是 |
订单优惠前总金额,单位:分 |
5 |
post_fee |
Integer |
否 |
订单邮费金额,单位:分 |
5 |
outer_transactions |
String[] |
否 |
外部订单号,默认:””, |
OR1533766114265956211 |
transaction |
String[] |
否 |
交易流水号,默认:”” |
TR1533766114265956211 |
商品明细结构体 Orders
参数名称 |
参数类型 |
必需 |
参数说明 |
示例值 |
num |
Integer |
是 |
商品数量 |
6 |
oid |
String |
是 |
交易明细id,子订单号 |
1533766114265956211 |
title |
String |
是 |
商品名称 |
测试商品02 |
price |
Integer |
是 |
单商品原价,单位:分 |
8 |
payment |
Integer |
是 |
订单明细应付金额,订单上每个商品最终均摊价,单位:分 |
50 |
total_fee |
Integer |
是 |
商品总价(扣除商品级优惠) 单位:分 |
45 |
pic_path |
String |
是 |
商品图片地址 |
http://erp.help.cloudsail.net.cn/_book/help/05_orderhelp/orderdistribution.html/FiaHY0DewCTyROywOgigS7WaXQBg.jpg |
status |
String |
是 |
商品状态: WAIT_SELLER_SEND_GOODS:等待卖家发货,即:买家已付款, WAIT_BUYER_CONFIRM_GOODS 等待买家确认收货,即:卖家已发货, TRADE_SUCCESS:买家已签收以及订单成功, TRADE_CLOSED:交易关闭 |
WAIT_SELLER_SEND_GOODS |
item_id |
long |
是 |
商品id,生成的商品唯一id,对应商品上传接口:product_id |
495112276 |
sku_properties_name |
String |
是 |
商品规格信息(无规格商品传空),结构体SkuPropertiesName数组类型的字符串格式,”[{“k”:”规格”,”k_id”:14,”v”:”袋”,”v_id”:10710}]” |
“[{“k”:”规格”,”k_id”:14,”v”:”袋”,”v_id”:10710}]” |
discount_price |
Integer |
否 |
单商品现价,减去了商品的优惠金额。单位:分 |
500 |
item_type |
Integer |
否 |
订单类型 默认:0, 0:普通类型商品; 10:分销商品; 24:周期购 |
0 |
outer_item_id |
String |
否 |
商品编码,商家自定义编码,可用于和其他系统之间商品的外部id的标识,对应云帆系统展示的商家SPU编码 |
spbm001 |
fenxiao_payment |
Integer |
否 |
分销单实付金额 默认:0,单位:分 |
86 |
buyer_messages |
String |
否 |
商品留言 |
{\”我是商品留言\”:\”商品留言\”} |
is_present |
Bool |
否 |
是否赠品,是:true,否:false |
false |
fenxiao_price |
Integer |
否 |
分销单金额 默认:0,单位:分 |
56 |
alias |
String |
否 |
商品别名,最长50个汉字 |
54564564asodj |
outer_sku_id |
String |
否 |
商品规格编码,,对应云帆系统展示的商家SKU编码 |
spbm001 |
customs_code |
String |
否 |
海关编号 |
SH |
sku_id |
long |
否 |
规格id 默认:0,生成的商品规格唯一id,对应商品上传接口:product_sku_id |
3635684788 |
points_pric |
Integer |
否 |
商品积分价(非积分商品则为0) 默认:0,如返回值是100则表示100积分。 |
100 |
express_no |
String |
否 |
快递单号。 “”:默认值 |
|
express_code |
String |
否 |
快递公司编码,详情参照【快递公司列表】对应快递公司编号。 “”:默认值 |
|
delivery_time |
String |
否 |
发货时间 |
2019-08-20 10:19:52 |
goods_url |
String |
否 |
商品详情链接 |
https://h5.youzan.com/v2/showcase/goods?alias=26vavj3339p1x |
refund_time |
String |
否 |
退款时间 |
2019-08-20 10:19:52 |
refund_fee |
Integer |
否 |
退款金额,默认:0,单位:分 |
105 |
refund_type |
Integer |
否 |
退款类型 默认:-1无,1:买家申请退款,2:商家主动退款, 3:系统退款。 |
1 |
refund_state |
Integer |
否 |
退款状态 默认:-1未退款,1:买家已经申请退款,等待卖家同意, 10:卖家拒绝退款, 20:卖家已经同意退货,等待买家退货, 30:买家已经退货,等待卖家确认收货, 40:卖家未收到货,拒绝退款, 50:退款关闭, 60:退款成功 |
1 |
参数名称 |
参数类型 |
必需 |
参数说明 |
示例值 |
buyer_message |
String |
否 |
订单买家留言 |
我是卖家留言 |
trade_memo |
String |
否 |
订单卖家备注 |
我是卖家备注内容 |
star |
Integer |
否 |
订单标星等级: 0~5分别表示不同星级,默认:0 |
1 |
商品规格信息结构体 SkuPropertiesName
参数名称 |
参数类型 |
必需 |
参数说明 |
示例值 |
k |
String |
否 |
规格名称 |
规格 |
k_id |
Integer |
否 |
规格名称编号 |
4 |
v |
String |
否 |
规格值 |
袋 |
v_id |
Integer |
否 |
规格值编号 |
400 |
云帆请求的说明
1、数据编码采用UTF-8格式,application/json格式
2、采用HTTP或HTTPS传输协议,POST方法
{
"app_id":"i1hY3vOmCBWAB9ddDSDTN1RL",
"msg_id":"eeced9cc441942ff8ec2002178c2ff9b",
"data":{
"address_info":{
"delivery_address":"水印城 1-4-1143",
"delivery_postal_code":"",
"receiver_name":"周XX",
"delivery_province":"四川省",
"delivery_city":"成都市",
"delivery_district":"双流区",
"receiver_tel":"18012630000"
},
"remark_info":{
"buyer_message":"卖家留言",
"trade_memo":"买家备注",
"star":0
},
"pay_info":{
"outer_transactions":[
"396201909050781205290"
],
"post_fee":0,
"total_fee":18970,
"payment":18170,
"transaction":[
"190905210136000381"
]
},
"orders":[
{
"outer_item_id":"",
"discount_price":8990,
"item_type":0,
"num":1,
"oid":"4200000396201909050781205290",
"title":"看得见的放心越光大米4KG",
"fenxiao_payment":0,
"buyer_messages":"{}",
"is_present":false,
"price":8990,
"fenxiao_price":0,
"total_fee":8990,
"alias":"35y166a13ppl1",
"payment":8990,
"outer_sku_id":"6957048900110",
"customs_code":"",
"item_id":425430756,
"item_no":"",
"sku_properties_name":"[{\"k\":\"规格\",\"k_id\":14,\"v\":\"袋\",\"v_id\":10710}]",
"sku_id":36243074,
"pic_path":"https://img.yzcdn.cn/upload_files/2019/05/23/FiCeZY7Sexk3GGdKmPGHI_Dkuy-7.jpg",
"points_price":0,
"express_no":"YD202012345689",
"delivery_time":"2020-05-22 09:53:28",
"express_code":"1",
"status":"TRADE_SUCCESS",
"refund_type":1,
"refund_time":"2020-09-02 12:00:00",
"refund_fee":1500,
"refund_state":60
}
],
"order_info":{
"consign_time":"2020-05-07 16:14:04",
"created":"2020-05-07 16:10:36",
"offline_id":56307550,
"expired_time":"2020-05-07 16:40:36",
"success_time":"2020-05-22 09:53:27",
"type":0,
"confirm_time":"",
"tid":"E20200507161036078000002",
"pay_time":"2020-05-07 16:10:50",
"update_time":"2020-05-22 09:53:28",
"is_retail_order":"false",
"pay_type":10,
"close_type":0,
"status":"TRADE_SUCCESS"
}
},
"timestamp":1603452082572
}
订单详情结构体Json数据示例
{
“address_info”: {
“delivery_address”: “水印城 1-4-1143”,
“delivery_postal_code”: “”,
“receiver_name”: “周XX”,
“delivery_province”: “四川省”,
“delivery_city”: “成都市”,
“delivery_district”: “双流区”,
“receiver_tel”: “18012630000”
},
“remark_info”: {
“buyer_message”: “卖家留言”,
“trade_memo”: “买家备注”,
“star”: 0
},
“pay_info”: {
“outer_transactions”: [“396201909050781205290”],
“post_fee”: 0,
“total_fee”: 18970,
“payment”: 18170,
“transaction”: [“190905210136000381”]
},
“orders”: [{
“outer_item_id”: “”,
“discount_price”: 8990,
“item_type”: 0,
“num”: 1,
“oid”: “4200000396201909050781205290”,
“title”: “看得见的放心越光大米4KG”,
“fenxiao_payment”: 0,
“buyer_messages”: “{}”,
“is_present”: false,
“price”: 89.9,
“fenxiao_price”: 0,
“total_fee”: 8990,
“alias”: “35y166a13ppl1”,
“payment”: 8990,
“outer_sku_id”: “6957048900110”,
“customs_code”: “”,
“item_id”: 425430756,
“item_no”: “”,
“sku_properties_name”: “[{\”k\”:\”规格\”,\”k_id\”:14,\”v\”:\”袋\”,\”v_id\”:10710}]”,
“sku_id”: 36243074,
“pic_path”: “https://img.yzcdn.cn/upload_files/2019/05/23/FiCeZY7Sexk3GGdKmPGHI_Dkuy-7.jpg“,
“points_price”: 0,
“express_no”: “YD202012345689”,
“delivery_time”: “2020-05-22 09:53:28”,
“express_code”: “1”,
“status”: “TRADE_SUCCESS”,
“refund_type”: 1,
“refund_time”: “2020-09-02 12:00:00”,
“refund_fee”: 1500,
“refund_state”: 60
}],
“order_info”: {
“consign_time”: “2020-05-07 16:14:04”,
“created”: “2020-05-07 16:10:36”,
“offline_id”: 56307550,
“expired_time”: “2020-05-07 16:40:36”,
“success_time”: “2020-05-22 09:53:27”,
“type”: 0,
“confirm_time”: “”,
“tid”: “E20200507161036078000002”,
“pay_time”: “2020-05-07 16:10:50”,
“update_time”: “2020-05-22 09:53:28”,
“is_retail_order”: “false”,
“pay_type”: 10,
“close_type”: 0,
“status”: “TRADE_SUCCESS”
}
}
响应参数
参数名称 |
参数类型 |
参数说明 |
示例值 |
success |
Boolean |
表示本次请求是否成功。 true:成功 false:失败 |
true |
message |
String |
网关返回码描述 |
trade not found |
status |
Int |
网关返回码,表示本次请求是否成功。200 :成功。 |
200 |
成功示例
{
“status”: 200, //状态码
“success”: true,
“message”: null,
“data”: null
}
异常示例(注意大小写格式)
{
“Status”: 1001, //状态码
“Success”: false,
“Message”: “sign is error”,
“Data”: null
}