NF-e 验证
DANFE 获取
按 chave 取本账户验证过的 NF-e 的 DANFE,直接返回 PDF 文件。
GET
/openapi/v3/consultas/danfe/{chave}需要
token、timestamp、sign 三个签名头,参见认证与签名。路径参数
chave* | string | 访问密钥 |
* 必填字段
200
DANFE 的 PDF 文件(不是 JSON)。响应头:
Content-Type: application/pdf;Content-Disposition: inline; filename="{chave}.pdf";Cache-Control: no-store;X-Tffiscal-Nfe-Status 为这份 PDF 对应的税务状态,Autorizada(正常版)或 Cancelada(作废水印版),不必解析 PDF 即可区分。鉴权方式与 chave 查询 相同:带 token、timestamp、sign 三个请求头,GET 的 body 取空串,chave 属于签名 path(完整规则见 认证与签名)。给定 app_secret = sk_live_9f8e7d6c5b4a、chave 35260764962869000108550990001366171195929648、timestamp = 1784906308,签名字符串为:
text
sign_input = "sk_live_9f8e7d6c5b4a"+ "/openapi/v3/consultas/danfe/35260764962869000108550990001366171195929648"+ ""+ "1784906308"sign = md5Hex(sign_input)
出不出 PDF,看取的那一刻这张票的验证结论:
| 当前验证结论 | 结果 |
|---|---|
VALIDATED | 正常版 DANFE |
REJECTED 且 status 为 Cancelada | 每页带 CANCELADA 作废水印的 DANFE |
验证未完成(PENDING_SEFAZ / VALIDATING) | 409 + 10015301,收到 webhook 后再取 |
其他(其余 REJECTED、VALIDATION_ERROR) | 409 + 10015302,不出 PDF |
- 只出 NF-e(模型 55)的 DANFE。
- 提交时 XML 不带授权协议(protNFe)的票,PDF 上的协议号与授权时间取自平台向 SEFAZ 核验得到的官方记录。
- PDF 反映取的那一刻的最新结论:同一张票不同时间取到的 PDF 可能不同。例如发票后来被取消,平台重新核验得到
Cancelada之后再取,拿到的就是作废水印版。取 PDF 不会刷新结论;结论按 幂等与重验 的规则更新,新结论经 webhook 推送。 - 响应带
Cache-Control: no-store:请不要在代理或网关缓存;需要留存请自行保存文件。 - 能取多久:平台保留该验证记录期间(缺省 3 个月)都能取;之后需重新提交验证。
- 收到
invoice.verify.completed后先回 2xx,再异步来取 PDF。不要在回调处理里同步取:回调处理变慢,平台向你推送回调的速率也随之降低(回调的处理要求见 接收端要求)。 - 只为
VALIDATED、以及需要时status为Cancelada的结论来取;其余结论取了也是 409。 - 503 按
Retry-After重试;404 与 409 不要原样重试(10015301等回调,10015303先按下一节「XML 原文缺失时」补 XML)。 - 限流:本端点单独一个接口组「DANFE 获取」,不占「发票验证」组的额度;应用总闸仍与其他接口共用。每张都取时,调用量约为提交量的两倍,请与平台约定额度(见 限流与退避)。
平台按你提交的 XML 原文生成 DANFE。极少数情况下(例如归档存储故障)平台没有保存下这张票的原文,取 PDF 返回 409 + 10015303。处理办法:
- 用 XML 验证 把同一份 XML 原样重新提交(与上次逐字节相同),不带
forceRevalidate。结论仍在复用期内时(见 幂等与重验,例如VALIDATED得出后 24 小时内,已取消的票一直复用),平台直接复用已有结论:不重新核验、不推送新事件,同时把这份原文补存上。已过复用期的,按规则完整重验,新结论经 webhook 推送。 - 再取 PDF(完整重验的,收到新结论后再取)。
注意:
- 内容不同的 XML 会按 幂等与重验 完整重验;已取消 / 已否决 / 已作废的票内容不同时直接复用、不会补存。请务必原样提交。
- 手里也没有这份 XML 时,平台无法出 DANFE(SEFAZ 的状态查询不返回商品明细)。
| 错误码 | HTTP | |
|---|---|---|
| 10015104 | 400 | chave 非法(长度 / 字符 / 校验位)。先本地校验:44 位数字,末位为 mod-11 校验位。 |
| 10015300 | 404 | 本账户没有这张票的验证记录(其他集成商验证过也一样)。先用 XML 验证 提交这张票;不要重试。 |
| 10015301 | 409 | 验证还没完成(PENDING_SEFAZ / VALIDATING)。收到 invoice.verify.completed 后再取。 |
| 10015302 | 409 | 当前结论不出 PDF:只有 VALIDATED 与 status 为 Cancelada 的 REJECTED 出 PDF。不要重试。 |
| 10015303 | 409 | 平台缺这张票的 XML 原文。用 XML 验证 原样重新提交这份 XML、不带 forceRevalidate,再取(见本页「XML 原文缺失时」)。 |
| 10015304 | 503 | XML 原文还在归档。按 Retry-After(5 秒)后重试。 |
| 10015305 | 503 | 生成繁忙或暂时不可用。按 Retry-After 后重试;持续几分钟以上请联系平台。 |
| 10001000 | 500 | 平台内部错误。退避重试;持续失败请携带请求的 timestamp 与路径联系平台。 |
