发票状态变更回调通知接口文档
1. 接口说明
该接口用于在发票状态变更时，向服务商（外部API来源）发起异步回调通知。
| 项目 |
说明 |
| 接口地址 |
由商户配置的 notify_url 决定 |
| 请求方式 |
POST |
| Content-Type |
application/json |
| 编码格式 |
UTF-8 |
2. 通知触发条件
3. 请求参数
3.1 公共字段
| 字段名 |
类型 |
必填 |
说明 |
fapiaoApplyId |
String |
是 |
发票申请单号（系统内部ID） |
outerApplyId |
String |
否 |
外部申请编号（服务商侧开票申请编号） |
eventType |
String |
是 |
事件类型，详见 事件类型说明 |
invoiceStatus |
String |
是 |
发票状态 |
invoiceNo |
String |
否 |
发票号码 |
invoiceCode |
String |
否 |
发票代码 |
failReason |
String |
否 |
失败原因 |
notifyTime |
String |
是 |
通知时间（格式：yyyy-MM-ddTHH:mm:ss） |
3.2 事件特定字段
4. 事件类型说明
| eventType |
说明 |
INVOICE_SUCCESS |
开票成功 |
INVOICE_FAIL |
开票失败 |
INVOICE_APPLYING |
开票受理成功（异步开票场景，表示请求已受理） |
REVERSE_SUCCESS |
红冲成功 |
REVERSE_FAIL |
红冲失败 |
5. 请求示例
5.1 INVOICE_SUCCESS（开票成功）
{
"fapiaoApplyId": "INV202406220001",
"outerApplyId": "OUTER202406220001",
"eventType": "INVOICE_SUCCESS",
"invoiceStatus": "SUCCESS",
"invoiceNo": "1234567890",
"invoiceCode": "011001900211",
"failReason": null,
"notifyTime": "2024-06-22T14:30:00"
}
5.2 INVOICE_FAIL（开票失败）
{
"outerApplyId": "OUTER202406220001",
"eventType": "INVOICE_FAIL",
"invoiceStatus": "FAIL",
"invoiceNo": null,
"invoiceCode": null,
"failReason": "开票失败：购方税号格式错误",
"notifyTime": "2024-06-22T14:30:00"
}
5.3 INVOICE_APPLYING（开票受理成功）
{
"outerApplyId": "OUTER202406220001",
"eventType": "INVOICE_APPLYING",
"invoiceStatus": "APPLYING",
"invoiceNo": null,
"invoiceCode": null,
"failReason": null,
"notifyTime": "2024-06-22T14:25:00"
}
5.4 REVERSE_SUCCESS（红冲成功）
{
"outerApplyId": "OUTER202406220001",
"eventType": "REVERSE_SUCCESS",
"invoiceStatus": "REVERSED",
"invoiceNo": "1234567890",
"invoiceCode": "011001900211",
"failReason": null,
"notifyTime": "2024-06-22T15:00:00"
}
5.5 REVERSE_FAIL（红冲失败）
{
"outerApplyId": "OUTER202406220001",
"eventType": "REVERSE_FAIL",
"invoiceStatus": "REVERSE_FAILED",
"invoiceNo": "1234567890",
"invoiceCode": "011001900211",
"failReason": "红冲失败：发票已作废",
"notifyTime": "2024-06-22T15:00:00"
}
6. 响应要求
接收方收到通知后，应在 5秒内 返回 HTTP 响应，响应内容为字符串 success（不区分大小写）：
| 条件 |
要求 |
| 接收成功 |
返回 HTTP 200 状态码，响应体为 success |
| 接收失败 |
返回非 200 状态码、响应体不为 success 或超时，系统将自动重试 |