# 订单添加/变更


开发之前需拥有一个腾讯数据接入数据源 (dataSourceId),可将 dataSourceId 理解为数据的集合。创建一个数据源后,所有接口传输数据时都可重复使用。


# 请求地址

域名/data-api/v1/order/add_order


# 请求方法

POST


# 请求参数

参数名 样例 描述
app_id abc 分配的app_id
nonce 61794670f155b 随机字符串
sign sha256 签名算法
timestamp 1569232087 请求时间戳(秒级)
signature aee30792812d7b09ba7d3aa67c24e16c6a7ea81282ac728ad5966dd1b3eef6d5 签名结果

# 请求体类型

application/json


# 请求体参数

名称
类型
必填
描述
dataSourceIdstringY数据源id(create方法返回的data.dataSource.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订单来源,枚举值:商家小程序:wxapp;商家app:app;商家H5:mobileweb;商家pcweb:pcweb;线下人工pos:offstore_pos_manual;线下自助收银:offstore_pos_self_help;其他:other
order_typeintegerY订单类型;1:普通订单;2:充值订单;3:消费订单(如停车费);4:预售订单_预付;5:预售订单_尾款;6:商品券订单(指定商品的券,视同为购买了商品);7:积分订单;8:代金券订单(所有商品可使用的券) 普通购买商品订单传 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主订单状态,1110待支付,1130未支付取消,1140已支付未发货取消,1150已支付待发货/已支付待核销,1160已发货,1180销售完成/已收货/已核销,2150已失效(违规类订单)
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_infostringCqq浏览器用户标识,例 5dd6ddffe1440, 接入qq浏览器业务必填
chan_id_hjstringC惠聚用户标识,例 63_5a23p4ded6ff6384,接入惠聚-发现福利业务必填
member_idstring下单人会员号
card_levelstring会员卡等级
user_first_order_timestring下单人在KA注册后首次下单时间,格式为UNIX时间戳 字段长度为 13 字节
goods_infoarrayY主订单商品信息,数组类型,每个sku存一个数组单位
external_sku_idstringYsku 编号
primary_image_urlstring商品主图
sku_name_chinesestringYsku 名称
goods_amountfloatY单件商品原价,单位默认为元
current_amountfloat当前商品的单件现价,单位默认为元
payment_amountfloatY多件商品实付金额(分摊了优惠的金额),单位默认为元,注:有数GMV计算使用该字段
is_giftinteger是否赠品,0代表非赠品,1代表赠品
external_spu_idstringYsku 所属 spu 编号,若无 spu,传输内容请与 external_sku_id 保持一致
spu_name_chinesestringYspu 名称,若无 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_qqstringCqq小程序落地页 url,当落地页为QQ小程序时必填 字段长度最小 1 字节,长度最大 100 字节
miniprogram_appid_qqstringCqq小程序 appid,当落地页为QQ小程序时必填 字段长度最小 1 字节,长度最大 100 字节
url_h5stringCh5落地页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_infostringqq浏览器用户标识,例 5dd6ddffe1440,接入qq浏览器业务必填
commission_infoarray佣金,json字符串
commission_typeinteger佣金类型,枚举值如下:1:按比例提成;2:按金额提成
commission_feefloat佣金金额,单位元,保留 2 位小数
third_promotion_infoobjectCPS业务必填,第三方推广信息
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:线索券;6:自定义券;7:运费券
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_qqstringCqq小程序落地页 url,当落地页为QQ小程序时必填 字段长度最小 1 字节,长度最大 100 字节
miniprogram_appid_qqstringCqq小程序 appid,当落地页为QQ小程序时必填 字段长度最小 1 字节,长度最大 100 字节
url_h5stringCh5落地页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非必填,其他状态码必填
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_qqstringCqq小程序落地页url,当落地页为QQ小程序时必填
miniprogram_appid_qqstringCqq小程序appid,当落地页为QQ小程序时必填
url_h5stringh5落地页url
is_deletedinteger商家标记订单已删除,0:未删除;1:已删除,为空默认为 0

# 请求体示例

{
  "dataSourceId": "101",
  "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": [
            {
              "coupon_code": "UWBE8873dsfdaes",
              "external_coupon_id": "37BHknfE832DW",
              "coupon_name": "会员10元优惠券",
              "coupon_amount": 100.0
            },
            {
              "coupon_code": "46568873basfJ",
              "external_coupon_id": "37BHknfE832DW",
              "coupon_name": "节日10元优惠券",
              "coupon_amount": 100.0
            }
          ]
        },
        {
          "coupon_type": 1,
          "coupon_amount_total": 30.0,
          "coupon_detail": [
            {
              "coupon_code": "455882xwenad",
              "external_coupon_id": "37455fE832ZZ",
              "coupon_name": "支付2元优惠券",
              "coupon_amount": 20.0
            },
            {
              "coupon_code": "455892sxsfds",
              "external_coupon_id": "37455fE832ZZ",
              "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
    }
  ]
}

# 应答体结构

名称
类型
描述
retcodeinteger返回码
errmsgstring错误信息
datajson object响应内容

# 应答示例

{
  "retcode":0,
  "errmsg":"",
  "data": {}
}



# 常见FAQ

问:创建数据仓库时返回retcode: 16 errmsg: data_source_already_exist,该如何处理?

答:该返回代表该接口已创建过数据仓库,请使用获取有数数据仓库接口获取已创建好的 dataSourceId 。


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

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


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

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


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

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


问:订单使用为非微信支付的方式(如购物卡、优惠券抵扣后订单为0元等)该如何上报数据?

答:

payment_info.payment_type 传"00001";

payment_info.trans_id 传 external_order_id(订单号)的值;

payment_info.trans_amount 传积分兑换为货币后的金额,如顾客支付订单 10000 积分,贵司按 100 积分 = 1 元比例管理积分,则 payment_info.trans_amount 传 100.00。


问:订单金额如何传输?

答:商品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"(已支付待发货)。

更多疑问,可前往常见问题清单。