跳到主要内容

订单添加/更新


前置条件

获得 数据源,并在 资产分发 打开该数据源ID 的指定应用场景的分发开关。


请求地址

https://api.e.qq.com/v1.3/order/add


所属权限

数据上报(User Actions)


请求方法

POST


请求参数

参数名描述
access_token密钥信息,可在 DataNexus 的 数据源 - 【查看密钥】获取
timestamp当前的时间戳,单位为秒,允许客户端请求最大时间误差为 300 秒。MarketingAPI 所使用的时间戳,若无特殊说明,均为秒级时间戳签名算法。MarketingAPI 所使用的时区为 GMT+8,例如当时间戳为 1494840119 时,表示 2017-05-15 17:21:59
nonce随机字串标识,不超过 32 个字符,由调用方自行生成,需保证全局唯一性

请求体类型

application/json


请求体参数

阅读说明:Y - 必填;C - 条件选填(conditional),请关注“描述”信息;空 - 非必填

名称类型必填描述
account_idintegerY
推广帐号 id或 DataNexus 账号 id
user_action_set_idintegerY
数据源 id,通过 DataNexus 创建数据源时分配的唯一 id。请注意,当填写的数据源类型为 {WECHAT, WECHAT_MINI_PROGRAM, WECHAT_MINI_GAME} 时,必填 user_id 字段中的 wechat_openid (或 wechat_unionid) 及 wechat_app_id。
ordersarrayY
订单列表 数组最大长度 50
external_order_idstringY
商家订单号
combine_mchidstring
微信支付场景,合单发起方商户号,服务商和电商模式下,传服务商商户号,示例值:1900000109
combine_appidstring
微信支付场景,合单发起方的appid,示例值:wxd678efh567hg6787
mchidstring
微信支付场景,支付下单商户的商户号,由微信支付生成并下发
appidstring
微信支付场景,由微信生成的应用ID,全局唯一
sub_mchidstring
微信支付场景,服务商模式下必填,微信支付下单的子商户的商户号
sub_appidstring
微信支付场景,服务商模式下子商户申请的appid,若填写,则 open_id 为该 sub_appid 下的唯一用户标识
create_timestringY
订单创建时间,unix时间戳 字段长度为 13 字节
order_sourcestringY
订单来源,见 枚举值
order_typeintegerY
订单类型,见 枚举值,普通购买商品订单传 1 即可
brand_idstring
订单品牌 id
brand_namestring
订单品牌名称
goods_num_totalintegerY
订单商品总数量
goods_weightfloat
订单商品总重量,默认单位为克
goods_amount_totalfloatY
商品总金额,单位默认为元 注:已含单品级别优惠的商品金额,如单品直降
freight_amountfloatY
订单运费,单位默认为元 注:运费为0时,传0.00
order_amountfloatY
订单金额,单位默认为元 注:商品总金额+运费金额=订单金额
payable_amountfloatY
订单应付金额,单位默认为元 注:订单金额-订单级别的优惠金额(如:订单满减)=订单应付金额
payment_amountfloatY
实付金额,单位默认为元 注:订单应付金额-支付优惠金额(如:微信支付优惠、招商银行优惠等)=订单实付金额
order_statusstringY
订单状态,见 枚举值
status_change_timestringY
状态变更时间,unix毫秒级时间,如 order_status状态为 1150 ,则传 1150(已支付待发货)状态变更的时间
user_infoobjectY
用户信息,json格式
open_idstringY
下单人 open_id,order_source = wxapp时,必填
app_idstring
小程序或公众号的appid
union_idstring
下单人 union_id
sha256_user_phonestring
下单人手机号,sha256加密
md5_user_phonestring
下单人手机号,md5加密
user_idstring
下单人用户 id
qb_account_infostringC
qq浏览器用户标识,例 5dd6ddffe1440, 接入qq浏览器业务必填
chan_id_hjstringC
惠聚用户标识,例 63_5a23p4ded6ff6384,接入惠聚-发现福利业务必填
member_idstring
下单人会员号
card_levelstring
会员卡等级
user_first_order_timestring
下单人在KA注册后首次下单时间,格式为UNIX时间戳 字段长度为 13 字节
goods_infoarrayY
主订单商品信息,数组类型,每个sku存一个数组单位
external_sku_idstringY
sku 编号
primary_image_urlstring
商品主图
sku_name_chinesestringY
sku 名称
goods_amountfloatY
单件商品原价,单位默认为元
current_amountfloat
当前商品的单件现价,单位默认为元
payment_amountfloatY
多件商品实付金额(分摊了优惠的金额),单位默认为元,注:「腾讯有数」GMV计算使用该字段
is_giftinteger
是否赠品,0代表非赠品,1代表赠品
external_spu_idstringY
sku 所属 spu 编号,若无 spu,传输内容请与 external_sku_id 保持一致
spu_name_chinesestringY
spu 名称,若无 spu,传输内容请与 sku_name_chinese 保持一致
sale_unitstring
商品售卖单位
category_idstring
末级类目 id
category_namestring
末级类目名称
goods_numintegerY
商品数量
goods_weightfloat
商品重量,单位默认为克
attribute_idsstring[]C
描述同一个 skuid 下的不同属性id,具体见枚举列表,当同一个 skuid 下有影响价格变动的属性值时必填
store_infoobject
订单销售门店信息
external_store_idstring
主订单销售门店id
store_namestring
主订单销售门店名称,如是线上门店,可填写线上门店名称
store_citystring
主订单销售门店所属城市
seller_infoobject
订单的卖家信息,供平台类商家填写自己的卖家信息
seller_idstring
订单卖家 id,由平台类商家自己生成
seller_name_chinesestring
订单子卖家名称
seller_name_englishstring
订单子卖家名称
target_urlobject
商品落地页信息
url_miniprogramstringC
微信小程序落地页 url,当落地页为微信小程序时必填 字段长度最小 1 字节,长度最大 100 字节
miniprogram_appidstringC
微信小程序 appid,当落地页为微信小程序时必填 字段长度最小 1 字节,长度最大 100 字节
miniprogram_usernamestringC
小程序原始ID,登录小程序管理后台-设置-基本设置-帐号信息中,gh_xx,当落地页为微信小程序时必填字段长度最小 1 字节,长度最大 100 字节
url_miniprogram_qqstringC
qq小程序落地页 url,当落地页为QQ小程序时必填 字段长度最小 1 字节,长度最大 100 字节
miniprogram_appid_qqstringC
qq小程序 appid,当落地页为QQ小程序时必填 字段长度最小 1 字节,长度最大 100 字节
url_h5stringC
h5落地页url 字段长度最小 1 字节,长度最大 100 字节
chan_infoarray
主订单来源渠道,数组类型
chan_wxappobject
小程序渠道
chan_scenestring
小程序场景值
chan_refer_app_idstring
智慧零售入口小程序必传,来源小程序或公众号appid
gdt_click_idstring
广告点击id,例 wx0t13scn3gq3zq400 表示该订单是从广告场景某次点击 click_id 带来的
chan_idstring
智慧零售入口小程序必传,引流渠道编码
tx_cps_idstring
腾讯广告CPS追踪参数,腾讯广告CPS业务必填
fy_cps_idstring
枫页CPS追踪参数,枫页CPS业务必填
ym_cps_idstring
云mall CPS追踪参数,云mall CPS业务必填
ym_cps_agency_idstring
云mall CPS机构ID,云mall CPS业务必填
qb_account_infostring
qq浏览器用户标识,例 5dd6ddffe1440,接入qq浏览器业务必填
commission_infoarray
佣金,json字符串
commission_typeinteger
佣金类型,枚举值如下:1:按比例提成;2:按金额提成
commission_feefloat
佣金金额,单位元,保留 2 位小数
third_promotion_infoobject
CPS业务必填,第三方推广信息
is_calculatedinteger
是否计佣;1:是;0:否
no_calculated_reasonstring
不计佣原因
commission_ratefloat
佣金比例,保留 2 位小数,不带百分号,如 10% 填10.00,CPS业务必传
commission_feefloat
佣金金额(实际计佣金额*佣金比例/100),单位元,保留 2 位小数,CPS业务必传
actual_commission_amountfloat
实际计算佣金的商品金额,不包括运费、优惠券等的金额,单位元,保留 2 位小数,CPS业务必传
is_settleinteger
商品是否已结算;1:是;0:否
settle_timestring
结算时间,unix时间戳 字段长度为 13 字节
coupon_infoarray
订单使用的券信息,数组类型
coupon_typeinteger
卡券类型;1:商家券;2:微信支付券
coupon_sub_typeinteger
卡券子类型;1:满减券;2:打折券;3:商品券;4:兑换券;5:线索券
coupon_amount_totalfloat
该类券优惠金额总额,单位默认为元
coupon_detailarray
该类券的细节券信息
coupon_codestring
券 id
external_coupon_idstring
券批次 id(该字段需要在优惠券接口中添加卡券批次)
coupon_namestring
券名称
coupon_amountfloat
分摊至该订单的该张券折扣金额,单位默认为元
target_urlobject
卡券领取页信息
url_miniprogramstringC
微信小程序落地页 url,当落地页为微信小程序时必填 字段长度最小 1 字节,长度最大 100 字节
miniprogram_appidstringC
微信小程序 appid,当落地页为微信小程序时必填 字段长度最小 1 字节,长度最大 100 字节
miniprogram_usernamestringC
小程序原始ID,登录小程序管理后台-设置-基本设置-帐号信息中,gh_xx,当落地页为微信小程序时必填字段长度最小 1 字节,长度最大 100 字节
url_miniprogram_qqstringC
qq小程序落地页 url,当落地页为QQ小程序时必填 字段长度最小 1 字节,长度最大 100 字节
miniprogram_appid_qqstringC
qq小程序 appid,当落地页为QQ小程序时必填 字段长度最小 1 字节,长度最大 100 字节
url_h5stringC
h5落地页url 字段长度最小 1 字节,长度最大 100 字节
url_liststring
可使用该卡券的商品/门店集合页链接
promotion_infoarray
主订单用到的活动信息,数组类型
promotion_typeinteger
活动类型;1:会员价;2:其他活动
external_promotion_idstring
订单中有使用的活动ID
promotion_namestring
活动名称
promotion_amountfloat
分摊至该订单的活动折扣金额,单位默认为元
payment_infoarray
主订单每种支付方式的支付信息,order_status = 1110时 payment_info非必填,其他状态码必填
combine_out_trade_nostring
微信支付场景,合单支付总订单号,要求32个字符内,只能是数字、大小写字母_-|*@ ,且在同一个商户号下唯一。示例值:P20150806125346
out_trade_numberstring
微信支付商户系统内部订单号,当 payment_type = 00009 时必填,只能是数字、大小写字母_-*且在同一个商户号下唯一
payment_typestringC
支付方式,见 枚举值
trans_idstringC
微信支付订单ID/流水号
trans_amountfloatC
金额,单位默认为元
express_infoobject
快递信息
goods_total_weightfloat
商品总重量,单位默认为克
receiver_country_codestring
国家编码
receiver_province_codestring
省份编码,见 民政部行政区划代码,440000
receiver_province_namestring
省份名称,XX省,字段长度最小 1 字节,长度最大 64 字节
receiver_city_codestring
城市编码,见 民政部行政区划代码
receiver_city_namestring
城市名称,XX市,字段长度最小 1 字节,长度最大 64 字节
receiver_district_codestring
区/县编码,见 民政部行政区划代码
receiver_district_namestring
区/县名称,XX区,字段长度最小 1 字节,长度最大 64 字节
receiver_addressstring
地址,字段长度最小 1 字节,长度最大 100 字节
receiver_namestring
收件人姓名,字段长度最小 1 字节,长度最大 100 字节
receiver_phonestring
收件人联系电话,字段长度最小 1 字节,长度最大 100 字节
expected_delivery_timestring
期望送货时间段,格式为“起始时间-结束时间”,如"9:00-12:00"
expected_delivery_datestring
期望送货日期,格式“YYYYMMDD”
express_package_infoarray
包裹信息
express_company_codestring
物流公司编码,枚举类型,枚举值请参见文章后面的“物流商 code”
express_company_namestring
物流公司名称
express_codestring
运单号
ship_timestring
发货时间,格式为时间戳 字段长度为 13 字节
logistics_statusstring
订单物流状态
express_pageobject
运费跳转页面,json字符串
miniprogram_pathstring
快递详情页跳转链接(小程序页面,小程序填此字段)
miniprogram_appidstring
小程序APPID,填写了miniprogram_path需填此字段
miniprogram_h5string
快递详情页跳转链接(h5页面,公众号填此字段)
express_package_infoarray
物流包裹信息
external_sku_idstring
商品sku id
numberinteger
商品数量
invoice_infoarray
发票信息,类型为数组
if_need_invoiceboolean
是否需要发票,true代表需要,false代表不需要
invoice_typestring
发票类型,枚举值,取值如下: 1000(增值税专用发票) 1001(普通发票) 1002(机动车专用发票) 1003(机打发票) 1004(定额发票 ) 1005(剪开式发票) 1006(其他)
invoice_titlestring
发票抬头
invoice_contentstring
发票内容
invoice_addition_infostring
发票附加信息
invoice_companystring
公司名称
invoice_taxpayerstring
纳税人识别号
registry_addressstring
注册地址
sha256_registry_phonestring
注册电话,sha256加密
registry_bank_namestring
开户银行
registry_bank_accountstring
开户账号
sha256_invoice_delivery_phonestring
发票收件人电话,sha256加密
invoice_numstring
发票号码
points_totalfloat
订单赠送总积分
target_urlobject
订单详情页信息
url_miniprogramstringC
微信小程序落地页url,当落地页为微信小程序时必填
miniprogram_appidstringC
微信小程序appid,当落地页为微信小程序时必填
miniprogram_usernamestringC
小程序原始ID,登录小程序管理后台-设置-基本设置-帐号信息中,gh_xx,当落地页为微信小程序时必填
url_miniprogram_qqstringC
qq小程序落地页url,当落地页为QQ小程序时必填
miniprogram_appid_qqstringC
qq小程序appid,当落地页为QQ小程序时必填
url_h5string
h5落地页url
is_deletedinteger
商家标记订单已删除,0:未删除;1:已删除,为空默认为 0

