# 提现申请接口文档 ## 基础信息 - **基础路径**: `/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#获取钱包详细信息) - [设置支付密码](#设置支付密码)