淘宝闪购

概览

本文档描述采购端调用淘宝闪购模块的外部接口。接口所属入口均为 App（采购端），实际访问路径以网关前缀配置为准。

接口列表

功能	方法	路径
获取 H5 链接	GET	/taobao-flash-sale/setting/h5-link
联合登录	POST	/taobao-flash-sale/auth/union-login
创建订单	POST	/taobao-flash-sale/order/create
查询本地订单详情	GET	/taobao-flash-sale/order/detail
查询 TBSG 上游订单详情	GET	/taobao-flash-sale/order/tbsg-detail
查询 BYN 订单详情	GET	/taobao-flash-sale/order/byn-detail
查询 TBSG 退款记录	GET	/taobao-flash-sale/order/refund-record

获取 H5 链接

接口信息

项目	说明
接口路径	GET /taobao-flash-sale/setting/h5-link
功能描述	获取后台配置的淘宝闪购 H5 链接
请求参数	无

成功响应

{
  "code": 0,
  "message": "success",
  "data": {
    "taobaoH5Link": "https://flashsale.taobao.com"
  }
}

字段说明

参数名	类型	说明
data.taobaoH5Link	string	淘宝闪购 H5 链接，来源于后台基础设置

联合登录

接口信息

项目	说明
接口路径	POST /taobao-flash-sale/auth/union-login
功能描述	采购端用户联合登录上游，获取上游访问 token
上游接口	POST /api/v3/auth/union_login

请求 Header

Header	必填	说明
Content-Type	是	固定为 application/json
app-type	否	透传给上游，例如 H5
x-token	否	采购端登录 token，用于识别采购端信息

请求参数

参数名	类型	必填	说明
out_uid	string	是	外部用户 ID
area_code	string	否	手机区号
phone	string	是	手机号；需要同时传 validate_code 或 password
validate_code	string	否	短信验证码
password	string	否	密码
invite_code	string	否	邀请码
parent_uids	string	否	上级用户 ID 链
nick	string	否	昵称
avatar	string	否	头像 URL
wx_appid	string	否	微信 AppID
wx_openid	string	否	微信 OpenID
self_ratio	string	否	自购比例，按上游规则透传
share_ratio	string	否	分享比例，按上游规则透传

请求示例

POST /taobao-flash-sale/auth/union-login
Content-Type: application/json
app-type: H5

{
  "out_uid": "1",
  "phone": "18686794695",
  "password": "123123",
  "nick": "tester",
  "invite_code": "AC4GYHG"
}

成功响应

{
  "code": 0,
  "message": "success",
  "data": {
    "token": "upstream-token"
  }
}

字段说明

参数名	类型	说明
data.token	string	上游联合登录返回的 token

失败响应示例

{
  "code": 7,
  "msg": "out_uid is required"
}

创建订单

接口信息

项目	说明
接口路径	POST /taobao-flash-sale/order/create
功能描述	采购端创建淘宝闪购订单，并自动扣减账户余额
幂等性	支持，通过 outId 去重

请求参数

参数名	类型	必填	说明
outId	string	是	三方订单号（幂等 Key），建议使用业务唯一标识
biyingOrderSN	string	是	必应鸟订单号，用于查询上游 TBSG 订单详情

创建订单金额不从下游入参读取，系统会根据上游订单详情中的 pay_amount 写入并扣款。

请求示例

{
  "outId": "ORD_20240115_001",
  "biyingOrderSN": "BY20240115001"
}

成功响应

{
  "code": 0,
  "message": "success",
  "data": {
    "middleOrderSN": "17808994741230001",
    "orderStatus": 2,
    "payAmount": 99.9,
    "createdAt": "2024-01-15T14:30:25+08:00"
  }
}

响应字段

参数名	类型	说明
data.middleOrderSN	string	中台订单号
data.orderStatus	int	订单状态，见“订单状态码”
data.payAmount	float64	实际付款金额
data.createdAt	string	创建时间，ISO 8601 格式

失败响应示例

{
  "code": 7,
  "msg": "upstream pay_amount must be greater than 0"
}

查询本地订单详情

接口信息

