440 lines
8.6 KiB
Markdown
440 lines
8.6 KiB
Markdown
# 发票服务 API 文档
|
||
|
||
## 基本信息
|
||
|
||
- **服务地址**: `http://localhost:8086`
|
||
- **API版本**: v1
|
||
- **Base Path**: `/api/invoices`
|
||
|
||
## 认证
|
||
|
||
所有API请求需要在Header中传递用户信息：
|
||
- `X-User-Id`: 用户ID
|
||
- `X-User-Name`: 用户名称
|
||
|
||
---
|
||
|
||
## 接口列表
|
||
|
||
### 1. 获取发票列表
|
||
|
||
**GET** `/api/invoices`
|
||
|
||
分页查询发票列表
|
||
|
||
**请求参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| tenantId | Long | 否 | 租户ID |
|
||
| status | Integer | 否 | 发票状态：0-待审核, 1-已开具, 2-已作废, 3-已红冲 |
|
||
| invoiceType | Integer | 否 | 发票类型：1-专用发票, 2-普通发票, 3-电子发票, 4-卷式发票 |
|
||
| keyword | String | 否 | 关键词搜索（发票号、购方名称、订单号） |
|
||
| startDate | String | 否 | 开始日期 (yyyy-MM-dd) |
|
||
| endDate | String | 否 | 结束日期 (yyyy-MM-dd) |
|
||
| page | Integer | 否 | 页码，默认1 |
|
||
| size | Integer | 否 | 每页数量，默认20 |
|
||
|
||
**响应示例:**
|
||
```json
|
||
{
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"invoiceNo": "INV20260404001",
|
||
"invoiceType": 2,
|
||
"invoiceTypeName": "增值税普通发票",
|
||
"status": 1,
|
||
"statusName": "已开具",
|
||
"buyerName": "测试公司",
|
||
"buyerTaxNo": "91110000XXXXXXXX",
|
||
"totalAmount": 1130.00,
|
||
"amount": 1000.00,
|
||
"taxAmount": 130.00,
|
||
"taxRate": 0.13,
|
||
"invoiceDate": "2026-04-04",
|
||
"applyDate": "2026-04-03",
|
||
"createdAt": "2026-04-03T10:00:00"
|
||
}
|
||
],
|
||
"total": 100,
|
||
"current_page": 1,
|
||
"last_page": 5,
|
||
"page_size": 20
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 获取发票详情
|
||
|
||
**GET** `/api/invoices/{id}`
|
||
|
||
根据ID获取发票详细信息
|
||
|
||
**路径参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | Long | 是 | 发票ID |
|
||
|
||
**响应示例:**
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"invoiceNo": "INV20260404001",
|
||
"invoiceCode": "144031900110",
|
||
"invoiceType": 2,
|
||
"invoiceTypeName": "增值税普通发票",
|
||
"status": 1,
|
||
"statusName": "已开具",
|
||
"buyerName": "测试公司",
|
||
"buyerTaxNo": "91110000XXXXXXXX",
|
||
"buyerAddressPhone": "北京市朝阳区 010-12345678",
|
||
"buyerBankAccount": "中国银行 123456789",
|
||
"sellerName": "销售公司",
|
||
"sellerTaxNo": "91110000YYYYYYYY",
|
||
"totalAmount": 1130.00,
|
||
"amount": 1000.00,
|
||
"taxAmount": 130.00,
|
||
"taxRate": 0.13,
|
||
"orderId": 100,
|
||
"orderNo": "ORD20260401001",
|
||
"customerId": 50,
|
||
"customerName": "测试客户",
|
||
"invoiceContent": "咨询服务",
|
||
"drawer": "开票人",
|
||
"reviewer": "复核人",
|
||
"payee": "收款人",
|
||
"invoiceDate": "2026-04-04",
|
||
"applyDate": "2026-04-03",
|
||
"pdfPath": "/files/invoices/2026/04/INV20260404001.pdf",
|
||
"imagePath": "/files/invoices/2026/04/INV20260404001.png",
|
||
"applicantId": 10,
|
||
"applicantName": "张三",
|
||
"auditorId": 20,
|
||
"auditorName": "李四",
|
||
"issuerId": 30,
|
||
"issuerName": "王五",
|
||
"items": [
|
||
{
|
||
"id": 1,
|
||
"goodsName": "咨询服务",
|
||
"spec": "标准版",
|
||
"unit": "次",
|
||
"quantity": 1.0000,
|
||
"unitPrice": 1130.00,
|
||
"amount": 1000.00,
|
||
"taxRate": 0.13,
|
||
"taxAmount": 130.00,
|
||
"totalAmount": 1130.00
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 根据发票号获取发票
|
||
|
||
**GET** `/api/invoices/no/{invoiceNo}`
|
||
|
||
**路径参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| invoiceNo | String | 是 | 发票号 |
|
||
|
||
---
|
||
|
||
### 4. 创建发票申请
|
||
|
||
**POST** `/api/invoices`
|
||
|
||
**请求体:**
|
||
```json
|
||
{
|
||
"invoiceType": 2,
|
||
"buyerName": "测试公司",
|
||
"buyerTaxNo": "91110000XXXXXXXX",
|
||
"buyerAddressPhone": "北京市朝阳区 010-12345678",
|
||
"buyerBankAccount": "中国银行 123456789",
|
||
"totalAmount": 1130.00,
|
||
"amount": 1000.00,
|
||
"taxAmount": 130.00,
|
||
"taxRate": 0.13,
|
||
"orderId": 100,
|
||
"orderNo": "ORD20260401001",
|
||
"customerId": 50,
|
||
"customerName": "测试客户",
|
||
"invoiceContent": "咨询服务",
|
||
"remark": "备注信息",
|
||
"items": [
|
||
{
|
||
"goodsName": "咨询服务",
|
||
"spec": "标准版",
|
||
"unit": "次",
|
||
"quantity": 1.0000,
|
||
"unitPrice": 1130.00,
|
||
"amount": 1000.00,
|
||
"taxRate": 0.13,
|
||
"taxAmount": 130.00,
|
||
"totalAmount": 1130.00
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**响应:** 返回创建的发票详情
|
||
|
||
---
|
||
|
||
### 5. 更新发票申请
|
||
|
||
**PUT** `/api/invoices/{id}`
|
||
|
||
仅允许更新待审核状态的发票
|
||
|
||
**路径参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | Long | 是 | 发票ID |
|
||
|
||
**请求体:** 同创建发票申请
|
||
|
||
---
|
||
|
||
### 6. 删除发票申请
|
||
|
||
**DELETE** `/api/invoices/{id}`
|
||
|
||
仅允许删除待审核状态的发票
|
||
|
||
**路径参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | Long | 是 | 发票ID |
|
||
|
||
---
|
||
|
||
### 7. 审核发票申请
|
||
|
||
**POST** `/api/invoices/{id}/audit`
|
||
|
||
**路径参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | Long | 是 | 发票ID |
|
||
|
||
**请求参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| auditStatus | Integer | 是 | 审核状态：1-通过, 0-拒绝 |
|
||
| auditRemark | String | 否 | 审核备注 |
|
||
|
||
**响应:** 返回审核后的发票详情
|
||
|
||
---
|
||
|
||
### 8. 开具发票
|
||
|
||
**POST** `/api/invoices/{id}/issue`
|
||
|
||
**路径参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | Long | 是 | 发票ID |
|
||
|
||
**请求参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| invoiceNo | String | 是 | 发票号码 |
|
||
| invoiceCode | String | 否 | 发票代码 |
|
||
| invoiceDate | String | 否 | 开票日期 (yyyy-MM-dd)，默认当天 |
|
||
| drawer | String | 否 | 开票人 |
|
||
| reviewer | String | 否 | 复核人 |
|
||
| payee | String | 否 | 收款人 |
|
||
|
||
**响应:** 返回开具后的发票详情
|
||
|
||
---
|
||
|
||
### 9. 作废发票
|
||
|
||
**POST** `/api/invoices/{id}/void`
|
||
|
||
**路径参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | Long | 是 | 发票ID |
|
||
|
||
**请求参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| reason | String | 是 | 作废原因 |
|
||
|
||
**响应:** 返回作废后的发票详情
|
||
|
||
---
|
||
|
||
### 10. 红冲发票
|
||
|
||
**POST** `/api/invoices/{id}/reverse`
|
||
|
||
**路径参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | Long | 是 | 发票ID |
|
||
|
||
**请求参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| reason | String | 是 | 红冲原因 |
|
||
|
||
**响应:** 返回红冲后的发票详情
|
||
|
||
---
|
||
|
||
### 11. 根据订单ID获取发票列表
|
||
|
||
**GET** `/api/invoices/order/{orderId}`
|
||
|
||
**路径参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| orderId | Long | 是 | 订单ID |
|
||
|
||
---
|
||
|
||
### 12. 根据客户ID获取发票列表
|
||
|
||
**GET** `/api/invoices/customer/{customerId}`
|
||
|
||
**路径参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| customerId | Long | 是 | 客户ID |
|
||
|
||
---
|
||
|
||
### 13. 获取租户已开具发票总金额
|
||
|
||
**GET** `/api/invoices/tenant/{tenantId}/amount`
|
||
|
||
**路径参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| tenantId | Long | 是 | 租户ID |
|
||
|
||
**响应示例:**
|
||
```json
|
||
100000.00
|
||
```
|
||
|
||
---
|
||
|
||
### 14. 获取日期范围内发票数量
|
||
|
||
**GET** `/api/invoices/tenant/{tenantId}/count`
|
||
|
||
**路径参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| tenantId | Long | 是 | 租户ID |
|
||
|
||
**请求参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| startDate | String | 是 | 开始日期 (yyyy-MM-dd) |
|
||
| endDate | String | 是 | 结束日期 (yyyy-MM-dd) |
|
||
|
||
**响应示例:**
|
||
```json
|
||
10
|
||
```
|
||
|
||
---
|
||
|
||
### 15. 更新发票PDF路径
|
||
|
||
**PUT** `/api/invoices/{id}/pdf`
|
||
|
||
**路径参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | Long | 是 | 发票ID |
|
||
|
||
**请求参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| pdfPath | String | 是 | PDF文件路径 |
|
||
|
||
---
|
||
|
||
### 16. 更新发票图片路径
|
||
|
||
**PUT** `/api/invoices/{id}/image`
|
||
|
||
**路径参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | Long | 是 | 发票ID |
|
||
|
||
**请求参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| imagePath | String | 是 | 图片文件路径 |
|
||
|
||
---
|
||
|
||
### 17. 获取发票明细
|
||
|
||
**GET** `/api/invoices/{id}/items`
|
||
|
||
**路径参数:**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | Long | 是 | 发票ID |
|
||
|
||
---
|
||
|
||
## 错误码
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| INVOICE_ERROR | 发票业务异常 |
|
||
| VALIDATION_ERROR | 参数校验失败 |
|
||
| SYSTEM_ERROR | 系统异常 |
|
||
|
||
---
|
||
|
||
## 发票状态流转
|
||
|
||
```
|
||
待审核(0) --> 已开具(1) --> 已作废(2)
|
||
|
|
||
+--> 已红冲(3)
|
||
|
||
待审核(0) --> 已作废(2) (审核拒绝)
|
||
```
|