erp-java/services/invoice-service/deploy/API.md

发票服务 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

响应示例:

{
  "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

响应示例:

{
  "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

请求体:

{
  "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

响应示例:

100000.00

---

14. 获取日期范围内发票数量

GET /api/invoices/tenant/{tenantId}/count

路径参数:

参数	类型	必填	说明
tenantId	Long	是	租户ID

请求参数:

参数	类型	必填	说明
startDate	String	是	开始日期 (yyyy-MM-dd)
endDate	String	是	结束日期 (yyyy-MM-dd)

响应示例:

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) (审核拒绝)