供应商API文档

编制	日期	版本
姜鹏	2023.11.14	V1.0

1 文档范围

2 全局约定

2.1 返回码

返回码	说明	类型
401	没有权限	string
403	拒绝访问	string
200	正确返回	string
429	网关限流返回。	string
其他	业务异常返回。如 token过期、刷新token过期、客户端调用已达最大次数。 https://confluence.mideazy.com/pages/viewpage.action?pageId=451739700	string

所有的返回码详细请参见： https://confluence.mideazy.com/pages/viewpage.action?pageId=451739700

重要说明：返回码新增 429，代表网关限流生效，请业务端捕获到此返回码后，建议等待至少1秒后再执行重试机制，可以直接Toast 给前端。

注：参数错误的情况， code, message 必返。

{
  "code", "非200",
  "message": "错误描述"

}

2.2 数据字典

2.2.1 供应商来源

字段	值	业务说明
supply_type	midea	供应商：美的智慧家

2.2.2 订单支付状态

字段	值	业务说明
payment_state	string	支付状态：1：待支付 2：支付成功 3：支付关闭，失败

2.2.3 商品上下架状态

字段	值	业务说明
status	Int	status 商品状态; 1-下架 2-上架

2.2.4 订单状态

字段	值	业务说明
status	string	1 - 等待付款
		2 - 等待发货
		3 - 已发货（等待签收）
		4 - 交易成功（确认收货）# 终态
		5 - 交易（未付款）取消 # 终态
		8 - 退款达成（款项处理中，等待打款操作）
		9 - 交易结束 # 终态

2.2.5 字段说明

业务中台字段与供应商字段映射关系详见：https://docs.qq.com/sheet/DUG16RVRXUWZIYXhR?tab=BB08J2

业务开发人员可以不用关注这个，以此业务中台的文档协议进行对接即可。

2.2.6 本期接口域名

域名	环境
https://tx-platform-biz-sit.remacsmart.com	SIT
https://tx-platform-biz.remacsmart.com	生产

2.3 API 返回值风格

所有的返回字段尽可能按下划线而非驼峰格式的返回。

3 安全规范

业务访问中台的所有接口均需要使用 bizToken 作为HTTP头部标识。详见：

https://confluence.mideazy.com/pages/viewpage.action?pageId=451739700

其中： bizToken为业务应用根据中台分配的client_id, client_secret 生成的Token。详细见： https://confluence.mideazy.com/pages/viewpage.action?pageId=451739700

4 API

4.1 获取供应商商品分页数据

URL: /tx/platform-biz/openapi/skus/page

方法： POST / PUT

HTTP头： bizToken

请求体：body 约定如下表

字段	类型	是否必传	说明
biz_data	JSONObject	是	业务参数
supply_type		是	见数据字典《2.2.1 供应商来源》

biz_data 业务参数属性列表：

字段	类型	是否必传	说明
page_no	int	是	页码
page_size	int	是	分页尺寸，最大尺寸为 100。超过将取最大值100.
sku_ids	Array(string)	否	供应商的商品SKU ID列表。sku_id 为字符类型，以兼容不同供应商的sku_id

请求示例：

