218 行
8.3 KiB
Markdown
218 行
8.3 KiB
Markdown
# 发票申请删 amount · 门槛放宽（小程序端）
|
||
|
||
- **接口**：POST /v3/internal/mp/order/{orderId}/invoice/apply
|
||
- **变更类型**：修改接口，破坏性变更（申请入参删 amount；申请门槛扩展；新增错误码 581524）
|
||
- **端类型**：小程序端
|
||
- **日期**：2026-06-25
|
||
- **Issue**：[#4353](https://git.1814.love:8443/wx/HL/issues/4353)
|
||
- **PR**：[#4360](https://git.1814.love:8443/wx/HL/pulls/4360)
|
||
|
||
---
|
||
|
||
## 1 接口背景
|
||
|
||
小程序端发票申请接口（POST /v3/internal/mp/order/{orderId}/invoice/apply）本次同步两项改动：
|
||
|
||
1. **申请入参删 amount**：开票金额不再前端传入，开票时后端按规则自动计算（正常单=应收总额；取消单=净实收）。
|
||
2. **申请门槛放宽**：原门槛仅允许 COMPLETED（已完成）订单申请；放宽为定制中及以后均可申请，同时支持已取消但净实收 > 0 的订单申请。
|
||
|
||
---
|
||
|
||
## 2 变更清单
|
||
|
||
| # | 变更项 | 变更前 | 变更后 |
|
||
|---|--------|--------|--------|
|
||
| 1 | 申请入参 amount | 必填字段，客户填写开票金额 | ⚠️ 已删除，后端开票时自动算 |
|
||
| 2 | 申请门槛（正常订单） | 订单状态必须 COMPLETED | 状态 ∈ {CUSTOMIZING / PENDING_DEPARTURE / TRAVELLING / COMPLETED} 均可申请 |
|
||
| 3 | 申请门槛（取消订单） | 不允许 | CANCELLED 且净实收（已付 - 已退）> 0 时可申请 |
|
||
| 4 | 不满足门槛的错误码 | 581510 INVOICE_ORDER_NOT_COMPLETED | ✨ 新增 581524 INVOICE_ORDER_NOT_APPLICABLE（更精确语义） |
|
||
|
||
---
|
||
|
||
## 3 接口详情
|
||
|
||
| 属性 | 值 |
|
||
|------|----|
|
||
| 方法 | POST |
|
||
| 路径 | /v3/internal/mp/order/{orderId}/invoice/apply |
|
||
| 描述 | 客户自主申请开票（申请阶段不填金额，开票时后端自动算） |
|
||
| 认证 | Bearer JWT（小程序用户） |
|
||
| 幂等性 | 非幂等，重复提交触发 581511（一单一票） |
|
||
| 限流 | 无特殊限制 |
|
||
|
||
---
|
||
|
||
## 4 接口入参
|
||
|
||
### 4.1 路径参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| orderId | string（Long 雪花） | 是 | 订单 ID |
|
||
|
||
### 4.2 请求体字段（MpInvoiceApplyReqVO，⚠️ amount 已删）
|
||
|
||
当前完整字段列表（无 amount）：
|
||
|
||
| 字段 | 类型 | 必填条件 | 说明 |
|
||
|------|------|---------|------|
|
||
| invoiceType | string | 始终必填 | 发票类型，只有 VAT_NORMAL / VAT_SPECIAL 两值 |
|
||
| titleType | string | 始终必填 | 抬头类型：COMPANY（单位）/ PERSONAL（个人）；VAT_SPECIAL 只能 COMPANY |
|
||
| titleName | string | 始终必填 | 发票抬头（企业全称或个人姓名） |
|
||
| taxNo | string | titleType=COMPANY 或 invoiceType=VAT_SPECIAL 时必填 | 纳税人识别号 |
|
||
| bankName | string | invoiceType=VAT_SPECIAL 时必填 | 开户银行名称 |
|
||
| bankAccount | string | invoiceType=VAT_SPECIAL 时必填 | 银行账号 |
|
||
| registAddress | string | invoiceType=VAT_SPECIAL 时必填 | 注册地址 |
|
||
| registPhone | string | invoiceType=VAT_SPECIAL 时必填 | 注册电话 |
|
||
| email | string | 始终必填 | 收件邮箱，需通过邮箱格式校验 |
|
||
| remark | string | 选填 | 申请备注 |
|
||
|
||
---
|
||
|
||
## 5 出参字段
|
||
|
||
响应：成功返回新建发票 ID（字符串，雪花 ID）。
|
||
|
||
|
||
|
||
---
|
||
|
||
## 6 枚举 / 数据字典
|
||
|
||
### 6.1 发票类型（invoiceType）
|
||
|
||
| code | 说明 |
|
||
|------|------|
|
||
| VAT_NORMAL | 增值税普通发票 |
|
||
| VAT_SPECIAL | 增值税专用发票 |
|
||
|
||
### 6.2 抬头类型（titleType）
|
||
|
||
| code | 说明 | 限制 |
|
||
|------|------|------|
|
||
| COMPANY | 单位 | 普票/专票均可 |
|
||
| PERSONAL | 个人 | 只能选 VAT_NORMAL；选 VAT_SPECIAL 返回 581523 |
|
||
|
||
### 6.3 订单状态与可申请关系
|
||
|
||
| 订单状态（code） | 中文 | 可申请？ | 说明 |
|
||
|----------------|------|---------|------|
|
||
| CUSTOMIZING | 定制中 | 是 | 放宽新增 |
|
||
| PENDING_DEPARTURE | 待出行 | 是 | 放宽新增 |
|
||
| TRAVELLING | 出行中 | 是 | 放宽新增 |
|
||
| COMPLETED | 已完成 | 是 | 原有 |
|
||
| CANCELLED | 已取消 | 条件是 | 净实收（已付 - 已退）> 0 时可申请 |
|
||
| 其他状态 | - | 否 | 报 581524 |
|
||
|
||
### 6.4 开票时金额自动计算规则
|
||
|
||
| 订单类型 | 金额计算公式 |
|
||
|----------|-------------|
|
||
| 正常单（非 CANCELLED） | 应收总额 = 订单总价 + 增项 - 优惠 |
|
||
| 取消单（CANCELLED） | 净实收 = 已付金额 - 已退金额 |
|
||
|
||
---
|
||
|
||
## 7 错误码
|
||
|
||
| 错误码 | 常量 | 触发场景 |
|
||
|--------|------|----------|
|
||
| 581511 | INVOICE_ALREADY_EXISTS | 该订单已有有效发票，不可重复申请（一单一票） |
|
||
| 581513 | INVOICE_TYPE_INVALID | 发票类型枚举值非法 |
|
||
| 581514 | INVOICE_TAX_NO_REQUIRED | 公司抬头/专票时税号为必填 |
|
||
| 581515 | INVOICE_VAT_SPECIAL_FIELDS_REQUIRED | 专票时开户行/银行账号/注册地址/注册电话为必填 |
|
||
| 581516 | INVOICE_EMAIL_REQUIRED | 收件邮箱为必填或格式错误（HTTP 400） |
|
||
| 581518 | INVOICE_FORBIDDEN | 无权访问该订单（IDOR 防护） |
|
||
| 581523 | INVOICE_VAT_SPECIAL_PERSONAL_FORBIDDEN | 专票只能开给单位 |
|
||
| 581524 | INVOICE_ORDER_NOT_APPLICABLE | ✨ 新增：订单状态不在可申请集合内，或取消单净实收为 0 |
|
||
|
||
---
|
||
|
||
## 8 示例
|
||
|
||
### 8.1 典型成功——普票申请（无 amount 字段）
|
||
|
||
请求
|
||
|
||
|
||
|
||
响应
|
||
|
||
|
||
### 8.2 边界情况——订单处于定制中提前申请
|
||
|
||
说明：订单状态 CUSTOMIZING（定制中），本次放宽后允许申请。开票金额将在财务执行开票操作时按当时应收总额计算。
|
||
|
||
请求（结构同 8.1，orderId 为定制中订单 ID）
|
||
|
||
响应
|
||
|
||
|
||
### 8.3 业务失败——取消订单净实收为 0 被拒
|
||
|
||
说明：订单已取消，实付 1000 元且已全额退款，净实收 = 0，无法申请开票。
|
||
|
||
请求（结构同 8.1，orderId 为该取消订单 ID）
|
||
|
||
响应
|
||
|
||
|
||
---
|
||
|
||
## 9 业务边界
|
||
|
||
适用：
|
||
- 订单状态 ∈ {CUSTOMIZING / PENDING_DEPARTURE / TRAVELLING / COMPLETED} 均可申请
|
||
- CANCELLED 且净实收（已付 - 已退）> 0 时可申请
|
||
|
||
不适用：
|
||
- PAID（已支付但未进入定制阶段）等其他状态报 581524
|
||
- CANCELLED 且净实收 = 0 报 581524
|
||
- 订单不属于当前登录用户，报 581518（IDOR 防护）
|
||
|
||
特殊边界：
|
||
- 一单一票：同一订单只允许一张有效发票（REQUESTED/ISSUED/PUSHED 状态），重复申请报 581511
|
||
- 开票金额由后端在财务执行 issue 操作时自动计算，小程序端申请时不确定最终金额
|
||
|
||
---
|
||
|
||
## 10 修改前后对比
|
||
|
||
| 字段 / 规则 | 变更前 | 变更后 |
|
||
|-------------|--------|--------|
|
||
| 申请入参 amount | 必填，客户填写开票金额 | ⚠️ 已删除，后端开票时自动算 |
|
||
| 正常订单申请门槛 | 仅 COMPLETED | CUSTOMIZING / PENDING_DEPARTURE / TRAVELLING / COMPLETED |
|
||
| 取消订单申请 | 不允许 | 净实收 > 0 时可申请 |
|
||
| 不满足门槛错误码 | 581510 INVOICE_ORDER_NOT_COMPLETED（已废弃） | 581524 INVOICE_ORDER_NOT_APPLICABLE（新增） |
|
||
|
||
---
|
||
|
||
## 11 影响评估 / 回滚
|
||
|
||
破坏兼容性：是
|
||
|
||
- 小程序申请发票表单必须删除金额输入框，不再传 amount 字段
|
||
- 若现有流程中有基于 amount 的前端金额展示或校验逻辑，须同步移除
|
||
- 不满足门槛的错误提示由旧 581510 改为 581524，前端若 hardcode 了 581510 的处理逻辑需同步更新
|
||
|
||
前端同步上线：申请表单删 amount 必须与后端同期上线。
|
||
|
||
回滚方案：回滚后端至 #4360 前版本，amount 字段恢复必填，申请门槛收回到仅 COMPLETED，581524 不再存在。
|
||
|
||
---
|
||
|
||
## 12 注意事项
|
||
|
||
1. **amount 字段已删**：小程序申请发票表单必须移除金额输入框，不传 amount，传入后端会忽略。
|
||
2. **申请门槛放宽的注意点**：定制中等状态提前申请，开票时金额由财务执行 issue 操作时后端按当时应收总额计算，小程序无法在申请时预知最终开票金额。
|
||
3. **581524 vs 旧 581510**：新错误码 581524 取代了旧的 581510，含义更精确（包含取消单净实收为 0 的场景）。若前端有 581510 的 hardcode 判断需更新为 581524。
|
||
4. **开票金额由财务操作确定**：小程序端只负责申请，金额由后端在财务开票（PUT issue）时写入，前端无法在申请时展示最终金额。
|
||
|
||
---
|
||
|
||
## 13 关联 / 联系人
|
||
|
||
- **Issue**：[#4353 发票模块门槛放宽与开票规则优化](https://git.1814.love:8443/wx/HL/issues/4353)
|
||
- **PR**：[#4360](https://git.1814.love:8443/wx/HL/pulls/4360)
|
||
- **后端负责人**：腰苏图（yaosutu）
|