订单上传

订单上传接口

此接口每次上传一个订单信息到云帆,如果有订单更新(不能变更和增减订单的商品的交易明细id),也使用本接口直接推送订单到云帆,开发者请注意严格遵守报文结构要求。
订单状态Status的取值说明:
WAIT_SELLER_SEND_GOODS:等待卖家发货,即:买家已付款
WAIT_BUYER_CONFIRM_GOODS :等待买家确认收货,即:卖家已发货
TRADE_SUCCESS:买家已签收或交易成功
TRADE_CLOSED:交易关闭
订单上传状态流转顺序: 注意:订单状态变更重复推送时,请保证 【tid】和【oid】保持一致
等待卖家发货—>交易成功;
等待卖家发货—>交易关闭;
等待卖家发货—>等待买家确认收货—>交易成功;
等待卖家发货—>等待买家确认收货—>交易关闭;

接口请求地址

测试地址:http://erppushtest.kuaidaoyun.com/api/yunfan/extopentrade
正式地址:

测试账号
【app_id】: i1hY3vOmCBWAB9ddDSDTN1RL
【appSecret】: 37f2af0405eaea09c363115273eb02df05cdba7f
正式环境的请求地址及账号信息,请在云帆ERP系统中进行申请。

请求参数

Headers参数

字段 类型 必需 默认 注释
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
office_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

备注详情结构体 RemarkInfo

参数名称 参数类型 必需 参数说明 示例值
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
}