{"supply_type": "midea", "biz_data": {"page_no": 1, "page_size": 20, "sku_ids":["1004865"] }

返回结果

{
  "code": "200",
  "messsage": "success",
  "data": {
    "trace_id": "995c40df9e23ed8766fcaa3aca59c13e",
    "total": 1,
    "sku_list": [
      {
        "sku_id": 1004865,
        "category": "",
        "category_id": 113,
        "sku_name": "【测试商品】空气炸锅 MF-KZ30E201 KZ30E201G 1325W",
        "status": 2,
        "sale_price": 20,
        "item_detail_url": "https://sitm.midea.cn/detail/index?itemid=10000000010012071004865"

      },
      ...
    ]
  }
}

4.2 获取供应商商品详情

URL: /tx/platform-biz/openapi/sku/detail

方法： POST / PUT

HTTP头： bizToken

请求体：body 约定如下表

字段	类型	是否必传	说明
biz_data	JSONObject	是	业务参数
supply_type		是	见数据字典《2.2.1 供应商来源》

biz_data 业务参数属性列表：

字段	类型	是否必传	说明
sku_id	String	是	商品SKU的ID, 注意是字符类型。

请求示例：

{"supply_type": "midea", "biz_data": {"sku_id":  :"1004865" }}

返回结果

{
  "code": "200",
  "message": "success",
  "data": {
    "trace_id": "27580b200ef647c12af419084b334351",
    "sku_detail": {
      "sku_id": 1004865,
      "sku_name": "【测试商品】空气炸锅 MF-KZ30E201 KZ30E201G 1325W",
      "imgs": [
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619028312051.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619028312115.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619028305654.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619028305268.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619028310925.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619028310853.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619028311120.jpg"
      ],
      "pc_descs": [
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027958384.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027888922.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027929220.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027915284.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027923262.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027915836.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027966461.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027960381.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027973257.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027916254.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027924285.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027916058.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027921237.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027915401.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027959859.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027963684.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027886435.jpg"
      ],
      "mobile_descs": [
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027958384.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027888922.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027929220.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027915284.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027923262.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027915836.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027966461.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027960381.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027973257.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027916254.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027924285.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027916058.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027921237.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027915401.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027959859.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027963684.jpg",
        "https://dsdcp.smartmidea.net/mcsp/prod/20210422/1619027886435.jpg"
      ],
      "sale_price": 20,
      "settle_price": 20,
      "pkginfos": [
        {
          "netlength": 220,
          "netwidth": 325,
          "netheight": 275,
          "netweight": 3200,
          "pkglength": 300,
          "pkgwidth": 300
        }
      ],
      "product_model": "MF-KZ30E201",
      "status": 2,
      "selling_point": "空气热能烹饪，少油健康 、旋钮控制，时间可调 ;双重安全防护 、不粘设计，容易清洗 、外观小巧、3L容量，美味分享\"\n"

  }
}

返回值说明：

supply_type	string	供应链
sku_name	string	商品名称
status	number	商品状态
category_id	number	供应商的产品分类
category	string	品类
measure_unit	string	计量单位
brand	string	品牌
selling_point	string	商品卖点
imgs	string[]	商品图片
pc_descs	string[]	商详（pc）
mobile_descs	string[]	移动端商详
sku_id	number	外部商品编码
product_model	string	产品型号
sale_price	number	零售指导价
settle_price	number	结算价
introduction	string	产品介绍
tech_param	string	技术参数
installation_condition	string	安装条件
cabling_plan	string	布线方案
supportmoduleinfo	object	服务支持
pkginfos	object[]	包装信息。对象数组。[ { "netlength":"", "netwidth":"", "netheight":"", "netweight":"", "pkglength":"", "pkgwidth":"", "pkgheight":"", "pkgweight":"" }, { "netlength":"", "netwidth":"", "netheight":"", "netweight":"", "pkglength":"", "pkgwidth":"", "pkgheight":"", "pkgweight":"" } ]
brand	string	品牌名称

4.3 查询商品库存

URL: /tx/platform-biz/openapi/sku/stock

方法： POST / PUT

HTTP头： bizToken

请求体：body 约定如下表

字段	类型	是否必传	说明
biz_data	JSONObject	是	业务参数
supply_type		是	见数据字典《2.2.1 供应商来源》

biz_data 业务参数属性列表：

字段	类型	是否必传	说明
sku_ids	Array	是	商品SKU的ID集合
province_code	Int	是	省（直辖市）编码
city_code	Int	是	市编码
region_code	Int	是	区编码

请求示例：

{"supply_type": "midea",      "biz_data": {"sku_ids": ["1004865"], "province_code": 110000,  "city_code": 110000, 
"region_code": 110101 } }

返回结果

{
  "code": "200",
  "message": "success",
  "data": {
    "total": 1,
    "trace_id": "14375870dc34c7c7809b9adff7c441e1",
    "stocks": [
      {
        "sku_id": 1004865,
        "stock": 97981,
        "store_id": 0
      }
    ]
  }
}

total: 查询总数

stock: 库存

store_id: 仓库id

4.4 批量下单

URL: /tx/platform-biz/openapi/order/submit/batch

方法： POST / PUT

HTTP头： bizToken

请求体：body 约定如下表

字段	类型	是否必传	说明
biz_data	JSONArray	是	业务参数
supply_type		是	见数据字典《2.2.1 供应商来源》

biz_data 业务参数属性列表：

字段	类型	是否必传	说明
orders	JSONArray	是	订单集合。当supply_type = midea 订单集合上限200，其他供应商上限待定。

订单对象

字段	类型	是否必传	说明
out_order_id	String	是	业务系统订单标识
business_type	String	是	业务类型，此处为 tiance
sku_id	String	是	sku ID
purchase_num	int	是	购买数量
province_code	int	是	收件人省编码；使用业务中台行政区划编码
city_code	int	是	收件人市编码；使用业务中台行政区划编码
region_code	int	是	收件人区编码；使用业务中台行政区划编码
province_name	String	是	收件人省名称，需要通过这个名称检索不同供应商的地址码
city_name	String	是	收件人市名称，需要通过这个名称检索不同供应商的地址码
region_name	String	是	收件人区名称，需要通过这个名称检索不同供应商的地址码
recv_name	String	是	收件人姓名
recv_address	String	是	收件人地址
recv_mobile	String	是	收件人手机号
recv_postcode	String	否	收件人邮编。由业务中台自行匹配邮编。
invoice_type	Int	否	1-普通纸质发票；3-专用增值税发票；4-需要电子发票。supply_type=midea 不用传。
invoice_drawee_type	Int	否	发票受票人类型， 1-个人，2-企业。invoice_type=1,4时必填。supply_type=midea 不用传。
invoice_head	String	否	发票抬头, invoice_drawee_type=2时必填。supply_type=midea 不用传。
taxpayer_code	String	否	纳税人识别号, invoice_drawee_type=2时必填, invoicetype=1,3时不填。supply_type=midea 不用传。
buyer_note	String	否	买家备注。

请求示例：

{"supply_type": "midea",  "biz_data": [ {"out_order_id": "22345678923", "business_type": "tiance", "sku_id": "1004865",   "purchase_num": 1,   "province_code": 420000 ,  "city_code": 420700,    "region_code":420703,    "recv_name": "姜生",     "recv_address": "天王老子村",     "recv_mobile": "13926003676",  "recv_postcode": "420703", "invoice_type": 1 }] }

返回结果

（1）完全失败返回

注：异常返回会返回每一个订单下单失败的详细原因。多出一个 faile_order_list JSON数组。

{
  "code": "9999",
  "message": "下单失败,\n",
  "data": {
    "trace_id": "",
    "fail_order_list": [
      {
        "out_order_id": "0112112345678992",
        "err_code": 560074798,
        "err_msg": "外部订单号已经存在，对应订单号[1110510730800200000]"
      }
    ],
    "bdeal_info": {
      "bdeal_id": "",
      "deal_list": null
    }
  }
}

(2) 完全成功返回：

{
  "code": "200",
  "message": "success",
  "data": {
    "trace_id": "01ed770c15cf9601decd51fc99dbfbce",
    "fail_order_list": [],
    "bdeal_info": {
      "bdeal_id": "A25835630020",
      "deal_list": [
        {
          "deal_id": "1110510731800200000",
          "out_order_id": "1112112345678992"
        }
      ]
    }
  }
}

bdeal_id: 供应商返回的大订单ID，对应业务方的多个批量订单号，请业务方做好关联。

out_order_id: 业务方的订单ID

deal_id: 供应商的订单号。请业务方做好关联，订单详情的查询依赖此字段。

（3）部分成功，部分失败返回

请求示例：

{"supply_type": "midea",  "biz_data": [ {"out_order_id": "111121123456788956", "business_type": "tiance", "sku_id": "1004928",   "purchase_num": 1,   "province_code": 420000 ,  "city_code": 420700,    "region_code":420703,  "recv_name": "姜生",     "recv_address": "天王老子村",     "recv_mobile": "13926003676",  "recv_postcode": "420703", "invoice_type": 1 }, {"out_order_id": "11112112345678895691", "business_type": "tiance", "sku_id": "1004928",   "purchase_num": 1,   "province_code": 420000 ,  "city_code": 420700,    "region_code":420703,  "recv_name": "姜生",     "recv_address": "天王老子村",     "recv_mobile": "13926003676",  "recv_postcode": "420703", "invoice_type": 1 }] }

返回示例：

{
  "code": "200",
  "message": "success",
  "data": {
    "trace_id": "7b7d6097e4e948c2cf1eecdb5df4330d",
    "fail_order_list": [
      {
        "out_order_id": "111121123456788956",
        "err_code": 560074798,
        "err_msg": "外部订单号已经存在，对应订单号[1110510739400200000]"
      }
    ],
    "bdeal_info": {
      "bdeal_id": "A25836320020",
      "deal_list": [
        {
          "deal_id": "1110510743400200000",
          "out_order_id": "11112112345678895691"
        }
      ]
    }
  }
}

批量提交多个订会出现部分成功部分失败的情况。成功的会返回大订单号及小订单号；失败的后返回失败的原因和业务单号。

注意：业务端错误信息处理：

返回结果处理：

1: 无 data对象，返回错误直接取 message；

2: 有 data 存在两种情况：

2-1 需要看 data中的 fail_order_list 集合是否有值，如果有值需要取集合对象中的对象 err_msg字段，用于准确描述订单失败原因 ;

2-2 data中的 fail_order_list 集合没有值，直接取 message

4.5 发起支付

URL: /tx/platform-biz/openapi/order/pay/submit

方法： POST / PUT

HTTP头： bizToken

请求体：body 约定如下表

字段	类型	是否必传	说明
biz_data	JSONObject	是	业务参数
supply_type		是	见数据字典《2.2.1 供应商来源》

biz_data 业务参数属性列表：

字段	类型	是否必传	说明
bdeal_id	String	是	供应商大订单ID

请求示例：

{"supply_type": "midea", "biz_data": {"bdeal_id": "A25822270020" }}

返回结果

{
  "code": "200",
  "message": "success",
  "data": {
    "batch_payment_no": "G1010077691002000000000107214092",
    "payment_state": "1",
    "create_time": "2023-11-27 15:36:00",
    "payment_total_amount": 20,
    "provider_trade_no": "",
    "trace_id": "aabafe9aa722c3fde24485e7fc9180d8"
  }
}

返回字段说明

参数名称	类型	是否必须	示例	备注
batch_payment_no	string	是	G1010077691023100000000107182640	支付批次号
payment_state	String	是	1	见数据字典《2.2.2 订单支付状态》
create_time	string	是	2023-07-01 12:32:22	拉起支付时间
payment_total_amount	int	是	1235	支付金额，单位为分
provider_trade_no	string	是	23423423423423454454	支付商交易流水号

4.6 单个支付记录查询

URL: /tx/platform-biz/openapi/order/pay/query/bybpno

方法： POST / PUT

HTTP头： bizToken

请求体：body 约定如下表

字段	类型	是否必传	说明
biz_data	JSONObject	是	业务参数
supply_type		是	见数据字典《2.2.1 供应商来源》

biz_data 业务参数属性列表：

字段	类型	是否必传	说明
batch_payment_no	String	是	支付批次号

请求示例：

{"supply_type": "midea",  "biz_data": { "batch_payment_no": "G1010077691002000000000107214092"} }

返回结果

{
  "code": "200",
  "message": "success",
  "data": {
    "trace_id": "8006fe23fdf1fd015f992f5436ec0238",
    "bdeal_id": "",
    "batch_payment_no": "G1010077691002000000000107214092",
    "payment_state": "2",
    "create_time": "2023-11-27 15:36:00",
    "payment_total_amount": 20,
    "provider_trade_no": "1071202311270000000000",
    "return_time": "2023-11-27 15:36:01"
  }
}

4.7 按大单号查询支付记录

URL: /tx/platform-biz/openapi/order/pay/query/bybdid

方法： POST / PUT

HTTP头： bizToken

请求体：body 约定如下表

字段	类型	是否必传	说明
biz_data	JSONObject	是	业务参数
supply_type		是	见数据字典《2.2.1 供应商来源》

biz_data 业务参数属性列表：

字段	类型	是否必传	说明
bdeal_id	String	是	供应商大单号

请求示例：

{"supply_type": "midea",  "biz_data": { "bdeal_id": "A25822270020"} }

返回结果

{
  "code": "200",
  "message": "success",
  "data": {
    "trace_id": "5971a7c8fb7e481ed18e64e3256c5c70",
    "batch_payments": [
      {
        "bdeal_id": "A25822270020",
        "batch_payment_no": "G1010077691002000000000107214011",
        "payment_state": "2",
        "create_time": "2023-11-22 13:32:45",
        "payment_total_amount": 20,
        "provider_trade_no": "1071202311220000001002",
        "return_time": "2023-11-22 13:34:25"
      }
    ]
  }
}

provider_trade_no: 支付商交易流水号

payment_state: 参考数据字典《2.2.2 订单支付状态》

4.8 批量查询订单状态

URL: /tx/platform-biz/openapi/order/status/batch/query

方法： POST / PUT

HTTP头： bizToken

请求体：body 约定如下表

字段	类型	是否必传	说明
biz_data	JSONObject	是	业务参数
supply_type		是	见数据字典《2.2.1 供应商来源》

biz_data 业务参数属性列表：

字段	类型	是否必传	说明
deal_ids	String[]	是	供应商订单号集合，注：不是供应商的大单号。

请求示例：

{"supply_type": "midea",  "biz_data": { "deal_ids": ["1110510734800200000"]} }

返回结果


{
  "code": "200",
  "message": "success",
  "data": {
    "trace_id": "f7c932e8263765da6d960b99ad594218",
    "orders_status": [
      {
        "deal_id": "1110510734800200000",
        "status": "1"
      }
    ]
  }
}

status: 订单状态，详见数据字典《2.2.4 订单状态》

4.9 订单详情查询

URL: /tx/platform-biz/openapi/order/detail

方法： POST / PUT

HTTP头： bizToken

请求体：body 约定如下表

字段	类型	是否必传	说明
biz_data	JSONObject	是	业务参数
supply_type		是	见数据字典《2.2.1 供应商来源》

biz_data 业务参数属性列表：

字段	类型	是否必传	说明
deal_id	String	是	供应商订单号，注：不是供应商的大单号。

请求示例：

{"supply_type": "midea",  "biz_data": { "deal_id": "1110510734800200000"} }

返回结果

{
  "code": "200",
  "message": "success",
  "data": {
    "trace_id": "1eea79137b6dc2e30d4149ab7ee6ba1d",
    "deal_info": {
      "dea_lid": "1110510739400200000",
      "deal_state": 3,
      "deal_payment": 299900,
      "pay_time": "2023-12-01 14:03:19",
      "confirm_recv_time": "1970-01-01 08:00:00",
      "express_no": "333",
      "express_company_id": "1",
      "express_company_name": "安得物流"
    }
  }
}

deal_state: 参见数据字典《2.2.4 订单状态》

express_no：供应商物流快递单号

express_company_name：供应商物流公司名称

express_company_id：供应商的物流公司id

confirm_recv_time：确认收货时间

供应商API

供应商API文档

1 文档范围

2 全局约定

2.1 返回码

2.2 数据字典

2.2.1 供应商来源

2.2.2 订单支付状态

2.2.3 商品上下架状态

2.2.4 订单状态

2.2.5 字段说明

2.2.6 本期接口域名

2.3 API 返回值风格

3 安全规范

4 API

4.1 获取供应商商品分页数据

4.2 获取供应商商品详情

4.3 查询商品库存

4.4 批量下单

4.5 发起支付

4.6 单个支付记录查询

4.7 按大单号查询支付记录

4.8 批量查询订单状态

4.9 订单详情查询

results matching ""

No results matching ""