277 lines
6.3 KiB
Markdown
277 lines
6.3 KiB
Markdown
# 发票API接口文档
|
||
|
||
## 概述
|
||
|
||
本文档描述了发票管理相关的API接口，包括用户申请开票和管理员处理开票申请的功能。
|
||
|
||
## 基础信息
|
||
|
||
- **Base URL**: `http://localhost:8080`
|
||
- **认证方式**: Bearer Token (JWT)
|
||
- **Content-Type**: `application/json`
|
||
|
||
## 用户接口
|
||
|
||
### 1. 申请开票
|
||
|
||
**接口地址**: `POST /api/v1/invoices/apply`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"invoice_type": "general", // 发票类型: general(普票) | special(专票)
|
||
"amount": "1000.00", // 开票金额
|
||
"invoice_info": {
|
||
"company_name": "海南省学宇思网络科技有限公司",
|
||
"taxpayer_id": "91460108MADNY3F43W",
|
||
"bank_name": "中国银行海口分行", // 专票必填
|
||
"bank_account": "1234567890123456", // 专票必填
|
||
"company_address": "海南省海口市", // 专票必填
|
||
"company_phone": "0898-12345678", // 专票必填
|
||
"receiving_email": "ilirnax@gmail.com"
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "申请开票成功",
|
||
"data": {
|
||
"id": "uuid",
|
||
"user_id": "user_uuid",
|
||
"invoice_type": "general",
|
||
"amount": "1000.00",
|
||
"status": "pending",
|
||
"invoice_info": {
|
||
"company_name": "海南省学宇思网络科技有限公司",
|
||
"taxpayer_id": "91460108MADNY3F43W",
|
||
"receiving_email": "ilirnax@gmail.com"
|
||
},
|
||
"created_at": "2024-01-01T12:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 获取用户发票信息
|
||
|
||
**接口地址**: `GET /api/v1/invoices/info`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "获取发票信息成功",
|
||
"data": {
|
||
"company_name": "海南省学宇思网络科技有限公司",
|
||
"taxpayer_id": "91460108MADNY3F43W",
|
||
"bank_name": "",
|
||
"bank_account": "",
|
||
"company_address": "",
|
||
"company_phone": "",
|
||
"receiving_email": "ilirnax@gmail.com",
|
||
"is_complete": false,
|
||
"missing_fields": ["基本开户银行", "基本开户账号", "企业注册地址", "企业注册电话"]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 更新用户发票信息
|
||
|
||
**接口地址**: `PUT /api/v1/invoices/info`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"company_name": "海南省学宇思网络科技有限公司",
|
||
"taxpayer_id": "91460108MADNY3F43W",
|
||
"bank_name": "中国银行海口分行",
|
||
"bank_account": "1234567890123456",
|
||
"company_address": "海南省海口市",
|
||
"company_phone": "0898-12345678",
|
||
"receiving_email": "ilirnax@gmail.com"
|
||
}
|
||
```
|
||
|
||
### 4. 获取用户开票记录
|
||
|
||
**接口地址**: `GET /api/v1/invoices/records?page=1&page_size=10&status=completed`
|
||
|
||
**查询参数**:
|
||
- `page`: 页码 (默认: 1)
|
||
- `page_size`: 每页数量 (默认: 10, 最大: 100)
|
||
- `status`: 状态筛选 (可选: pending, completed, rejected)
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "获取开票记录成功",
|
||
"data": {
|
||
"records": [
|
||
{
|
||
"id": "uuid",
|
||
"user_id": "user_uuid",
|
||
"invoice_type": "general",
|
||
"amount": "1000.00",
|
||
"status": "completed",
|
||
"company_name": "海南省学宇思网络科技有限公司",
|
||
"file_name": "invoice_20240101.pdf",
|
||
"file_size": 1024000,
|
||
"file_url": "https://example.com/invoice.pdf",
|
||
"processed_at": "2024-01-01T14:00:00Z",
|
||
"created_at": "2024-01-01T12:00:00Z"
|
||
}
|
||
],
|
||
"total": 1,
|
||
"page": 1,
|
||
"page_size": 10,
|
||
"total_pages": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5. 获取可开票金额
|
||
|
||
**接口地址**: `GET /api/v1/invoices/available-amount`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "获取可开票金额成功",
|
||
"data": {
|
||
"available_amount": "5000.00",
|
||
"total_recharged": "10000.00",
|
||
"total_gifted": "1000.00",
|
||
"total_invoiced": "4000.00"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6. 下载发票文件
|
||
|
||
**接口地址**: `GET /api/v1/invoices/{application_id}/download`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "获取下载信息成功",
|
||
"data": {
|
||
"file_id": "file_uuid",
|
||
"file_name": "invoice_20240101.pdf",
|
||
"file_size": 1024000,
|
||
"file_url": "https://example.com/invoice.pdf"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 管理员接口
|
||
|
||
### 1. 获取待处理的发票申请列表
|
||
|
||
**接口地址**: `GET /api/v1/admin/invoices/pending?page=1&page_size=10`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "获取待处理申请列表成功",
|
||
"data": {
|
||
"applications": [
|
||
{
|
||
"id": "uuid",
|
||
"user_id": "user_uuid",
|
||
"invoice_type": "general",
|
||
"amount": "1000.00",
|
||
"status": "pending",
|
||
"company_name": "海南省学宇思网络科技有限公司",
|
||
"receiving_email": "ilirnax@gmail.com",
|
||
"created_at": "2024-01-01T12:00:00Z"
|
||
}
|
||
],
|
||
"total": 1,
|
||
"page": 1,
|
||
"page_size": 10,
|
||
"total_pages": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 通过发票申请（上传发票）
|
||
|
||
**接口地址**: `POST /api/v1/admin/invoices/{application_id}/approve`
|
||
|
||
**请求方式**: `multipart/form-data`
|
||
|
||
**请求参数**:
|
||
- `file`: 发票文件 (PDF格式)
|
||
- `admin_notes`: 管理员备注 (可选)
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "通过发票申请成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 3. 拒绝发票申请
|
||
|
||
**接口地址**: `POST /api/v1/admin/invoices/{application_id}/reject`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"reason": "发票信息不完整，请补充企业注册地址和电话"
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "拒绝发票申请成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
## 错误码说明
|
||
|
||
| 状态码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 请求成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 用户未登录或认证已过期 |
|
||
| 403 | 权限不足 |
|
||
| 404 | 资源不存在 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
## 业务规则
|
||
|
||
### 开票金额限制
|
||
- 用户只能申请充值金额（除去赠送）减去已开票金额
|
||
- 开票金额必须大于0
|
||
|
||
### 发票信息验证
|
||
- **普票**: 至少需要公司名称、纳税人识别号、接收邮箱
|
||
- **专票**: 需要完整的企业信息（包括银行信息、地址、电话）
|
||
|
||
### 状态流转
|
||
- `pending` (待处理) → `completed` (已完成) 或 `rejected` (已拒绝)
|
||
|
||
### 文件要求
|
||
- 发票文件格式：PDF
|
||
- 文件大小限制：10MB
|
||
- 文件命名：`invoice_{application_id}.pdf`
|
||
|
||
## 注意事项
|
||
|
||
1. 所有接口都需要JWT认证
|
||
2. 管理员接口需要管理员权限
|
||
3. 文件上传接口使用 `multipart/form-data` 格式
|
||
4. 金额字段使用字符串格式，精确到分
|
||
5. 时间字段使用ISO 8601格式 |