请求体示例

{
"account_id": 1111111111,
"user_action_set_id": 1111111111,
"orders": [
{
"external_order_id": "34452222",
"create_time": "1572395131732",
"order_source": "wxapp",
"order_type": 1,
"brand_id": "1455222",
"brand_name": "百丽",
"goods_num_total": 3,
"goods_weight": 400.0,
"goods_amount_total": 562.0,
"freight_amount": 10.0,
"order_amount": 572.0,
"payable_amount": 560.0,
"payment_amount": 560.0,
"order_status": "1150", // 见<枚举列表>页
"status_change_time": "1572395131732",
"user_info": {
"open_id": "ok4Qb0U0dFqJ2KiSoGBXKCIqXnFY",
"app_id": "wxc8f3e27b33ae9e8e",
"union_id": "k4Qb0U0dFqJ2K",
"sha256_user_phone": "9c0376063270573736d48ebd6a9e99230c0d8892671d5a79ef94e8c4eeccaf09",
"user_id": "q2Qb0U0dFqJ2KGE",
"member_id": "8f323e76jsw3ae9e8e",
"user_first_order_time": "1572395131732"
},
"goods_info": [
{
"external_sku_id": "cS1cWjrkFbFUA",
"primary_image_url": "https://img.ddimg.mobi/product/89bbccca93b8a1601347598489.jpg",
"sku_name_chinese": "鞋子蓝色",
"goods_amount": 60.0, // 不包含件数及不包含均摊优惠的商品金额
"payment_amount": 110.0, // 包含件数及包含优惠均摊后的金额
"is_gift": 0,
"external_spu_id": "F-306233",
"spu_name_chinese": "鞋子",
"sale_unit": "双",
"category_id": "0001",
"category_name": "服装",
"goods_num": 2,
"goods_weight": 350.0,
"store_info": {
"external_store_id": "9L33",
"store_name": "文华仓",
"store_city": "福州市"
},
"chan_info": [
{
"chan_wxapp": {
"chan_scene": "1140"
},
"chan_custom": {
"chan_custom_id": "123456",
"chan_custom_id_desc": "123456",
"chan_custom_cat_3": "123456",
"chan_custom_cat_3_desc": "123456",
"chan_custom_cat_2": "123456",
"chan_custom_cat_2_desc": "123456",
"chan_custom_cat_1": "123456",
"chan_custom_cat_1_desc": "123456"
},
"chan_id": "8_5a23p4ded6ff6384",
"chan_refer_app_id": "wxc8f3e27b33ae9e8e"
}
],
"commission_info": [
{
"commission_type": 1,
"commission_fee": 10.0
},
{
"commission_type": 1,
"commission_fee": 20.0
}
]
},
{
"external_sku_id": "caaajrkFbFUA",
"sku_name_chinese": "连衣裙红色",
"goods_amount": 90.0,
"payment_amount": 85.0,
"is_gift": 0,
"external_spu_id": "F-306233",
"spu_name_chinese": "连衣裙",
"sale_unit": "件",
"category_id": "0001",
"category_name": "服装",
"goods_num": 1,
"goods_weight": 350.0,
"store_info": {
"external_store_id": "9L33",
"store_name": "文华仓",
"store_city": "福州市"
},
"chan_info": [
{
"chan_wxapp": {
"chan_scene": "1140"
},
"chan_custom": {
"chan_custom_id": "123456",
"chan_custom_id_desc": "123456",
"chan_custom_cat_3": "123456",
"chan_custom_cat_3_desc": "123456",
"chan_custom_cat_2": "123456",
"chan_custom_cat_2_desc": "123456",
"chan_custom_cat_1": "123456",
"chan_custom_cat_1_desc": "123456"
},
"chan_id": "8_5a23p4ded6ff6384",
"chan_refer_app_id": "wxc8f3e27b33ae9e8e"
}
],
"commission_info": [
{
"commission_type": 1,
"commission_fee": 10.0
},
{
"commission_type": 1,
"commission_fee": 20.0
}
]
}
],
"coupon_info": [
{
"coupon_type": 1,
"coupon_amount_total": 200.0,
"coupon_detail": [
{
"external_coupon_id": "UWBE8873basfJ",
"coupon_batch_id": "37BHknfE832DW",
"coupon_name": "会员10元优惠券",
"coupon_amount": 100.0
},
{
"external_coupon_id": "46568873basfJ",
"coupon_batch_id": "37BHknfE832DW",
"coupon_name": "节日10元优惠券",
"coupon_amount": 100.0
}
]
},
{
"coupon_type": 1,
"coupon_amount_total": 30.0,
"coupon_detail": [
{
"external_coupon_id": "4558873basfJ",
"coupon_batch_id": "37455fE832DW",
"coupon_name": "支付2元优惠券",
"coupon_amount": 20.0
},
{
"external_coupon_id": "4558873basfJ",
"coupon_batch_id": "37455fE832DW",
"coupon_name": "支付叠加1元优惠券",
"coupon_amount": 10.0
}
]
}
],
"payment_info": [
{
"payment_type": "00009", // 见<枚举列表>页
"trans_id": "243245125",
"trans_amount": 100.0
},
{
"payment_type": "00004", // 见<枚举列表>页
"trans_id": "2566245125",
"trans_amount": 200.0
}
],
"express_info": {
"logistics_status": "3010",
"goods_total_weight": 150.0,
"receiver_name": "Jerry",
"sha256_receiver_phone": "9c0376063270573736d48ebd6a9e99230c0d8892671d5a79ef94e8c4eeccaf09",
"receiver_address": "广东省深圳市XXX",
"receiver_country_code": "CN",
"receiver_province_code": "440000",
"receiver_city_code": "440001",
"receiver_district_code": "440001",
"expected_delivery_time": "9:00-12:00",
"expected_delivery_date": "20190501",
"express_package_info": [
{
"express_company_code": "100003",
"express_company_name": "顺丰",
"express_code": "27427185",
"ship_time": "1572395131732",
"express_page": {
"miniprogram_path": "page/XXXX",
"miniprogram_appid": "wxc8f3e27b33ae9e8e",
"miniprogram_h5": "http://XXX"
},
"express_package_info": [
{
"external_sku_id": "7888372",
"number": 1
},
{
"external_sku_id": "FE-788837201",
"number": 3
}
]
}
]
},
"invoice_info": [
{
"if_need_invoice": false,
"invoice_type": "1002",
"invoice_title": "UUnw829auH",
"invoice_content": "F371BYSWfe",
"invoice_addition_info": "无",
"invoice_company": "广东深圳公司",
"invoice_taxpayer": "510107723420661",
"registry_address": "广东深圳市",
"sha256_registry_phone": "9c0376063270573736d48ebd6a9e99230c0d8892671d5a79ef94e8c4eeccaf09",
"registry_bank_name": "工商银行",
"registry_bank_account": "698374522",
"invoice_delivery_address": "广东深圳市",
"invoice_delivery_name": "Jerry",
"sha256_invoice_delivery_phone": "9c0376063270573736d48ebd6a9e99230c0d8892671d5a79ef94e8c4eeccaf09",
"invoice_num": "8377205631"
},
{
"if_need_invoice": true,
"invoice_type": "1001",
"invoice_title": "aaUnw829auH",
"invoice_content": "aa71BYSWfe",
"invoice_addition_info": "无",
"invoice_company": "广东深圳公司",
"invoice_taxpayer": "510107723420661",
"registry_address": "广东深圳市",
"sha256_registry_phone": "9c0376063270573736d48ebd6a9e99230c0d8892671d5a79ef94e8c4eeccaf09",
"registry_bank_name": "工商银行",
"registry_bank_account": "698374522",
"invoice_delivery_address": "广东深圳市",
"invoice_delivery_name": "tom",
"sha256_invoice_delivery_phone": "9c0376063270573736d48ebd6a9e99230c0d8892671d5a79ef94e8c4eeccaf09",
"invoice_num": "8377205631"
}
],
"points_total": 200.0,
"is_deleted": 0
}
]
}

