440 lines
11 KiB
Markdown
440 lines
11 KiB
Markdown
# 提现申请接口文档
|
||
|
||
## 基础信息
|
||
|
||
- **基础路径**: `/wallet`
|
||
- **认证方式**: 所有接口都需要在请求头中携带 `token`（通过 `mw.CheckToken` 中间件验证）
|
||
- **请求方法**: 所有接口均为 `POST`
|
||
- **Content-Type**: `application/json`
|
||
|
||
## 响应格式说明
|
||
|
||
所有接口的响应格式统一为：
|
||
|
||
```json
|
||
{
|
||
"errCode": 0, // 错误码，0 表示成功
|
||
"errMsg": "", // 错误消息
|
||
"errDlt": "", // 错误详情
|
||
"data": {} // 响应数据
|
||
}
|
||
```
|
||
|
||
## 公共数据结构
|
||
|
||
### RequestPagination（分页信息）
|
||
|
||
```json
|
||
{
|
||
"pageNumber": 1, // 页码（从1开始）
|
||
"showNumber": 10 // 每页显示数量
|
||
}
|
||
```
|
||
|
||
### WithdrawApplicationInfo（提现申请信息）
|
||
|
||
```json
|
||
{
|
||
"id": "string", // 申请ID
|
||
"userID": "string", // 用户ID
|
||
"amount": 10000, // 提现金额（单位：分）
|
||
"withdrawAccount": "string", // 提现账号
|
||
"withdrawAccountType": 1, // 提现账号类型：1-支付宝，2-微信，3-银行卡
|
||
"status": 1, // 申请状态：1-待审核，2-已通过，3-已拒绝，4-处理中，5-已完成
|
||
"auditorID": "string", // 审核人ID（管理员ID）
|
||
"auditTime": 1234567890123, // 审核时间（毫秒时间戳，未审核时为0）
|
||
"auditRemark": "string", // 审核备注
|
||
"ip": "string", // 申请IP
|
||
"deviceID": "string", // 设备ID
|
||
"platform": "string", // 平台（iOS、Android、Web等）
|
||
"deviceModel": "string", // 设备型号
|
||
"deviceBrand": "string", // 设备品牌
|
||
"osVersion": "string", // 操作系统版本
|
||
"appVersion": "string", // 应用版本
|
||
"remark": "string", // 申请备注
|
||
"createTime": 1234567890123, // 创建时间（毫秒时间戳）
|
||
"updateTime": 1234567890123 // 更新时间（毫秒时间戳）
|
||
}
|
||
```
|
||
|
||
### 提现申请状态说明
|
||
|
||
| 状态值 | 状态名称 | 说明 |
|
||
|--------|---------|------|
|
||
| 1 | 待审核 | 用户已提交申请，等待管理员审核 |
|
||
| 2 | 已通过 | 管理员审核通过 |
|
||
| 3 | 已拒绝 | 管理员审核拒绝 |
|
||
| 4 | 处理中 | 审核通过后，正在处理提现 |
|
||
| 5 | 已完成 | 提现已完成 |
|
||
|
||
---
|
||
|
||
## 接口列表
|
||
|
||
### 1. 设置支付密码
|
||
|
||
**接口地址**: `/wallet/payment_password/set`
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"newPassword": "string", // 新支付密码（必填）
|
||
"oldPassword": "string" // 旧支付密码（修改时必填，首次设置时不需要）
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**业务逻辑**:
|
||
|
||
1. **首次设置支付密码**（钱包不存在或未设置支付密码）:
|
||
- 不需要提供 `oldPassword`
|
||
- 如果提供了 `oldPassword`，会返回错误
|
||
- 如果钱包不存在，会自动创建钱包并设置支付密码
|
||
|
||
2. **修改支付密码**（已设置支付密码）:
|
||
- 必须提供 `oldPassword`
|
||
- 验证旧密码是否正确
|
||
- 验证新密码不能与旧密码相同
|
||
- 更新支付密码
|
||
|
||
**错误码说明**:
|
||
|
||
| 错误码 | 错误信息 | 说明 |
|
||
|--------|---------|------|
|
||
| 400 | 新支付密码不能为空 | newPassword 为空 |
|
||
| 400 | 修改支付密码需要提供旧密码 | 已设置密码但未提供 oldPassword |
|
||
| 400 | 首次设置支付密码不需要提供旧密码 | 未设置密码但提供了 oldPassword |
|
||
| 400 | 旧支付密码错误 | oldPassword 验证失败 |
|
||
| 400 | 新密码不能与旧密码相同 | newPassword == oldPassword |
|
||
|
||
**请求示例**:
|
||
|
||
首次设置：
|
||
```json
|
||
{
|
||
"newPassword": "123456"
|
||
}
|
||
```
|
||
|
||
修改密码：
|
||
```json
|
||
{
|
||
"newPassword": "654321",
|
||
"oldPassword": "123456"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 设置提现账号
|
||
|
||
**接口地址**: `/wallet/withdraw_account/set`
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"account": "string", // 提现账号（必填）
|
||
"accountType": 1 // 账号类型（必填）：1-支付宝，2-微信，3-银行卡
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**账号类型说明**:
|
||
|
||
| 类型值 | 类型名称 | 说明 |
|
||
|--------|---------|------|
|
||
| 1 | 支付宝 | 支付宝账号 |
|
||
| 2 | 微信 | 微信账号 |
|
||
| 3 | 银行卡 | 银行卡号 |
|
||
|
||
**错误码说明**:
|
||
|
||
| 错误码 | 错误信息 | 说明 |
|
||
|--------|---------|------|
|
||
| 400 | 提现账号不能为空 | account 为空 |
|
||
| 400 | 账号类型无效，必须是1-支付宝，2-微信，3-银行卡 | accountType 不在有效范围内 |
|
||
|
||
**业务逻辑**:
|
||
|
||
1. 验证必填字段（账号、账号类型）
|
||
2. 验证账号类型是否有效（1-3）
|
||
3. 更新钱包中的提现账号和账号类型
|
||
|
||
---
|
||
|
||
### 3. 申请提现
|
||
|
||
**接口地址**: `/wallet/withdraw/apply`
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"amount": 10000, // 提现金额（单位：分，必填，必须大于0）
|
||
"paymentPassword": "string", // 支付密码（必填）
|
||
"ip": "string", // 申请IP（可选）
|
||
"deviceID": "string", // 设备ID（可选）
|
||
"platform": "string", // 平台（可选，如：iOS、Android、Web）
|
||
"deviceModel": "string", // 设备型号（可选，如：iPhone 14 Pro）
|
||
"deviceBrand": "string", // 设备品牌（可选，如：Apple）
|
||
"osVersion": "string", // 操作系统版本（可选，如：iOS 17.0）
|
||
"appVersion": "string" // 应用版本（可选）
|
||
}
|
||
```
|
||
|
||
**注意**:
|
||
- 提现账号从用户钱包中自动获取，不需要在请求中提供
|
||
- 如果钱包中未设置提现账号，会返回错误提示
|
||
- 备注（remark）由后台管理员在审核时填写，用户申请时不需要提供
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"applicationID": "uuid-string" // 申请ID
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码说明**:
|
||
|
||
| 错误码 | 错误信息 | 说明 |
|
||
|--------|---------|------|
|
||
| 400 | 提现金额必须大于0 | amount <= 0 |
|
||
| 400 | 支付密码不能为空 | paymentPassword 为空 |
|
||
| 400 | 钱包不存在，无法申请提现 | 用户钱包不存在 |
|
||
| 400 | 请先设置支付密码 | 用户未设置支付密码 |
|
||
| 400 | 支付密码错误 | 支付密码验证失败 |
|
||
| 400 | 余额不足，无法申请提现 | 钱包余额 < 提现金额 |
|
||
| 400 | 请先在钱包中设置提现账号 | 钱包中未设置提现账号 |
|
||
|
||
**业务逻辑**:
|
||
|
||
1. 验证必填字段（金额、支付密码）
|
||
2. 获取用户钱包信息
|
||
3. 验证支付密码
|
||
4. 检查余额是否足够
|
||
5. 检查钱包中是否设置了提现账号（从钱包中获取）
|
||
6. 创建提现申请记录（状态：待审核，提现账号从钱包中获取）
|
||
|
||
---
|
||
|
||
### 4. 获取提现申请列表
|
||
|
||
**接口地址**: `/wallet/withdraw/list`
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"pagination": {
|
||
"pageNumber": 1, // 页码（从1开始）
|
||
"showNumber": 10 // 每页显示数量
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"total": 100, // 总数
|
||
"applications": [ // 申请列表
|
||
{
|
||
"id": "string",
|
||
"userID": "string",
|
||
"amount": 10000,
|
||
"withdrawAccount": "string",
|
||
"status": 1,
|
||
"auditorID": "string",
|
||
"auditTime": 1234567890123,
|
||
"auditRemark": "string",
|
||
"ip": "string",
|
||
"deviceID": "string",
|
||
"platform": "string",
|
||
"deviceModel": "string",
|
||
"deviceBrand": "string",
|
||
"osVersion": "string",
|
||
"appVersion": "string",
|
||
"remark": "string",
|
||
"createTime": 1234567890123,
|
||
"updateTime": 1234567890123
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**业务逻辑**:
|
||
|
||
1. 从 token 中获取当前用户ID
|
||
2. 根据用户ID查询提现申请列表
|
||
3. 按创建时间倒序排列
|
||
4. 支持分页查询
|
||
|
||
---
|
||
|
||
## 请求示例
|
||
|
||
### 申请提现
|
||
|
||
```bash
|
||
curl -X POST http://your-domain/wallet/withdraw/apply \
|
||
-H "Content-Type: application/json" \
|
||
-H "token: your-token" \
|
||
-d '{
|
||
"amount": 10000,
|
||
"paymentPassword": "123456",
|
||
"ip": "192.168.1.1",
|
||
"deviceID": "device-uuid",
|
||
"platform": "iOS",
|
||
"deviceModel": "iPhone 14 Pro",
|
||
"deviceBrand": "Apple",
|
||
"osVersion": "iOS 17.0",
|
||
"appVersion": "1.0.0"
|
||
}'
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"applicationID": "550e8400-e29b-41d4-a716-446655440000"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 获取提现申请列表
|
||
|
||
```bash
|
||
curl -X POST http://your-domain/wallet/withdraw/list \
|
||
-H "Content-Type: application/json" \
|
||
-H "token: your-token" \
|
||
-d '{
|
||
"pagination": {
|
||
"pageNumber": 1,
|
||
"showNumber": 10
|
||
}
|
||
}'
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"total": 5,
|
||
"applications": [
|
||
{
|
||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||
"userID": "user123",
|
||
"amount": 10000,
|
||
"withdrawAccount": "6222021234567890123",
|
||
"status": 1,
|
||
"auditorID": "",
|
||
"auditTime": 0,
|
||
"auditRemark": "",
|
||
"ip": "192.168.1.1",
|
||
"deviceID": "device-uuid",
|
||
"platform": "iOS",
|
||
"deviceModel": "iPhone 14 Pro",
|
||
"deviceBrand": "Apple",
|
||
"osVersion": "iOS 17.0",
|
||
"appVersion": "1.0.0",
|
||
"remark": "提现备注",
|
||
"createTime": 1704067200000,
|
||
"updateTime": 1704067200000
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## RPC 接口说明
|
||
|
||
### gRPC 服务
|
||
|
||
**服务名**: `openim.chat.Chat`
|
||
|
||
### 1. CreateWithdrawApplication
|
||
|
||
**RPC 方法**: `CreateWithdrawApplication`
|
||
|
||
**请求消息**: `CreateWithdrawApplicationReq`
|
||
|
||
**响应消息**: `CreateWithdrawApplicationResp`
|
||
|
||
### 2. SetPaymentPassword
|
||
|
||
**RPC 方法**: `SetPaymentPassword`
|
||
|
||
**请求消息**: `SetPaymentPasswordReq`
|
||
|
||
**响应消息**: `SetPaymentPasswordResp`
|
||
|
||
### 3. GetWithdrawApplications
|
||
|
||
**RPC 方法**: `GetWithdrawApplications`
|
||
|
||
**请求消息**: `GetWithdrawApplicationsReq`
|
||
|
||
**响应消息**: `GetWithdrawApplicationsResp`
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **支付密码验证**: 申请提现时必须提供正确的支付密码
|
||
2. **余额检查**: 系统会检查钱包余额是否足够，余额不足时无法申请
|
||
3. **提现账号**: 如果钱包中已设置提现账号，可以不传 `withdrawAccount`，系统会使用钱包中的账号
|
||
4. **申请状态**: 新创建的申请状态为"待审核"（status=1），需要管理员审核
|
||
5. **分页查询**: 列表接口支持分页，默认按创建时间倒序排列
|
||
6. **权限控制**: 用户只能查看自己的提现申请列表
|
||
|
||
---
|
||
|
||
## 相关接口
|
||
|
||
- [钱包余额查询](./API_WALLET.md#获取钱包余额)
|
||
- [钱包信息查询](./API_WALLET.md#获取钱包详细信息)
|
||
- [设置支付密码](#设置支付密码)
|