NF-e 验证
XML 验证
提交 NF-e XML 原文；同步返回一级结论与票面数据，并启动 SEFAZ 核验。
/openapi/v3/consultas/nf-e/xml需要 token、timestamp、sign 三个签名头，参见认证与签名。
提交 NF-e XML 原文，同步返回一级结论与解析出的票面数据；一级通过后自动进入二级 SEFAZ 核验，最终结论经 invoice.verify.completed webhook 推送（见 NF-e 验证）。
HTTP 200 表示请求受理成功，不代表发票通过验证。 XML 格式合法但校验不通过仍返回 200，结论在 validation 块中。请勿以 HTTP 状态码判断验证结果。
参数
请求头
Content-Typestring必填application/xml或text/xml。forceRevalidateboolean可选可选，默认
false。传true时即使已有可复用的终态结论也强制重验。不参与签名。 见下方“幂等与重验”。
响应
请求受理成功。解析出的票面数据加上带一级结论的 validation 块。包含校验不通过的情况：请检查 validation.validationStatus 与 validation.errors。
tipostring单据类型。
取值:NF-eNFC-emodelostring单据模型。
取值:5565statusstringSEFAZ 税务状态。
取值:AutorizadaCanceladaDenegadaInutilizadaNaoEncontradaDesconhecidastatusDescriptionstringstatus的本地化描述，随请求语言（见 NF-e 验证 的“响应语言”）。ambienteEmissaostring单据的发行环境。
取值:ProducaoHomologacaonumerostring发票号 nNF，无前导零。
seriestring系列号。
dataEmissaostring开票时间 dhEmi，ISO-8601 带时区偏移，票面原文（如
2026-07-23T11:20:05-03:00）。chaveAcessostring44 位访问密钥。
emitenteobject开票方。
destinatarioobject收票方。
itensarray商品行。
dataAutorizacaostring | nullSEFAZ 授权时间 dhRecbto（ISO-8601）；提交的 XML 无协议节点时为 null。
protocoloobject | null授权协议；无协议节点时为 null。
valorTotalnumber整单折后净额 vNF，2 位小数。
validationobject一级结论块。仅此端点返回。
错误
| 错误码 | HTTP | |
|---|---|---|
| 10015000 | 400 | 请求体为空。请在 body 中发送 XML。 |
| 10015001 | 400 | 超过 1 MB。真实单张 NF-e 不会超过此限制；检查是否包了一层或二次编码。 |
| 10015002 | 400 | 检测到 DTD（ |
| 10015003 | 400 | 编码非 UTF-8。提交前请转为 UTF-8。 |
请求体与签名
- 推荐提交完整的 nfeProc 授权全文（含
protNFe协议节点）；也接受裸NFe：无协议节点仅产生 warning，照常受理。 - 硬约束：上限 1 MB、仅 UTF-8、禁止 DTD（含
<!DOCTYPE直接拒绝）。 - 签名：body 参与签名前须去除全部 CR 与 LF，而实际发送的请求体保持原样：
sign = md5Hex(app_secret + "/openapi/v3/consultas/nf-e/xml" + 去CRLF后的XML + timestamp)
forceRevalidate 头不参与签名。完整规则见 认证与签名。
金额口径
行级 itens[].valorTotal 是折前毛额（vProd），根级 valorTotal 是折后净额（vNF），两者之差即整单折扣。
一级校验错误
以 HTTP 200 返回，位于 validation.errors[]。这些不是传输错误：请求成功、单据不合格。除 PROTOCOL_MISSING（warning）外均为阻断项（终态 REJECTED）。
| errors[].code | 数字码 | 含义 |
|---|---|---|
XML_MALFORMED | 10015100 | XML 语法非法 |
XSD_INVALID | 10015101 | 不符合 NF-e 4.00 XSD 版式 |
SIGNATURE_INVALID | 10015102 | 数字签名验证失败（内容被篡改，或签名时证书已过期） |
SIGNATURE_CERT_MISMATCH | 10015103 | 签名证书 CNPJ 与开票方不符 |
ACCESS_KEY_INVALID | 10015104 | chave 结构 / 校验位非法 |
ACCESS_KEY_MISMATCH | 10015105 | chave 分段与票面字段不一致 |
PROTOCOL_MISMATCH | 10015106 | 协议块与票内容不自洽 |
PROTOCOL_MISSING | 10015107 | 无协议节点（warning，不阻断） |
XML_VERSION_UNSUPPORTED | 10015108 | 版式版本非 4.00 |
二级结论（webhook）
一级通过后，最终结论只经 invoice.verify.completed webhook 推送；请求头、载荷与接收端要求见 NF-e 验证。这些不是 HTTP 错误。
| validationStatus | 终态？ | 处置 |
|---|---|---|
VALIDATED | 是 | 可放行（发货、结算等） |
REJECTED | 是 | 不可放行；reason 说明 SEFAZ 判定（已取消 / 否决 / 作废 / 查无 / 协议不符） |
VALIDATION_ERROR | 否 | 平台侧核验失败，非发票判定；稍后带 forceRevalidate: true 重新提交 |
幂等与重验
- XML 验证以 chave 为幂等键：验证进行中重复提交返回当前进度；终态结论 24 小时内复用（不重复消耗核验资源）。
- 强制重验：加请求头
forceRevalidate: true（不参与签名）。chave 查询 为固定 GET 形状，无重验通道；需强制重验请通过本端点重新提交。 - 一级阻断的
REJECTED无二级对象，重验须重新提交 XML。