diff --git a/changelogs/2026-03/2026-03-17_1720_invoice_full_api.md b/changelogs/2026-03/2026-03-17_1720_invoice_full_api.md new file mode 100644 index 0000000..45935dd --- /dev/null +++ b/changelogs/2026-03/2026-03-17_1720_invoice_full_api.md @@ -0,0 +1,142 @@ +# 发票模块完整接口清单 + +> 本文档包含发票模块全部接口(管理端 + 用户端 + 内部调用),供前端对接参考 + +## 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>` + +--- + +### `GET` /admin/invoice/page -- 发票分页列表 + +> 分页查询发票申请列表,支持按状态、订单号、用户ID筛选。 + +**响应** `Result>` + +**关联字典** + + - `invoice_status`(发票状态): PENDING=待开票, ISSUED=已开票, FAILED=开票失败, VOIDED=已作废 + - `invoice_title_type`(抬头类型): PERSONAL=个人, COMPANY=企业 + +--- + +### `GET` /admin/invoice/{id} -- 发票详情 + +> 获取发票的完整信息,包含开票信息、用户信息、企业信息等。 + +**响应** `Result` + +--- + +### `PUT` /admin/invoice/{id}/issue -- 开票完成 + +> 管理员上传发票文件并填写发票号码后,将发票状态改为已开票。 + +**响应** `Result` + +--- + +### `PUT` /admin/invoice/{id}/fail -- 开票失败 + +> 标记发票开票失败,需填写失败原因。用户可根据原因修正后重新申请。 + +**响应** `Result` + +--- + +### `PUT` /admin/invoice/{id}/void -- 作废发票 + +> 将发票标记为已作废。已作废的发票不可重复作废。 + +**响应** `Result` + +--- + +## 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` + +**关联字典** + + - `invoice_title_type`(抬头类型,请求/返回字段titleType): PERSONAL=个人, COMPANY=企业 + - `invoice_type`(发票类型,返回字段invoiceType): NORMAL=普通发票, SPECIAL=专用发票 + - `invoice_status`(发票状态,返回字段status): PENDING=待开票, ISSUED=已开票, FAILED=开票失败, CANCELLED=已作废 + +--- + +### `GET` /internal/mp/invoice/{id} -- 发票详情 + +> **关联字典**: + +**响应** `Result` + +**关联字典** + + - `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` + +**关联字典** + + - `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>` + +--- + +### `GET` /mp/invoice/{id} -- 发票详情 + +> 获取发票的完整信息,包含开票状态、发票抬头、税号、金额、电子发票文件链接等 + +**响应** `Result>` + +--- + +### `GET` /mp/invoice/order/{orderId} -- 通过订单ID查询发票 + +> 查询指定订单的发票信息,如果订单未开票则返回null + +**响应** `Result>` + +--- + +### `POST` /mp/invoice/{invoiceId}/reissue -- 发票换开 + +> 对已开发票申请换开(修改抬头/税号等),原发票作废后重新开具新发票 + +**响应** `Result>` + +---