NF-e 验证
XML 验证
提交 NF-e XML 原文；同步返回一级结论与票面数据，并启动 SEFAZ 核验。
/openapi/v3/consultas/nf-e/xmltoken、timestamp、sign 三个签名头，参见认证与签名。提交 NF-e XML 原文，同步返回一级结论与解析出的票面数据；一级通过后自动进入二级 SEFAZ 核验，最终结论经 invoice.verify.completed webhook 推送（见 NF-e 验证）。
HTTP 200 表示请求受理成功，不代表发票通过验证。 XML 格式合法但校验不通过仍返回 200，结论在 validation 块中。请勿以 HTTP 状态码判断验证结果。
请求头
Content-Type* | string | 请求体类型 |
forceRevalidate | bool | 强制重验 |
* 必填字段
validation 块。包含校验不通过的情况：请检查 validation.validationStatus 与 validation.errors。tipo | string | 单据类型 |
modelo | string | 单据模型码 |
status | string | 税务状态 |
statusDescription | string | 状态说明 |
ambienteEmissao | string | 开票环境 |
numero | string | 发票号 |
serie | string | 系列号 |
dataEmissao | string | 开具时刻 |
tipoOperacao | string | 操作类型（tpNF），从开票方看货物的方向 |
chaveAcesso | string | 访问密钥 |
| object | 开票方 |
| object | 收票方 |
| array | 商品行 |
dataAutorizacao | string | 授权时刻 |
| object | 授权协议 |
valorTotal | number | 整单净额 |
| object | 一级校验结论 |
- 推荐提交 SEFAZ 授权后的完整文件，带授权协议；只有发票、没有授权协议的文件也接受，产生一条
PROTOCOL_MISSING提示，照常受理。 - 硬约束：上限 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 是折前毛额，根级 valorTotal 是折后净额，两者之差即整单折扣。
金额与数量是 JSON 数值，取票面原值并去掉尾随零：100.00 返回 100，94.90 返回 94.9，展示时请自行格式化。票面没有值的字段直接省略，不会返回 null。
一级结论即时判定并在本响应返回；二级是向 SEFAZ 的核验，只经 Webhook 推送。validationStatus 与 errors[].code 的取值见页底枚举。
一级不通过的同步响应
HTTP 200，validationStatus = REJECTED，errors 至少一项。这是终态：没有二级，重验须重新提交 XML（24 小时窗口内需带 forceRevalidate: true）。
"validation": {"fileAccessible": true,"xmlWellFormed": true,"schemaValid": true,"signatureValid": false,"accessKeyValid": true,"protocolPresent": true,"protocolValid": true,"xmlVersion": "4.00","validationStatus": "REJECTED","validationStatusDescription": "Verification failed","errors": [ { "code": "SIGNATURE_INVALID", "field": "Signature", "message": "Digital signature verification failed: ..." } ],"warnings": []}
- XML 验证以 chave 为幂等键：二级进行中重复提交返回当前进度，不会再发起一次核验；带
forceRevalidate: true也不会让它重新开始或提前完成。 - 终态结论自得出之时起 24 小时内复用，
VALIDATION_ERROR同样复用；超过 24 小时后，普通的重复提交会重新完整验证。 - 复用的响应反映当初提交的那份 XML，
validationStatus为当前值；窗口内验证同一 chave 修正后的 XML，请带forceRevalidate: true。 - 强制重验：加请求头
forceRevalidate: true，新结论作为一条新事件经 webhook 推送。chave 查询 不能强制复核。 - 一级阻断的
REJECTED无二级对象，重验须重新提交 XML。 - 验证记录归属于你的集成商账户：其他集成商验证同一张票互不影响，各自出结论。
Content-Type请求体类型（请求头）
| 取值 | 含义 |
|---|---|
| application/xml | XML 请求体 |
| text/xml | XML 请求体，等价 |
forceRevalidate强制重验（请求头）
不传即 false。
| 取值 | 含义 |
|---|---|
| true | 从头重新验证，忽略可复用的终态结论 |
| false | 有 24 小时内的终态结论则复用 |
tipo单据类型
| 取值 | 含义 |
|---|---|
| NF-e | 电子发票，用于企业间交易与发货销售 |
| NFC-e | 消费者电子发票，用于现场零售 |
modelo单据模型码
| 取值 | 含义 |
|---|---|
| 55 | NF-e |
| 65 | NFC-e |
status税务状态
| 取值 | 含义 |
|---|---|
| Autorizada | SEFAZ 已授权且没有取消事件 |
| Cancelada | 已取消，含替代性取消 |
| Denegada | SEFAZ 否决 |
| Inutilizada | 号码已作废 |
| NaoEncontrada | SEFAZ 查无此票，可能是同步延迟 |
| Desconhecida | 无法从 SEFAZ 应答判定 |
ambienteEmissao开票环境
| 取值 | 含义 |
|---|---|
| Producao | 正式环境 |
| Homologacao | 税务局测试环境，票无法律效力 |
tipoOperacao操作类型
| 取值 | 含义 |
|---|---|
| Saida | 货物从开票方发出（tpNF=1），如销售发货 |
| Entrada | 货物进入开票方（tpNF=0），如消费者退货、进口 |
validation.validationStatus验证状态
首次同步响应只会是 PENDING_SEFAZ 或 REJECTED；其余经 invoice.verify.completed webhook 推送，也会出现在复用响应与 chave 查询中。
| 取值 | 含义 |
|---|---|
| PENDING_SEFAZ | 一级通过，排队等待 SEFAZ 核验 |
| REJECTED | 不通过，终态。一级因阻断错误，二级因 SEFAZ 状态（已取消、否决、作废、查无、协议不符）；不可放行 |
| VALIDATING | 二级进行中，正在向 SEFAZ 查询 |
| VALIDATED | SEFAZ 确认真实且状态正常；终态，可放行 |
| VALIDATION_ERROR | 平台侧技术失败，不是对发票的判定；与其他结论一样 24 小时内复用，稍后带 forceRevalidate: true 重新提交 |
validation.errors[].code一级问题码
除 PROTOCOL_MISSING 进 warnings[] 外都是阻断项，直接 REJECTED。括号里是对应的数字码。
| 取值 | 含义 |
|---|---|
| XML_MALFORMED | XML 语法非法（10015100） |
| XSD_INVALID | 不符合 NF-e 4.00 官方版式（10015101） |
| SIGNATURE_INVALID | 数字签名无效：内容被改或签名时证书已过期（10015102） |
| SIGNATURE_CERT_MISMATCH | 签名证书 CNPJ 与开票方不符（10015103） |
| ACCESS_KEY_INVALID | 访问密钥结构或校验位非法（10015104） |
| ACCESS_KEY_MISMATCH | 访问密钥分段与票面字段不一致（10015105） |
| PROTOCOL_MISMATCH | 授权协议与票面不自洽（10015106） |
| PROTOCOL_MISSING | 无授权协议；提示，不阻断（10015107） |
| XML_VERSION_UNSUPPORTED | 版式版本非 4.00（10015108） |
| 错误码 | HTTP | |
|---|---|---|
| 10015000 | 400 | 请求体为空。请在 body 中发送 XML。 |
| 10015001 | 400 | 超过 1 MB。检查是否包了一层或二次编码。 |
| 10015002 | 400 | 检测到 DTD（<!DOCTYPE）。请去除 DTD。 |
| 10015003 | 400 | 编码非 UTF-8。提交前请转为 UTF-8。 |