2.7 KiB
2.7 KiB
Contract: IF-REV-009 发票结果查询与客户侧消费接口
1. 合同定位
本合同用于固化 REV-005 一期发票结果查询、查询兜底补偿以及客户侧查看/下载/推送已开票电子发票的统一口径。
2. 适用范围
适用场景：
- 后台按申请单号 / 受理号查询发票最终状态
- 系统定时轮询
SYS-008获取开票结果 - 客户侧查看已开具电子发票
- 客户侧下载、推送电子发票
不适用范围：
- 客户侧直接发起开票申请
- 发票作废 / 红冲全流程深度处理
3. 查询请求合同
| 字段 | 类型 | 必填 | 说明 | 约束 |
|---|---|---|---|---|
| applicationNo | String | 否 | 发票申请单号 | 与 sysRequestNo 二选一 |
| sysRequestNo | String | 否 | 外部受理号 | 与 applicationNo 二选一 |
| custId | Long | 否 | 客户 ID | 客户侧查询时使用 |
| querySource | String | 是 | 查询来源 | SYSTEM_JOB / ADMIN / CUSTOMER |
| pushEmail | String | 否 | 推送邮箱 | 客户侧推送时使用 |
4. 查询响应合同
| 字段 | 类型 | 说明 | 约束 |
|---|---|---|---|
| invoiceId | Long | 发票记录 ID | 对应 biz_invoice.id |
| applicationNo | String | 发票申请单号 | 幂等主键 |
| invoiceStatus | String | 发票状态 | PENDING / SUCCESS / FAIL / INVALID / RED_INK |
| invoiceCode | String | 发票代码 | 成功后返回 |
| invoiceNumber | String | 发票号码 | 成功后返回 |
| fileUrl | String | 电子票下载地址 | 成功后返回 |
| failReason | String | 失败原因 | 失败时返回 |
| pushStatus | String | 推送状态 | NONE / PUSHED / FAIL |
| lastQueryTime | DateTime | 最近查询时间 | 用于补偿追踪 |
5. 共性规则
- 查询兜底是开票结果获取的必备路径，不可省略。
- 已成功开票状态不得被后续失败结果覆盖。
- 客户侧只允许查询、下载、推送属于当前客户的已开票电子发票。
- 下载/推送前必须校验发票状态为
SUCCESS且存在fileUrl。 - 查询补偿任务需记录
lastTryTime、nextTryTime、tryCount等信息。
6. 物理承接口径
| 逻辑对象 | 物理承接 |
|---|---|
| 发票结果主对象 | biz_invoice |
| 客户查询身份与资料 | biz_cust_invoice |
| 查询补偿与结果留痕 | biz_invoice 扩展字段 + biz_operat_log* |
| 账单发票摘要展示 | biz_charge* + 历史关系快照 |
7. 验收关注点
- 是否支持后台按申请单号 / 受理号查询结果
- 是否支持系统任务轮询补偿
- 是否支持客户侧查看、下载、推送已开票电子发票
- 是否避免客户侧越权查询和重复推送