接入文档 /发票开具/重试与失败处理

重试与失败处理

开票失败（state == -1）的申请可以在修正原因后重新发起开票；开票中（state == 4）长时间无结果的申请可以主动置为失败后重新提交。

按外部订单号重试开票

POST/invoice/retry

参数	类型	必填	说明
appKey	string	条件必填	服务密钥 Key，与 appSecret 成对使用；传了 accessToken 时可不传
appSecret	string	条件必填	服务密钥 Secret
accessToken	string	条件必填	访问令牌，通过获取访问令牌接口获取；传了 accessToken 则无需 appKey / appSecret
taxNumber	string	必填	企业纳税人识别号，指定本次操作的开票企业；必须是该密钥已关联的企业
outOrderNos	array	必填	外部订单号数组

json

{
  "appKey": "你的appKey",
  "appSecret": "你的appSecret",
  "taxNumber": "91320211MA1WML8X6T",
  "outOrderNos": ["ORDER20260101001", "ORDER20260101002"]
}

json

{
  "code": 1,
  "message": "提交成功"
}

message	说明
xxx订单号不存在	外部订单号在当前企业下不存在
非法参数	订单号不属于当前企业

按发票 ID 批量重试开票

POST/invoice/batch-retry

参数	类型	必填	说明
appKey	string	条件必填	服务密钥 Key，与 appSecret 成对使用；传了 accessToken 时可不传
appSecret	string	条件必填	服务密钥 Secret
accessToken	string	条件必填	访问令牌，通过获取访问令牌接口获取；传了 accessToken 则无需 appKey / appSecret
taxNumber	string	必填	企业纳税人识别号，指定本次操作的开票企业；必须是该密钥已关联的企业
ids	array	必填	发票 ID 数组；状态为放弃开票（`-9`）的记录会被跳过

json

{
  "appKey": "你的appKey",
  "appSecret": "你的appSecret",
  "taxNumber": "91320211MA1WML8X6T",
  "ids": [10001, 10002]
}

重试最早一张开票失败发票

GET/invoice/retry-first

取当前企业最早一张开票失败（state == -1）的发票重新开票，适合定时任务逐张重试。

参数	类型	必填	说明
appKey	string	条件必填	服务密钥 Key，与 appSecret 成对使用；传了 accessToken 时可不传
appSecret	string	条件必填	服务密钥 Secret
accessToken	string	条件必填	访问令牌，通过获取访问令牌接口获取；传了 accessToken 则无需 appKey / appSecret
taxNumber	string	必填	企业纳税人识别号，指定本次操作的开票企业；必须是该密钥已关联的企业

json

{
  "code": 1,
  "message": "已提交"
}

没有开票失败发票时返回 暂无开票失败发票。

测试环境

企业开启「是否测试环境」时，以上重试接口直接返回 提交成功，不会真正重试。

重新下载发票版式文件

GET/invoice/{outOrderNo}/file-refresh

开票成功但 PDF / OFD / XML 文件缺失或损坏时，重新从电子税务局下载版式文件，异步处理。

参数	类型	必填	说明
outOrderNo	string	必填	路径参数，外部订单号
appKey	string	条件必填	服务密钥 Key，与 appSecret 成对使用；传了 accessToken 时可不传
appSecret	string	条件必填	服务密钥 Secret
accessToken	string	条件必填	访问令牌，通过获取访问令牌接口获取；传了 accessToken 则无需 appKey / appSecret
taxNumber	string	必填	企业纳税人识别号，指定本次操作的开票企业；必须是该密钥已关联的企业

json

{
  "code": 1,
  "message": "已提交，稍后生效"
}

message	说明
xxx订单号不存在	外部订单号不存在
xxx发票暂无下载地址，无法刷新文件	该发票没有税局下载地址

开票中变更为开票失败

POST/invoice/{id}/making-failure

把开票中（state == 4）且确认未在电子税务局开具的申请置为开票失败，之后可修改参数重新提交。鉴权参数以表单或 Query String 方式传递。

参数	类型	必填	说明
id	int	必填	路径参数，发票 ID
appKey	string	条件必填	服务密钥 Key，与 appSecret 成对使用；传了 accessToken 时可不传
appSecret	string	条件必填	服务密钥 Secret
accessToken	string	条件必填	访问令牌，通过获取访问令牌接口获取；传了 accessToken 则无需 appKey / appSecret
taxNumber	string	必填	企业纳税人识别号，指定本次操作的开票企业；必须是该密钥已关联的企业

bash

curl -X POST "https://fapiao-api.easyapi.com/invoice/10001/making-failure?appKey=你的appKey&appSecret=你的appSecret&taxNumber=91320211MA1WML8X6T"

json

{
  "code": 1,
  "message": "变更成功"
}

变更后会按回调通知规则推送一条「开票失败」通知，failMsg 为 开票中发票主动变更为开票失败。

message	说明
非法发票ID参数	发票不属于当前企业
只允许开票中发票变更为开票失败	发票状态不是 `4`
助手在线，发票即将开具不能重置为开票失败	发票已进入开票队列且助手在线
正在开票中，无法取消 / 当前发票正在开票中，请稍后再试	发票正在电子税务局开具

测试发票变更为开票失败

POST/invoice/{id}/test-failure

仅用于联调：把测试环境开具的发票（审核中或开票成功）改为开票失败，并触发一次「开票失败」回调，便于验证失败回调处理逻辑。正式发票不允许调用。

参数	类型	必填	说明
id	int	必填	路径参数，发票 ID
appKey	string	条件必填	服务密钥 Key，与 appSecret 成对使用；传了 accessToken 时可不传
appSecret	string	条件必填	服务密钥 Secret
accessToken	string	条件必填	访问令牌，通过获取访问令牌接口获取；传了 accessToken 则无需 appKey / appSecret
taxNumber	string	必填	企业纳税人识别号，指定本次操作的开票企业；必须是该密钥已关联的企业

message	说明
只允许审核中、开票成功发票变更为开票失败	发票状态不是 `0` 或 `1`
暂不支持正式环境发票主动变更为开票失败	发票不是测试环境开具