637 lines
12 KiB
Markdown
637 lines
12 KiB
Markdown
# 提现功能 API 文档
|
|
|
|
## 目录
|
|
- [收款账号管理 API](#收款账号管理-api)
|
|
- [提现申请 API (用户端)](#提现申请-api-用户端)
|
|
- [提现管理 API (管理员端)](#提现管理-api-管理员端)
|
|
|
|
---
|
|
|
|
## 收款账号管理 API
|
|
|
|
### 1. 查询收款账号列表
|
|
|
|
**请求**
|
|
```
|
|
GET /api/payment-accounts?page=1&page_size=20
|
|
Authorization: Bearer {user_token}
|
|
```
|
|
|
|
**响应**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "success",
|
|
"data": {
|
|
"items": [
|
|
{
|
|
"id": 1,
|
|
"user_id": 123,
|
|
"account_type": "alipay",
|
|
"account_name": "张三",
|
|
"account_no": "138****5678",
|
|
"bank_name": "",
|
|
"bank_branch": "",
|
|
"certificate_urls": ["https://..."],
|
|
"is_default": true,
|
|
"status": "active",
|
|
"created_at": "2026-06-06T10:00:00Z",
|
|
"updated_at": "2026-06-06T10:00:00Z"
|
|
}
|
|
],
|
|
"total": 1,
|
|
"page": 1,
|
|
"page_size": 20
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2. 查询收款账号详情
|
|
|
|
**请求**
|
|
```
|
|
GET /api/payment-accounts/:id
|
|
Authorization: Bearer {user_token}
|
|
```
|
|
|
|
**响应**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "success",
|
|
"data": {
|
|
"id": 1,
|
|
"user_id": 123,
|
|
"account_type": "alipay",
|
|
"account_name": "张三",
|
|
"account_no": "138****5678",
|
|
"bank_name": "",
|
|
"bank_branch": "",
|
|
"certificate_urls": ["https://..."],
|
|
"is_default": true,
|
|
"status": "active",
|
|
"created_at": "2026-06-06T10:00:00Z",
|
|
"updated_at": "2026-06-06T10:00:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. 添加收款账号
|
|
|
|
**请求**
|
|
```
|
|
POST /api/payment-accounts
|
|
Authorization: Bearer {user_token}
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"account_type": "alipay", // alipay | wechat | bank
|
|
"account_name": "张三", // 必须与实名认证姓名一致
|
|
"account_no": "13812345678", // 支付宝账号/微信号/银行卡号
|
|
"bank_name": "中国工商银行", // 银行卡必填
|
|
"bank_branch": "北京分行", // 银行卡可选
|
|
"certificate_urls": [ // 凭证截图（可选）
|
|
"https://..."
|
|
]
|
|
}
|
|
```
|
|
|
|
**响应**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "success",
|
|
"data": {
|
|
"id": 1,
|
|
"user_id": 123,
|
|
"account_type": "alipay",
|
|
"account_name": "张三",
|
|
"account_no": "138****5678",
|
|
"is_default": false,
|
|
"status": "active",
|
|
"created_at": "2026-06-06T10:00:00Z",
|
|
"updated_at": "2026-06-06T10:00:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
**错误响应**
|
|
```json
|
|
{
|
|
"code": 40001,
|
|
"message": "账户名必须与实名认证姓名一致"
|
|
}
|
|
```
|
|
|
|
```json
|
|
{
|
|
"code": 40002,
|
|
"message": "请先完成实名认证"
|
|
}
|
|
```
|
|
|
|
```json
|
|
{
|
|
"code": 40003,
|
|
"message": "收款账号数量已达上限（最多5个）"
|
|
}
|
|
```
|
|
|
|
### 4. 更新收款账号
|
|
|
|
**请求**
|
|
```
|
|
PUT /api/payment-accounts/:id
|
|
Authorization: Bearer {user_token}
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"bank_branch": "北京朝阳支行",
|
|
"certificate_urls": ["https://..."]
|
|
}
|
|
```
|
|
|
|
**响应**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "success",
|
|
"data": {
|
|
"id": 1,
|
|
"account_type": "bank",
|
|
"account_name": "张三",
|
|
"account_no": "6222****1234",
|
|
"bank_name": "中国工商银行",
|
|
"bank_branch": "北京朝阳支行",
|
|
"is_default": false,
|
|
"status": "active",
|
|
"created_at": "2026-06-06T10:00:00Z",
|
|
"updated_at": "2026-06-06T10:05:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 5. 删除收款账号
|
|
|
|
**请求**
|
|
```
|
|
DELETE /api/payment-accounts/:id
|
|
Authorization: Bearer {user_token}
|
|
```
|
|
|
|
**响应**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "success",
|
|
"data": {
|
|
"deleted": true
|
|
}
|
|
}
|
|
```
|
|
|
|
### 6. 设置默认收款账号
|
|
|
|
**请求**
|
|
```
|
|
POST /api/payment-accounts/:id/set-default
|
|
Authorization: Bearer {user_token}
|
|
```
|
|
|
|
**响应**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "success",
|
|
"data": {
|
|
"updated": true
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 提现申请 API (用户端)
|
|
|
|
### 1. 创建提现申请
|
|
|
|
**请求**
|
|
```
|
|
POST /api/withdrawals
|
|
Authorization: Bearer {user_token}
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"payment_account_id": 1,
|
|
"amount": 100.00
|
|
}
|
|
```
|
|
|
|
**响应**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "success",
|
|
"data": {
|
|
"id": 1,
|
|
"withdraw_no": "WD17362512001a2b3c4d",
|
|
"user_id": 123,
|
|
"amount": 100.00,
|
|
"fee": 0.00,
|
|
"actual_amount": 100.00,
|
|
"account_type": "alipay",
|
|
"account_name": "张三",
|
|
"account_no": "138****5678",
|
|
"bank_name": "",
|
|
"status": "pending",
|
|
"review_remark": "",
|
|
"created_at": "2026-06-06T10:00:00Z",
|
|
"updated_at": "2026-06-06T10:00:00Z",
|
|
"reviewed_at": null,
|
|
"paid_at": null
|
|
}
|
|
}
|
|
```
|
|
|
|
**错误响应**
|
|
```json
|
|
{
|
|
"code": 40001,
|
|
"message": "提现金额低于最小限额"
|
|
}
|
|
```
|
|
|
|
```json
|
|
{
|
|
"code": 40002,
|
|
"message": "提现金额超过最大限额"
|
|
}
|
|
```
|
|
|
|
```json
|
|
{
|
|
"code": 40003,
|
|
"message": "余额不足"
|
|
}
|
|
```
|
|
|
|
### 2. 查询提现列表
|
|
|
|
**请求**
|
|
```
|
|
GET /api/withdrawals?page=1&page_size=20
|
|
Authorization: Bearer {user_token}
|
|
```
|
|
|
|
**响应**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "success",
|
|
"data": {
|
|
"items": [
|
|
{
|
|
"id": 1,
|
|
"withdraw_no": "WD17362512001a2b3c4d",
|
|
"user_id": 123,
|
|
"amount": 100.00,
|
|
"fee": 0.00,
|
|
"actual_amount": 100.00,
|
|
"account_type": "alipay",
|
|
"account_name": "张三",
|
|
"account_no": "138****5678",
|
|
"bank_name": "",
|
|
"status": "completed",
|
|
"review_remark": "审核通过",
|
|
"created_at": "2026-06-06T10:00:00Z",
|
|
"updated_at": "2026-06-06T10:30:00Z",
|
|
"reviewed_at": "2026-06-06T10:10:00Z",
|
|
"paid_at": "2026-06-06T10:30:00Z"
|
|
}
|
|
],
|
|
"total": 1,
|
|
"page": 1,
|
|
"page_size": 20
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. 查询提现详情
|
|
|
|
**请求**
|
|
```
|
|
GET /api/withdrawals/:id
|
|
Authorization: Bearer {user_token}
|
|
```
|
|
|
|
**响应**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "success",
|
|
"data": {
|
|
"id": 1,
|
|
"withdraw_no": "WD17362512001a2b3c4d",
|
|
"user_id": 123,
|
|
"amount": 100.00,
|
|
"fee": 0.00,
|
|
"actual_amount": 100.00,
|
|
"account_type": "alipay",
|
|
"account_name": "张三",
|
|
"account_no": "138****5678",
|
|
"bank_name": "",
|
|
"status": "processing",
|
|
"review_remark": "审核通过",
|
|
"created_at": "2026-06-06T10:00:00Z",
|
|
"updated_at": "2026-06-06T10:10:00Z",
|
|
"reviewed_at": "2026-06-06T10:10:00Z",
|
|
"paid_at": null
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4. 取消提现申请
|
|
|
|
**请求**
|
|
```
|
|
POST /api/withdrawals/:id/cancel
|
|
Authorization: Bearer {user_token}
|
|
```
|
|
|
|
**响应**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "success",
|
|
"data": {
|
|
"cancelled": true
|
|
}
|
|
}
|
|
```
|
|
|
|
**错误响应**
|
|
```json
|
|
{
|
|
"code": 40001,
|
|
"message": "提现申请状态已锁定，无法操作"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 提现管理 API (管理员端)
|
|
|
|
### 1. 查询提现列表
|
|
|
|
**请求**
|
|
```
|
|
GET /api/admin/withdrawals?status=pending&page=1&page_size=20
|
|
Authorization: Bearer {admin_token}
|
|
X-Required-Permission: withdrawal:list
|
|
```
|
|
|
|
**查询参数**
|
|
- `status`: 状态筛选 (pending | processing | completed | rejected | cancelled)
|
|
- `user_id`: 用户ID筛选
|
|
- `page`: 页码
|
|
- `page_size`: 每页数量
|
|
|
|
**响应**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "success",
|
|
"data": {
|
|
"items": [
|
|
{
|
|
"id": 1,
|
|
"withdraw_no": "WD17362512001a2b3c4d",
|
|
"user_id": 123,
|
|
"user_nickname": "用户昵称",
|
|
"user_phone": "138****5678",
|
|
"amount": 100.00,
|
|
"fee": 0.00,
|
|
"actual_amount": 100.00,
|
|
"payment_account_id": 1,
|
|
"account_type": "alipay",
|
|
"account_name": "张三",
|
|
"account_no": "13812345678", // 管理员可见完整账号
|
|
"bank_name": "",
|
|
"bank_branch": "",
|
|
"status": "pending",
|
|
"reviewed_by": null,
|
|
"reviewed_by_name": "",
|
|
"reviewed_at": null,
|
|
"review_remark": "",
|
|
"paid_by": null,
|
|
"paid_by_name": "",
|
|
"paid_at": null,
|
|
"payment_proof_url": "",
|
|
"payment_remark": "",
|
|
"created_at": "2026-06-06T10:00:00Z",
|
|
"updated_at": "2026-06-06T10:00:00Z"
|
|
}
|
|
],
|
|
"total": 1,
|
|
"page": 1,
|
|
"page_size": 20
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2. 查询提现详情
|
|
|
|
**请求**
|
|
```
|
|
GET /api/admin/withdrawals/:id
|
|
Authorization: Bearer {admin_token}
|
|
X-Required-Permission: withdrawal:detail
|
|
```
|
|
|
|
**响应**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "success",
|
|
"data": {
|
|
"id": 1,
|
|
"withdraw_no": "WD17362512001a2b3c4d",
|
|
"user_id": 123,
|
|
"user_nickname": "用户昵称",
|
|
"user_phone": "13812345678",
|
|
"amount": 100.00,
|
|
"fee": 0.00,
|
|
"actual_amount": 100.00,
|
|
"payment_account_id": 1,
|
|
"account_type": "alipay",
|
|
"account_name": "张三",
|
|
"account_no": "13812345678",
|
|
"bank_name": "",
|
|
"bank_branch": "",
|
|
"status": "pending",
|
|
"reviewed_by": null,
|
|
"reviewed_by_name": "",
|
|
"reviewed_at": null,
|
|
"review_remark": "",
|
|
"paid_by": null,
|
|
"paid_by_name": "",
|
|
"paid_at": null,
|
|
"payment_proof_url": "",
|
|
"payment_remark": "",
|
|
"created_at": "2026-06-06T10:00:00Z",
|
|
"updated_at": "2026-06-06T10:00:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. 审核提现申请
|
|
|
|
**请求**
|
|
```
|
|
POST /api/admin/withdrawals/:id/review
|
|
Authorization: Bearer {admin_token}
|
|
X-Required-Permission: withdrawal:review
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"approved": true,
|
|
"remark": "审核通过"
|
|
}
|
|
```
|
|
|
|
**审核通过响应**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "success",
|
|
"data": {
|
|
"id": 1,
|
|
"withdraw_no": "WD17362512001a2b3c4d",
|
|
"status": "processing",
|
|
"reviewed_by": 10,
|
|
"reviewed_by_name": "财务管理员",
|
|
"reviewed_at": "2026-06-06T10:10:00Z",
|
|
"review_remark": "审核通过",
|
|
...
|
|
}
|
|
}
|
|
```
|
|
|
|
**审核拒绝请求**
|
|
```json
|
|
{
|
|
"approved": false,
|
|
"remark": "账号信息不符"
|
|
}
|
|
```
|
|
|
|
**审核拒绝响应**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "success",
|
|
"data": {
|
|
"id": 1,
|
|
"withdraw_no": "WD17362512001a2b3c4d",
|
|
"status": "rejected",
|
|
"reviewed_by": 10,
|
|
"reviewed_by_name": "财务管理员",
|
|
"reviewed_at": "2026-06-06T10:10:00Z",
|
|
"review_remark": "账号信息不符",
|
|
...
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4. 确认打款
|
|
|
|
**请求**
|
|
```
|
|
POST /api/admin/withdrawals/:id/confirm-payment
|
|
Authorization: Bearer {admin_token}
|
|
X-Required-Permission: withdrawal:pay
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"payment_proof_url": "https://storage.example.com/proofs/proof_123.jpg",
|
|
"remark": "已通过支付宝转账"
|
|
}
|
|
```
|
|
|
|
**响应**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "success",
|
|
"data": {
|
|
"id": 1,
|
|
"withdraw_no": "WD17362512001a2b3c4d",
|
|
"status": "completed",
|
|
"paid_by": 10,
|
|
"paid_by_name": "财务管理员",
|
|
"paid_at": "2026-06-06T10:30:00Z",
|
|
"payment_proof_url": "https://storage.example.com/proofs/proof_123.jpg",
|
|
"payment_remark": "已通过支付宝转账",
|
|
...
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 状态说明
|
|
|
|
### 提现状态 (status)
|
|
|
|
| 状态 | 说明 | 允许操作 |
|
|
|------|------|---------|
|
|
| `pending` | 待审核 | 用户可取消、管理员可审核 |
|
|
| `processing` | 处理中 | 管理员可确认打款 |
|
|
| `completed` | 已完成 | 无 |
|
|
| `rejected` | 已拒绝 | 无 |
|
|
| `cancelled` | 已取消 | 无 |
|
|
|
|
### 账号类型 (account_type)
|
|
|
|
| 类型 | 说明 |
|
|
|------|------|
|
|
| `alipay` | 支付宝 |
|
|
| `wechat` | 微信 |
|
|
| `bank` | 银行卡 |
|
|
|
|
---
|
|
|
|
## 错误码说明
|
|
|
|
| 错误码 | 说明 |
|
|
|--------|------|
|
|
| 40001 | 请求参数错误 |
|
|
| 40002 | 实名认证未通过 |
|
|
| 40003 | 账号数量限制 |
|
|
| 40004 | 提现金额错误 |
|
|
| 40005 | 余额不足 |
|
|
| 40006 | 状态锁定 |
|
|
| 40401 | 未找到资源 |
|
|
| 40301 | 未授权 |
|
|
| 50001 | 服务器错误 |
|
|
|
|
---
|
|
|
|
## 接口权限说明
|
|
|
|
### 用户端接口
|
|
所有用户端接口需要携带用户 Token (`Authorization: Bearer {user_token}`)
|
|
|
|
### 管理员端接口
|
|
所有管理员端接口需要：
|
|
1. 携带管理员 Token (`Authorization: Bearer {admin_token}`)
|
|
2. 拥有对应的权限
|
|
|
|
#### 提现管理权限列表
|
|
- `withdrawal:list` - 查看提现申请列表
|
|
- `withdrawal:detail` - 查看提现详情
|
|
- `withdrawal:review` - 审核提现申请
|
|
- `withdrawal:pay` - 确认打款
|
|
|
|
**财务角色 (finance)** 默认拥有以上所有权限。
|