69 lines
2.8 KiB
Markdown
69 lines
2.8 KiB
Markdown
# Contract: IF-REV-008 发票申请接口
|
|
|
|
## 1. 合同定位
|
|
|
|
本合同用于固化 REV-005 一期后台发票申请 / 单笔与批量开票接口口径，服务于后续正式接口文档修订、任务拆解与 backend 实施。
|
|
|
|
## 2. 适用范围
|
|
|
|
适用场景：
|
|
- 后台营业收费员 / 财务人员发起单笔开票
|
|
- 后台按已收费账单集合批量发起开票
|
|
- 生成发票申请记录并提交 `SYS-008`
|
|
|
|
不适用范围：
|
|
- 客户侧直接申请开票
|
|
- 原始单账单直接任意部分金额开票
|
|
- 复杂拆分/合并开票策略配置
|
|
|
|
## 3. 请求合同
|
|
|
|
| 字段 | 类型 | 必填 | 说明 | 约束 |
|
|
|------|------|------|------|------|
|
|
| applicationNo | String | 否 | 发票申请单号 | 服务端生成，作为幂等主键之一 |
|
|
| chargeIds | Array<Long> | 是 | 关联账单 ID 列表 | 所有账单必须已收费且未开票 |
|
|
| custId | Long | 是 | 客户 ID | 必须存在可用开票信息 |
|
|
| invoiceType | String | 是 | 发票类型 | `ELECTRONIC` / `PAPER` |
|
|
| invoiceTitle | String | 是 | 发票抬头 | 来自 `biz_cust_invoice` 或后台确认输入 |
|
|
| taxNo | String | 否 | 纳税人识别号 | 企业抬头场景建议必填 |
|
|
| email | String | 否 | 接收邮箱 | 电子发票场景优先使用 |
|
|
| mobile | String | 否 | 接收手机号 | 推送或通知场景使用 |
|
|
| sourceChannel | String | 是 | 来源渠道 | `COUNTER` / `FINANCE_BACKOFFICE` |
|
|
| remark | String | 否 | 申请备注 | 进入操作留痕 |
|
|
|
|
## 4. 响应合同
|
|
|
|
| 字段 | 类型 | 说明 | 约束 |
|
|
|------|------|------|------|
|
|
| invoiceId | Long | 发票申请记录 ID | 对应 `biz_invoice.id` |
|
|
| applicationNo | String | 发票申请单号 | 后续查询与幂等主键 |
|
|
| invoiceStatus | String | 当前状态 | `SUBMITTED` / `PENDING` / `REJECTED` |
|
|
| sysRequestNo | String | `SYS-008` 受理号 | 异步查询主键 |
|
|
| msg | String | 处理说明 | 不可开票时返回明确原因 |
|
|
|
|
## 5. 共性规则
|
|
|
|
1. 所有账单必须处于“已收费、未开票、未作废”状态。
|
|
2. 一期不支持对原始单账单直接任意部分金额开票。
|
|
3. 如需多张发票，需来源于拆账/分账后的账单集合。
|
|
4. 幂等控制可采用 `applicationNo` 或 `custId + chargeIds` 组合。
|
|
5. 申请成功后必须生成查询补偿任务，不可依赖回调作为唯一结果来源。
|
|
6. 所有申请动作必须写入操作留痕。
|
|
|
|
## 6. 物理承接口径
|
|
|
|
| 逻辑对象 | 物理承接 |
|
|
|---------|----------|
|
|
| 发票申请主对象 | `biz_invoice` |
|
|
| 客户开票信息 | `biz_cust_invoice` |
|
|
| 税率配置 | `biz_invoice_taxrate` |
|
|
| 关联账单 | `biz_charge*` |
|
|
| 操作留痕 | `biz_operat_log*` |
|
|
|
|
## 7. 验收关注点
|
|
|
|
- 是否支持后台单笔 / 批量已收费账单开票
|
|
- 是否拒绝原始单账单直接部分金额开票
|
|
- 是否生成申请单号与查询主键
|
|
- 是否与 `SYS-008` 查询兜底模式一致
|