项目	说明
接口路径	GET /taobao-flash-sale/order/detail
功能描述	根据下游单号查询淘宝闪购本地订单详情，不请求上游

请求参数

参数名	类型	必填	说明
outId	string	是	下游单号/三方订单号，对应本地订单表 out_id

兼容参数名：out_id、downstreamOrderNo。

请求示例

GET /taobao-flash-sale/order/detail?outId=ORD_20240115_001

成功响应

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "middleOrderSN": "17808994741230001",
    "outId": "ORD_20240115_001",
    "biyingOrderSN": "BY20240115001",
    "upstreamOrderSN": "8069420328978571688",
    "goodsName": "商品名称",
    "goodsImage": "https://example.com/goods.jpg",
    "storeName": "门店名称",
    "orderAmount": 99.9,
    "payAmount": 99.9,
    "payStatus": 2,
    "orderStatus": 2,
    "orderStatusText": "已付款",
    "createdAt": "2024-01-15T14:30:25+08:00"
  }
}

失败响应示例

{
  "code": 7,
  "msg": "订单不存在"
}

查询 TBSG 上游订单详情

接口信息

项目	说明
接口路径	GET /taobao-flash-sale/order/tbsg-detail
功能描述	根据上游订单号实时查询 TBSG 上游订单详情
数据来源	上游 api/v3/tbsg/orders 接口

请求参数

参数名	类型	必填	说明
order_no	string	是	TBSG 上游订单号

兼容参数名：orderNo、upstreamOrderSN。

请求示例

GET /taobao-flash-sale/order/tbsg-detail?order_no=8069420336687632846

成功响应

{
  "code": 0,
  "message": "success",
  "data": {
    "orderSN": "8069420336687632846",
    "goodsName": "商品名称",
    "goodsId": "123456",
    "goodsImage": "https://example.com/goods.jpg",
    "storeName": "门店名称",
    "orderAmount": 99.9,
    "payAmount": 88.8,
    "orderStatus": 2,
    "orderStatusText": "已付款",
    "createTime": "2026-06-08 14:20:46",
    "receiveTime": "2026-06-08 14:30:46",
    "commissionAmount": 1.41,
    "buyerOutUid": "buyer-001",
    "buyerPhone": "13800000000",
    "receiverName": "张三",
    "receiverPhone": "13800000000",
    "receiverProvince": "浙江省",
    "receiverCity": "杭州市",
    "receiverDistrict": "西湖区",
    "receiverAddress": "详细地址"
  }
}

响应字段

参数名	类型	说明
data.orderSN	string	TBSG 上游订单号
data.goodsName	string	商品名称
data.goodsId	string	商品 ID
data.goodsImage	string	商品图片
data.storeName	string	店铺/门店名称
data.orderAmount	float64	订单金额
data.payAmount	float64	实付金额，对应上游 pay_amount
data.orderStatus	int	订单状态，已映射为本地订单状态码
data.orderStatusText	string	订单状态文本
data.createTime	string	上游下单时间
data.receiveTime	string	上游收货时间
data.commissionAmount	float64	预估佣金金额
data.buyerOutUid	string	上游买家外部 UID
data.buyerPhone	string	上游买家手机号
data.receiverName	string	收货人姓名
data.receiverPhone	string	收货人手机号
data.receiverProvince	string	收货省份
data.receiverCity	string	收货城市
data.receiverDistrict	string	收货区县
data.receiverAddress	string	收货详细地址

失败响应示例

{
  "code": 7,
  "msg": "order_no不能为空"
}

查询 BYN 订单详情

接口信息

项目	说明
接口路径	GET /taobao-flash-sale/order/byn-detail
功能描述	根据必应鸟订单号实时查询 BYN 订单详情，只查询上游，不写入本地订单
数据来源	上游 api/v3/common/order_sync 接口

请求参数

参数名	类型	必填	说明
order_no	string	是	必应鸟订单号

兼容参数名：orderNo、biyingOrderSN。

请求示例

GET /taobao-flash-sale/order/byn-detail?order_no=8069420336327077348