应答体结构

名称类型是否一定返回描述
codeintegerY返回码,等于0表示成功,不等于0表示错误,具体见文档附录
messagestringY错误描述,code不等于0时,message为错误描述
message_cnstring中文错误描述,code不等于0时,message_cn为错误情况的中文描述
dataobject资源数据,具体返回内容见各接口定义,只在code等于0时可能返回
errorsobject详细错误信息,只在code不等于0时可能返回

应答示例

{
"code": 0,
"message": "",
"message_cn": {}
}



FAQ

问:订单状态很多,该传哪些状态?

答:必传的订单状态有 1110 待支付,1130未支付取消,1140已支付未发货取消,1150 已支付待发货,1160 已发货,1180 销售完成/已收货。具体可参考 枚举列表


问:1130未支付取消和1140已支付未发货取消的区别是?

答:1130未支付取消是指用户下单后,在支付之前发起的取消订单,该状态下的订单不会计入 GMV;1140已支付未发货取消是指用户下单支付后,在发货之前发起的取消订单,该状态下的订单计入 GMV。


问:订单同步的时效性要求是?

答:订单要求实时上报(5分钟内)。


问:订单使用为非微信支付的方式(如购物卡、优惠券抵扣后订单为0元等)无微信支付流水号的,文档中要求必填的 trans_id 该如何传输?

