yml/live-hub-py
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

优化斗鱼充值

Browse Source
This commit is contained in:
yml2213
2026-08-13 21:43:27 +08:00
parent 902e669614
commit 0bf69c1240
19 changed files with 450 additions and 266 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/鱼翅充值api/接入分析.md
+8 -7
View File
@@ -16,22 +16,22 @@
- 商户账户查询 `userInfoV2`；
- 环境变量配置和请求、响应格式校验。
嵌套的 `recharge_arg`、`ext_arg` 在签名中使用稳定的紧凑 JSON 字符串。该序列化方式需要供应商联调确认；若其服务端使用其他规则，应在 `FishFinRechargeClient._sign_value` 中按确认规则调整。
新版订单文档规定：`recharge_arg`、`ext_arg` 都是 JSON 字符串，不是 JSON 数组或对象。客户端以紧凑 JSON 文本发送并将该文本原样参与签名。
## 已确认商品
供应商商品列表中，鱼翅商品为“鱼翅-1元”：`goodsNo=111570`、单份供货成本 `0.993`。项目将它作为 API 渠道的默认商品参数。用户在工作台填写的充值面值同时传为 `buy_num` 与 `customer_price`，例如填写 `10` 会为每个勾选账号创建 `buy_num=10`、`customer_price=10` 的订单；整数金额以 JSON 整数发送，例如 `1` 而不是 `1.0`。供货成本不参与下单金额。
供应商商品列表中，鱼翅商品为“鱼翅-1元”：`goodsNo=111570`、单份供货成本 `0.993`。项目将它作为 API 渠道的默认商品参数。用户在工作台填写的充值面值同时传为 `buy_num` 与 `pay_amount`，例如填写 `10` 会为每个勾选账号创建 `buy_num=10`、`pay_amount=10`、`order_type=0` 的直充订单；整数金额以 JSON 整数发送，例如 `1` 而不是 `1.0`。供货成本不参与下单金额。
创建订单只会发送文档示例中的必填字段和 UID 对应的 `recharge_arg`；空 `notify_url` 与未约定的 `ext_arg` 不会发送或参与签名。`ext_arg` 仅在供应商明确约定 `skuid`、`skuname` 等字段后才可启用。
创建订单使用新版必填字段 `product_id`、`buy_num`、`pay_amount`、`out_order_id`、`order_type`，其中 `out_order_id` 是稳定的 `DYGF{任务ID}`。UID 通过 JSON 字符串 `recharge_arg` 传递。空 `notify_url` 与未约定的 `ext_arg` 不会发送或参与签名。`ext_arg` 仅在供应商明确约定 `skuid`、`skuname` 等字段后才可启用。
查询订单使用 `GET queryOrderV2?out_order_id=...`。服务端会轮询该订单号；如果设置 `FISH_FIN_RECHARGE_NOTIFY_URL`，也会发送回调地址至供应商。回调地址为 `/api/douyu/supplier-recharge/callback`，仅接受通过 `POST` 签名验证的回调并按 `out_order_id` 幂等更新任务。
## 接入前待供应商确认
1. API 网关基地址（文档只给出相对路径）。
2. `AppKey` 的实际传输位置与字段名。当前协议示例只签名并发送 `app_id`，客户端不会猜测发送 `AppKey`。
3. `queryOrderV2` 所需的订单标识字段名（商户单号、供应商单号或两者）。
4. 创建订单完整字段和 `recharge_arg` 模板，尤其是鱼翅商品 `product_id`、价格、数量含义，以及是否必须传 `ext_arg`。
5. `recharge_arg` / `ext_arg` 的嵌套签名序列化规则，以及请求与响应是否必须验签。
6. 回调地址、回调重试与回调验签规则；生产接入应持久化商户订单号并实现幂等处理。
3. 鱼翅商品 `product_id`、`pay_amount`、`buy_num` 的最终业务约束，以及是否必须传 `ext_arg`。
4. 回调地址的公网可达性与回调重试策略。
## 运行时配置
@@ -42,6 +42,7 @@ FISH_FIN_RECHARGE_BASE_URL=https://supplier.example
FISH_FIN_RECHARGE_APP_ID=
FISH_FIN_RECHARGE_APP_KEY=
FISH_FIN_RECHARGE_APP_SECRET=
FISH_FIN_RECHARGE_NOTIFY_URL=https://your-domain.example/api/douyu/supplier-recharge/callback
FISH_FIN_RECHARGE_TIMEOUT=20
```
docs/鱼翅充值api/订单接口/1.创建订单_必要.md
+77
View File
@@ -0,0 +1,77 @@
# 创建订单【必要】
# 接口说明
- 下单接口
- POST 请求
- application/json
- 接口地址 adapter-apiaccess/open/api/createOrderV2
# 请求参数
请求公共参数 —— 参考接口规范的请求公共参数 是 携带公共参数
product_id string 66668888 是 商品编码
buy_num int 1 是 购买数量
pay_amount decimal 88.88 是 用户支付金额
out_order_id string OUT202503010010208888 是 来源/外部订单号
order_type int 是 订单类型：0-直充 1-话费 2-流量 3-卡密
recharge_arg string 用户填写信息的JSON串 否 【直充必传】充值模板及填写值
buyer_ip string 114.115.116.117 否 买家IP，若要启用风控则必传
buyer_id string（64） 15486548471 否 买家唯一标识，若要启用风控则必传
notify_url string 否 回调地址，订单完成会通过该地址异步通知
ext_arg string 订单补充信息JSON串 否 补充字段，经过约定后，补充信息字段都在这里传递
notify_url：
- 一些直充类的订单时间比较久，但不能持续占用连接
- 不传就不回调，订单的状态在查询时处理
recharge_arg：（此处数据为用户填写和对应模板）
[
{
"templateName": "模板名，一般是中文，如手机号，只是标识用，调用方可自行决定",
"templateVal": "用户填写的充值账号，比如：19876543210",
}
]
这里是用户填写的信息，比如：充值手机号：19876543210
templateName：充值手机号
templateVal：19876543210
ext_arg：（此处数据均为双方约定）
{
"skuid": 243241231238888888,
"skuname: "电商平台的商品名称"
}
# 响应信息
## code数据对业务流程的影响
参数 类型 示例值 必要 描述
响应公共参数 —— 参考接口规范的响应公共参数 是 携带公共参数
请求异常情况下，下面的参数都是非必要的下标描述的是请求接收正常情况下的参数说明
out_order_id string OUT202503010010208888 是 来源/外部订单号
order_id string 202503010010208888 是 供货方的订单号
order_type int 4 是 订单类型：0-直充；1-话费；2-流量；3-卡密
order_status int 0 是 0，待处理；1，处理中；2，成功；3，失败 4-异常
fail_reason string 否 失败原因，失败必传
create_time string 2025/3/1 0:10 是 订单创建时间（供货方）
code数据对业务流程的影响
- 如果返回 200 的状态码，则下单成功，后续通过【查询订单】或者【订单异步通知】来获取订单结果状态
- 如果返回非 200 的状态码，订单失败，流程结束
order_status数据对业务流程的影响
- 0，待处理；1，处理中；2，成功；3，失败； 4，异常
- 当为 0 和 1 时，订单没有结束，
- 需要调用方自轮询查询订单；
- 或本平台订单结束后，异步通知订单结果
docs/鱼翅充值api/订单接口/2.查询订单_必要.md
+44
View File
@@ -0,0 +1,44 @@
查询订单【必要】
接口说明
- 订单查询接口
- GET 请求
- application/x-www-form-urlencoded
- 接口地址 adapter-apiaccess/open/api/queryOrderV2
请求参数
参数 类型 示例值 必要 描述
请求公共参数 —— 参考接口规范的请求公共参数 是 携带公共参数
out_order_id string OUT202503010010208888 是 来源/外部订单号
响应信息
参数 类型 示例值 必要 描述
响应公共参数 —— 请参考接口规范的响应公共参数 是 携带公共参数
请求异常情况下，下面的参数都是非必要的下标描述的是请求接收正常情况下的参数说明
out_order_id string OUT202503010010208888 是 来源/外部订单号
order_id string 202503010010208888 是 供货方的订单号
order_type int 4 是 订单类型：0-直充；1-话费；2-流量；3-卡密
order_status int 0 是 0，待处理；1，处理中；2，成功；3，失败 4-异常
fail_reason string 否 失败原因，失败必传
create_time string 2025/3/1 0:10 是 订单创建时间（原厂）
finish_time string 2025/3/1 0:10 否 订单完成时间（原厂）
cards string 加密数据 否 卡密订单时才可能有数据，使用ASE加密，加密方式参考附录的数据加密部分
code数据对业务流程的影响
- 查询订单时如果返回非 200 的状态码，订单失败，流程结束
order_status数据对业务流程的影响
- 当为 0 和 1 时，订单没有结束，
- 需要调用方自轮询查询订单；
- 或本平台订单结束后，异步通知订单结果
- 当为 2 和 3 、4 时，订单结束
cards解密后的结构如下
[
{
card_no: 'CN88889999',（无卡号就填""空串）
card_pwd: 'ABCD-DEFG-GHIJ-JKLM',
expired_time: '2026-09-27 08:36:58',（过期时间，可不传）
price: '8.8',（卡密单价，可不传）
card_type: '0'（不传时，默认为0。0.普通卡密 1.短链）
}
]
docs/鱼翅充值api/订单接口/3.订单异步通知_推荐.md
+47
View File
@@ -0,0 +1,47 @@
# 订单异步通知【推荐】
# 接口说明
- 下单后，如订单流程、时间较长，需要第一时间返回下单成功状态，之后的流程中再去通知外部平台订单的状态
- POST 请求
- 接口地址一般为 ***http://IP******\[:PORT\]/网关/业务/callBackV2***
- 具体地址，请双方开发协定，或联系运营获取
# 请求参数
参数 类型 示例值 必要 描述
请求公共参数 —— 参考接口规范的请求公共参数 是 携带公共参数
out_order_id string OUT202503010010208888 是 来源/外部订单号
order_id string 202503010010208888 是 原厂的订单号
order_type int 4 是 订单类型：0-直充；1-话费；2-流量；3-卡密
order_status int 0 是 "0，待处理；1，处理中
2，成功；3，失败； 4-异常
这里应该只有 2 和 3、4"
fail_reason string 否 失败原因，失败必传
create_time string 2025/3/1 0:10 是 订单创建时间（原厂）
finish_time string 2025/3/1 0:10 是 订单完成时间（原厂）
cards string 加密数据 否 卡密订单时才可能有数据，使用ASE加密，加密方式参考附录的数据加密部分
## cards解密后的结构如下：
```JSON
[
{
card_no: 'CN88889999',（无卡号就填""空串）
card_pwd: 'ABCD-DEFG-GHIJ-JKLM',
expired_time: '2026-09-27 08:36:58',（过期时间，可不传）
price: '8.8',（卡密单价，可不传）
card_type: '0'（不传时，默认为0。0.普通卡密 1.短链）
}
]
```
# 响应信息
参数 类型 示例值 必要 描述
公共参数 —— 请参考接口规范的公共响应信息 是 携带公共参数
docs/鱼翅充值api/订单接口/创建订单【必要】.md
-76
View File
@@ -1,76 +0,0 @@
# 创建订单【必要】
# 接口说明
- 下单接口
- POST 请求
- application/json
- 接口地址 ***adapter\-apiaccess/open/api/createOrderV2***
# 请求参数
**notify\_url**：
- 一些直充类的订单时间比较久，但不能持续占用连接
- 不传就不回调，订单的状态在查询时处理
**recharge\_arg**：（此处数据为用户填写和对应模板）
```Plain Text
[
{
"templateName": "模板名，一般是中文，如手机号，只是标识用，调用方可自行决定",
"templateVal": "用户填写的充值账号，比如：19876543210",
}
]
```
这里是用户填写的信息，比如：充值手机号：19876543210
templateName：充值手机号
templateVal：19876543210
**ext\_arg**：（此处数据均为双方约定）
```Plain Text
{
"skuid": 243241231238888888,
"skuname: "电商平台的商品名称"
}
```
# 响应信息
## code数据对业务流程的影响
- 如果返回 200 的状态码，则下单成功，后续通过【查询订单】或者【订单异步通知】来获取订单结果状态
- 如果返回非 200 的状态码，订单失败，流程结束
## order\_status数据对业务流程的影响
- 0，待处理；1，处理中；2，成功；3，失败； 4，异常
- 当为 0 和 1 时，订单没有结束，
- 需要调用方自轮询查询订单；
- 或本平台订单结束后，异步通知订单结果
docs/鱼翅充值api/订单接口/查询订单【必要】.md
-54
View File
@@ -1,54 +0,0 @@
# 查询订单【必要】
# 接口说明
- 订单查询接口
- GET 请求
- application/x\-www\-form\-urlencoded
- 接口地址 ***adapter\-apiaccess/open/api/queryOrderV2***
# 请求参数
# 响应信息
## code数据对业务流程的影响
- 查询订单时如果返回非 200 的状态码，订单失败，流程结束
## order\_status数据对业务流程的影响
- 当为 0 和 1 时，订单没有结束，
- 需要调用方自轮询查询订单；
- 或本平台订单结束后，异步通知订单结果
- 当为 2 和 3 、4 时，订单结束
## cards解密后的结构如下
```JSON
[
{
card_no: 'CN88889999',（无卡号就填""空串）
card_pwd: 'ABCD-DEFG-GHIJ-JKLM',
expired_time: '2026-09-27 08:36:58',（过期时间，可不传）
price: '8.8',（卡密单价，可不传）
card_type: '0'（不传时，默认为0。0.普通卡密 1.短链）
}
]
```
docs/鱼翅充值api/订单接口/订单异步通知【推荐】.md
-34
View File
@@ -1,34 +0,0 @@
# 订单异步通知【推荐】
# 接口说明
- 下单后，如订单流程、时间较长，需要第一时间返回下单成功状态，之后的流程中再去通知外部平台订单的状态
- POST 请求
- 接口地址一般为 ***http://IP******\[:PORT\]/网关/业务/callBackV2***
- 具体地址，请双方开发协定，或联系运营获取
# 请求参数
## cards解密后的结构如下：
```JSON
[
{
card_no: 'CN88889999',（无卡号就填""空串）
card_pwd: 'ABCD-DEFG-GHIJ-JKLM',
expired_time: '2026-09-27 08:36:58',（过期时间，可不传）
price: '8.8',（卡密单价，可不传）
card_type: '0'（不传时，默认为0。0.普通卡密 1.短链）
}
]
```
# 响应信息
docs/鱼翅充值api/订单接口/账户信息查询.md
-20
View File
@@ -1,20 +0,0 @@
# 账户信息查询
# 接口说明
- 下单接口
- GET 请求
- 接口地址 ***adapter\-apiaccess/open/api/userInfoV2***
# 请求参数
# 响应信息
docs/鱼翅充值api/账户接口/账户信息查询.md
+8 -3
View File
@@ -11,10 +11,15 @@
# 请求参数
参数 类型 示例值 必要 描述
请求公共参数 —— 参考接口规范的请求公共参数 是 携带公共参数
# 响应信息
参数 类型 示例值 必要 描述
响应公共参数 —— 请参考接口规范的响应公共参数 是 携带公共参数
请求异常情况下，下面的参数都是非必要的下标描述的是请求接收正常情况下的参数说明
name string 发财集团 是 商户名称
balance decimal 9999999999999999.99 是 商户余额（单位：元）
status int 1 是 商户状态，0，禁用；1，启用