# 发票模块完整接口清单

> 本文档包含发票模块全部接口（管理端 + 用户端 + 内部调用），供前端对接参考

## AdminInvoice (发票管理)

> 接口文档: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) -> 分组「3.3 发票管理」 -> 标签「发票管理」

### `POST` /admin/invoice/upload -- 上传发票文件

> 上传发票PDF/图片文件，返回文件访问URL。

**响应** `Result<Map<String, String>>`

---

### `GET` /admin/invoice/page -- 发票分页列表

> 分页查询发票申请列表，支持按状态、订单号、用户ID筛选。

**响应** `Result<PageResult<InvoiceVO>>`

**关联字典**

  - `invoice_status`(发票状态): PENDING=待开票, ISSUED=已开票, FAILED=开票失败, VOIDED=已作废
  - `invoice_title_type`(抬头类型): PERSONAL=个人, COMPANY=企业

---

### `GET` /admin/invoice/{id} -- 发票详情

> 获取发票的完整信息，包含开票信息、用户信息、企业信息等。

**响应** `Result<InvoiceVO>`

---

### `PUT` /admin/invoice/{id}/issue -- 开票完成

> 管理员上传发票文件并填写发票号码后，将发票状态改为已开票。

**响应** `Result<InvoiceVO>`

---

### `PUT` /admin/invoice/{id}/fail -- 开票失败

> 标记发票开票失败，需填写失败原因。用户可根据原因修正后重新申请。

**响应** `Result<InvoiceVO>`

---

### `PUT` /admin/invoice/{id}/void -- 作废发票

> 将发票标记为已作废。已作废的发票不可重复作废。

**响应** `Result<InvoiceVO>`

---

## InternalInvoice (【内部接口】小程序发票（Feign调用）)

> 接口文档: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) -> 标签「【内部接口】小程序发票（Feign调用）」

### `POST` /internal/mp/invoice/apply -- 申请开票

> 用户对已支付订单申请开具电子发票。支持个人和企业抬头。

**响应** `Result<InvoiceVO>`

**关联字典**

  - `invoice_title_type`(抬头类型，请求/返回字段titleType): PERSONAL=个人, COMPANY=企业
  - `invoice_type`(发票类型，返回字段invoiceType): NORMAL=普通发票, SPECIAL=专用发票
  - `invoice_status`(发票状态，返回字段status): PENDING=待开票, ISSUED=已开票, FAILED=开票失败, CANCELLED=已作废

---

### `GET` /internal/mp/invoice/{id} -- 发票详情

> **关联字典**：

**响应** `Result<InvoiceVO>`

**关联字典**

  - `invoice_title_type`(抬头类型，返回字段titleType): PERSONAL=个人, COMPANY=企业
  - `invoice_type`(发票类型，返回字段invoiceType): NORMAL=普通发票, SPECIAL=专用发票
  - `invoice_status`(发票状态，返回字段status): PENDING=待开票, ISSUED=已开票, FAILED=开票失败, CANCELLED=已作废

---

### `GET` /internal/mp/invoice/order/{orderId} -- 通过订单ID查询发票

> 查询订单关联的发票信息。未开票时返回null

**响应** `Result<InvoiceVO>`

**关联字典**

  - `invoice_title_type`(抬头类型，返回字段titleType): PERSONAL=个人, COMPANY=企业
  - `invoice_type`(发票类型，返回字段invoiceType): NORMAL=普通发票, SPECIAL=专用发票
  - `invoice_status`(发票状态，返回字段status): PENDING=待开票, ISSUED=已开票, FAILED=开票失败, CANCELLED=已作废

---

## MpInvoice (C端 - 发票接口)

> 接口文档: [http://192.168.100.236:8086/doc.html](http://192.168.100.236:8086/doc.html) -> 标签「C端 - 发票接口」

### `POST` /mp/invoice/apply -- 申请开票

> 开票流程：订单完成后 → 填写发票信息(抬头/税号/类型) → 提交开票申请 → 管理员处理 → 发送电子发票

**响应** `Result<Map<String, Object>>`

---

### `GET` /mp/invoice/{id} -- 发票详情

> 获取发票的完整信息，包含开票状态、发票抬头、税号、金额、电子发票文件链接等

**响应** `Result<Map<String, Object>>`

---

### `GET` /mp/invoice/order/{orderId} -- 通过订单ID查询发票

> 查询指定订单的发票信息，如果订单未开票则返回null

**响应** `Result<Map<String, Object>>`

---

### `POST` /mp/invoice/{invoiceId}/reissue -- 发票换开

> 对已开发票申请换开（修改抬头/税号等），原发票作废后重新开具新发票

**响应** `Result<Map<String, Object>>`

---