答:此时 trans_id 可传入 external_order_id(订单号)的值。


问:订单金额如何传输?

答:商品a,单价20 元,2件;商品b, 单价30 元,2件;运费 10 元,满足了满 100 减 10 元的活动,用户最终支付了 100 元,传输内容如下:

goods_amount_total 100 元

freight_amount 10元

order_amount 110元

payable_amount 100元

payment_amount 100元

goods_info[]中

商品a goods_amount = 20元,payment_amount = 36 元

商品b goods_amount = 30元,payment_amount = 54 元


问:货到付款订单金额如何传输?

答:货到付款订单由于支付后移,上报会与普通订单有所不同。因有数侧确定销售是以前端 custom_order.order_status="payed" (支付)及后端 add_order.order_status="1150" (已支付待发货)确定 ,故如何上报给有数是基于您小程序货到付款的订单是何时计入销售,目前有以下有两种常见情况:

1)下单计入销售上报方法

下单时前端custom_order.order_status同时上报 "give_order"(下单)和 "payed"(支付),后端 add_order.order_status上报 "1110"(待支付) 和 "1150"(已支付待发货)。

2)发货计入销售上报方法

  1. 下单时前端custom_order.order_status同时上报 "give_order"(下单),后端 add_order.order_status上报 "1110"(待支付) 。
  2. 发货时后端 add_order.order_status上报 "1150"(已支付待发货)。



该内容是否有帮助?