成功响应

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "platform_id": 1,
    "buyer_id": 10001,
    "buyer_out_uid": "buyer-001",
    "buyer_phone": "13800000000",
    "pre_commission": 1.41,
    "commission": 0,
    "parent_order_id": "8069420336327077348",
    "sub_order_id": "8069420336327077348",
    "title": "商品名称",
    "image": "https://example.com/goods.jpg",
    "goods_id": "123456",
    "goods_count": 1,
    "goods_price": 22.98,
    "pay_price": 12.88,
    "shop_name": "门店名称",
    "status": 2,
    "create_time": "2026-05-14 12:00:00",
    "receive_time": "",
    "settle_time": "",
    "updated_at": "2026-05-14 12:10:00"
  }
}

响应字段

参数名	类型	说明
data.parent_order_id	string	必应鸟父订单号
data.sub_order_id	string	子订单号
data.title	string	商品名称
data.image	string	商品图片
data.goods_id	string	商品 ID
data.goods_count	int	商品数量
data.goods_price	float64	商品单价
data.pay_price	float64	实付金额
data.pre_commission	float64	预估佣金
data.commission	float64	结算佣金
data.shop_name	string	店铺/门店名称
data.status	int	BYN 订单状态
data.buyer_out_uid	string	买家外部 UID
data.buyer_phone	string	买家手机号
data.create_time	string	下单时间
data.receive_time	string	收货时间
data.settle_time	string	结算时间
data.updated_at	string	更新时间

失败响应示例

{
  "code": 7,
  "msg": "byn order not found"
}

查询 TBSG 退款记录

接口信息

项目	说明
接口路径	GET /taobao-flash-sale/order/refund-record
功能描述	根据 TBSG 上游订单号实时查询退款记录
数据来源	上游 api/v3/tbsg/refunds 接口
返回说明	系统只取上游响应中的 data 部分，并按统一响应格式返回

请求参数

参数名	类型	必填	说明
order_no	string	是	TBSG 上游订单号

兼容参数名：orderNo、upstreamOrderSN。

请求示例

GET /taobao-flash-sale/order/refund-record?order_no=8069420338096945529

成功响应：存在退款记录

{
  "code": 0,
  "msg": "操作成功",
  "data": [
    {
      "create_time": "2026-06-08 14:20:46",
      "no": "R322258636961824768",
      "order_no": "8069420337988015590",
      "pay_amount": 15.6,
      "refund_amount": 15.6,
      "status": 1
    }
  ]
}

成功响应：无退款记录

{
  "code": 0,
  "msg": "操作成功",
  "data": []
}

响应字段

参数名	类型	说明
data	array	退款记录列表
data[].no	string	退款单号
data[].order_no	string	TBSG 上游订单号
data[].pay_amount	float64	支付金额，单位元
data[].refund_amount	float64	退款金额，单位元
data[].create_time	string	退款记录创建时间
data[].status	int	退款状态：1-退款中；2-退款成功；3-退款失败

当无退款记录时，data 为 []。

失败响应示例

{
  "code": 7,
  "msg": "order_no不能为空"
}

订单状态码

状态码	说明
1	待付款
2	已付款
3	待接单
4	商家已接单
5	订单成功
6	主动取消
7	已关闭

支付状态码

状态码	说明
1	未付款
2	已付款
3	付款失败

业务说明

1. 创建订单时会先根据 outId 查询本地订单，若已存在则走幂等逻辑。
2. 新订单会调用上游接口获取商品详情，包括商品名、图片、店铺、收货信息和 pay_amount 等。
3. 系统会根据下单用户会员等级固化分佣比例到订单中。
4. 中台订单号格式为纯数字：{毫秒时间戳}{4位自增序号}。
5. 系统按采购端账户优先级依次尝试扣款。
6. 查询本地订单详情只读取本地订单表，不会触发上游同步。

注意事项

• outId 必须保证唯一，重复的 outId 会触发幂等逻辑。
• 扣款失败会导致订单创建失败，请确保采购端账户余额充足。
• H5 链接来源于后台基础设置，未配置时可能返回空字符串。

---

文档版本：v1.3 更新时间：2026-06-05