@ (#111)

docs/api目录文档分类和补全 --------- Co-authored-by: guke <guke@autohome.com.cn> Reviewed-on: #111
2026-07-03 15:00:37 +08:00
parent ee132aa93b
commit a563c1ca4b
102 changed files with 2418 additions and 217 deletions
@@ -0,0 +1,108 @@
+# 免确认收款授权（transfer-auth 族）
+
+> 所属:Wallet 组（前缀 `/api/v1/wallet`） | 鉴权:全部 Bearer | [← 返回 API 索引](../README.md)
+>
+> 集成实现:见 [integrations/wxpay](../../integrations/wxpay.md)（微信 V3 免确认收款授权）。
+
+开启一次后，后续提现走免确认转账直接到账，不再跳微信确认。绑定 openid 是前提。
+
+---
+
+## POST /transfer-auth — 开启免确认到账
+
+申请免确认授权，返回拉起微信授权页的 `package_info`。
+
+### 入参
+
+无（`user_id` 从 JWT 取）。
+
+### 出参
+
+响应 `200`:`TransferAuthResultOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `already_active` | bool | 是否已是开启状态（无需再授权） |
+| `package_info` | string \| null | 拉起微信授权页的 package；已开启时为空 |
+| `mch_id` | string \| null | 商户号 |
+| `app_id` | string \| null | 微信 AppID |
+
+Mock 出参（首次申请）:
+```json
+{
+  "already_active": false,
+  "package_info": "affirmTransferAuth|{\"mchId\":\"1234567890\",\"appId\":\"wxabc123\",\"package\":\"affirm_biz_123\"}",
+  "mch_id": "1234567890",
+  "app_id": "wxabc123"
+}
+```
+
+Mock 出参（已开启，无需重复授权）:
+```json
+{
+  "already_active": true,
+  "package_info": null,
+  "mch_id": "1234567890",
+  "app_id": "wxabc123"
+}
+```
+
+### 错误码
+- `400` 未绑定微信
+- `502` 微信授权接口调用失败
+- `503` 微信支付授权未配置
+
+---
+
+## GET /transfer-auth/status — 查免确认授权状态
+
+从微信授权页返回后轮询。
+
+### 入参
+
+无（`user_id` 从 JWT 取）。
+
+### 出参
+
+响应 `200`:`TransferAuthStatusOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `state` | string | `none`（未开启）/ `pending`（待确认）/ `active`（已开启）/ `closed`（已关闭） |
+| `enabled` | bool | 是否已开启免确认到账 |
+
+Mock 出参:
+```json
+{
+  "state": "active",
+  "enabled": true
+}
+```
+
+---
+
+## POST /transfer-auth/close — 关闭免确认到账
+
+解除授权，恢复每次提现跳微信确认。
+
+### 入参
+
+无（`user_id` 从 JWT 取）。
+
+### 出参
+
+响应 `200`:`TransferAuthStatusOut`（同上）
+
+Mock 出参:
+```json
+{
+  "state": "closed",
+  "enabled": false
+}
+```
+
+---
+
+## 错误码（通用）
+- `401` 未鉴权 / token 失效
+- `503` 微信支付授权未配置