docs(invoice): 发票申请最终契约 - 新增2文件 + 勘误2文件(#4290 #4292 #4302)
新增: - changelogs-v2/2026-06/23_4290_发票申请入参票种修正-修改接口-管理后台.md - changelogs-v2-mp/2026-06/23_4290_发票申请票种修正-修改接口-小程序端.md 勘误: - 23_4258_发票详情接口:删除 mailAddress 出参字段、去掉 ELECTRONIC 枚举、email 改为始终有值 - 23_4265_发票列表:invoiceType 枚举去掉 ELECTRONIC(普票/专票两值) 契约定稿要点:invoiceType 只有 VAT_NORMAL/VAT_SPECIAL;email 始终必填+格式; 专票限 COMPANY 抬头(581523);专票五项全必填(581515);删 mailAddress(全电子交付)
这个提交包含在:
@@ -6,6 +6,11 @@
|
||||
|
||||
---
|
||||
|
||||
> **勘误(2026-06-23,#4292 #4302)**:本文件初版(#4262)包含 3 处与最终实现不符的内容,已在本次修正:
|
||||
> 1. `invoiceType` 枚举已删除 `ELECTRONIC`(电子发票),只保留 `VAT_NORMAL`(增值税普通发票)和 `VAT_SPECIAL`(增值税专用发票)
|
||||
> 2. 出参已删除 `mailAddress` 字段(无纸质邮寄,全电子交付)
|
||||
> 3. `email` 字段始终有值(全电子交付),不再是"电子发票为 null"
|
||||
|
||||
## 接口背景
|
||||
|
||||
财务在「上传发票 PDF」弹窗或发票详情页中,需要读取完整的开票申请明细:抬头信息、开票金额、专票四项(银行账号、注册地址、注册电话)、开票后的发票号 / PDF / 推送记录。本接口返回单张发票的全量字段,供弹窗回显和详情页展示使用。
|
||||
@@ -73,8 +78,7 @@
|
||||
| `registAddress` | string / null | 注册地址,**仅专票**有值,其余 null |
|
||||
| `registPhone` | string / null | 注册电话,**仅专票**有值,其余 null |
|
||||
| `amount` | string | 开票金额,单位**分**,字符串防精度丢失,如 `"98600"` |
|
||||
| `email` | string / null | 电子发票接收邮箱 |
|
||||
| `mailAddress` | string / null | 纸质发票邮寄地址,电子发票为 null |
|
||||
| `email` | string | 收件邮箱(始终有值,全电子交付) |
|
||||
| `applyReason` | string / null | 备注(申请原因) |
|
||||
|
||||
### 状态字段
|
||||
@@ -124,7 +128,6 @@
|
||||
|--------|--------|------|
|
||||
| `VAT_NORMAL` | 增值税普通发票 | 普票,专票四项字段均为 null |
|
||||
| `VAT_SPECIAL` | 增值税专用发票 | 专票,bankName / bankAccount / registAddress / registPhone 有值 |
|
||||
| `ELECTRONIC` | 电子发票 | 电子普票,mailAddress 为 null,仅 email 有值 |
|
||||
|
||||
### 抬头类型(titleType)
|
||||
|
||||
@@ -184,7 +187,6 @@ Authorization: Bearer <token>
|
||||
"registPhone": null,
|
||||
"amount": "98600",
|
||||
"email": "finance@hulalv.com",
|
||||
"mailAddress": null,
|
||||
"applyReason": "报销使用",
|
||||
"status": "REQUESTED",
|
||||
"statusText": "待开票",
|
||||
@@ -235,7 +237,6 @@ Authorization: Bearer <token>
|
||||
"registPhone": "021-12345678",
|
||||
"amount": "150000",
|
||||
"email": null,
|
||||
"mailAddress": "上海市浦东新区财务部",
|
||||
"applyReason": null,
|
||||
"status": "ISSUED",
|
||||
"statusText": "已开票(待推送)",
|
||||
@@ -288,7 +289,7 @@ Authorization: Bearer <token>
|
||||
- 小程序端查询发票(本接口仅管理后台)
|
||||
|
||||
**特殊边界**
|
||||
- 专票四项字段(`bankName` / `bankAccount` / `registAddress` / `registPhone`):仅 `invoiceType=VAT_SPECIAL` 时有值,前端按 invoiceType 决定是否展示这四项
|
||||
- 专票五项字段(`taxNo` / `bankName` / `bankAccount` / `registAddress` / `registPhone`):taxNo 普票公司抬头也需填,专票四项仅 `invoiceType=VAT_SPECIAL` 时有值,前端按 invoiceType 决定是否展示
|
||||
- 开票痕迹字段(`invoiceNo` / `fileUrl` / `pdfName` / `pdfSize` / `issuedBy` / `issuedAt`):状态为 `ISSUED` 或 `PUSHED` 时有值,`REQUESTED` 和 `VOIDED` 时为 null
|
||||
- 推送痕迹字段(`pushedAt` / `pushedChannels`):仅 `PUSHED` 时有值
|
||||
- `amount` 单位为**分**,前端展示时除以 100 转为元
|
||||
|
||||
在新工单中引用
屏蔽一个用户