接入文档 /发票查询/批量查询发票状态

批量查询发票状态

按条件批量查询发票的状态与文件地址，返回精简字段，适合对账与补偿查询。

按条件查询

GET/invoice/state

同时支持 GET 与 POST。一次最多返回 100 条，按发票 ID 倒序。

参数	类型	必填	说明
appKey	string	条件必填	服务密钥 Key，与 appSecret 成对使用；传了 accessToken 时可不传
appSecret	string	条件必填	服务密钥 Secret
accessToken	string	条件必填	访问令牌，通过获取访问令牌接口获取；传了 accessToken 则无需 appKey / appSecret
taxNumber	string	必填	企业纳税人识别号，指定本次操作的开票企业；必须是该密钥已关联的企业
outOrderNo	string	选填	外部订单号（精确匹配）
outOrderNos	string	选填	多个外部订单号，用英文逗号分隔
color	string	选填	`blue` 蓝票 / `red` 红票
state	int	选填	基本状态，见发票状态说明
category	string	选填	发票类型
number	string	选填	发票号码（模糊匹配）
allElectronicInvoiceNumber	string	选填	数电发票号码（模糊匹配）
startAddTime	string	选填	申请时间起，`yyyy-MM-dd HH:mm:ss`
endAddTime	string	选填	申请时间止
startPrintTime	string	选填	开票成功时间起
endPrintTime	string	选填	开票成功时间止

bash

curl "https://fapiao-api.easyapi.com/invoice/state?appKey=你的appKey&appSecret=你的appSecret&taxNumber=91320211MA1WML8X6T&outOrderNos=ORDER20260101001,ORDER20260101002"

响应示例

json

{
  "code": 1,
  "message": "获取成功",
  "content": [
    {
      "invoiceId": 10001,
      "category": "全电电子普通发票",
      "outOrderNo": "ORDER20260101001",
      "state": 1,
      "auditState": 1,
      "printState": 1,
      "redState": 0,
      "cancelState": 0,
      "statements": "已开票",
      "failMsg": null,
      "printTime": "2026-01-01 10:00:35",
      "electronicInvoiceImg": "https://.../invoice.jpg",
      "electronicInvoiceUrl": "https://.../invoice.pdf",
      "electronicInvoiceOfd": "https://.../invoice.ofd",
      "electronicInvoiceXml": "https://.../invoice.xml",
      "downloadUrl": "https://.../download",
      "code": "",
      "number": "",
      "checkCode": "",
      "allElectronicInvoiceNumber": "26312000000000000001"
    }
  ]
}

没有匹配记录时返回 {"code":0,"message":"暂无数据"}。

字段说明

字段	类型	说明
invoiceId	int	发票 ID
category	string	发票类型
outOrderNo	string	外部订单号
state / auditState / printState / redState / cancelState	int	状态，见发票状态说明
statements	string	状态说明
failMsg	string	开票失败原因
printTime	string	开票成功时间
electronicInvoiceImg / electronicInvoiceUrl / electronicInvoiceOfd / electronicInvoiceXml	string	发票图片 / PDF / OFD / XML
downloadUrl	string	发票交付页地址
code / number / checkCode	string	发票代码 / 号码 / 校验码
allElectronicInvoiceNumber	string	数电发票号码

按外部订单号数组查询

GET/shop/batch-state

传入外部订单号数组，逐个返回对应蓝票的状态（字段同上）。该接口通过请求体传递 JSON 数组，部分 HTTP 客户端不支持 GET 携带请求体，此时请使用上面的 GET /invoice/state 并传 outOrderNos。

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

bash

curl -X GET "https://fapiao-api.easyapi.com/shop/batch-state?appKey=你的appKey&appSecret=你的appSecret&taxNumber=91320211MA1WML8X6T" \
  -H "Content-Type: application/json" \
  -d '["ORDER20260101001","ORDER20260101002"]'

任一订单号不存在时返回 xxx商户订单号发票不存在。