NF-e 验证

能力概述

平台对第三方 NF-e（模型 55）执行两级验证：

另提供独立的 chave 查询：按访问密钥查询发票票面数据，纯查询接口，不含验证结论。

两个端点都需要三个签名请求头，见 认证与签名。响应为裸结构（不带平台信封）；请求级错误为裸 {code, message} 对象。

验证生命周期

提交 XML ──► 一级校验
              ├─ 阻断错误 ─────────────────► REJECTED          （终态）
              └─ 通过 ──► PENDING_SEFAZ ──► VALIDATING（二级）
                                             ├──► VALIDATED       （终态）
                                             ├──► REJECTED        （终态，带 reason）
                                             └──► VALIDATION_ERROR（可重试，带 reason）

对接前提（一次性）

1. 应用凭证：申请应用并领取 app_secret。仅回显一次，请妥善保存；如泄漏可申请轮换。
2. 接口订阅：平台为你的应用开通 POST /openapi/v3/consultas/nf-e/xml 与 GET /openapi/v3/consultas/nf-e/{chave}。
3. webhook 接收地址：通过 注册 Webhook 登记回调 URL，并订阅事件 invoice.verify.completed（二级结论的唯一推送通道）。保存地址时平台会立即发送一条 event_type=webhook.verify 的测试推送，接收端须返回 2xx 才能保存成功（该测试事件直接回 200 即可，无需处理）。

端点

接收最终结论

二级 SEFAZ 核验落定后，平台向已注册的 webhook URL 发起 POST。这是最终结论的唯一推送通道；chave 查询可作轮询兜底。

请求头

载荷

{
  "version": "1.0",
  "event_id": "1950000000000001",
  "event_type": "invoice.verify.completed",
  "occurred_at": "2026-07-23T17:16:23Z",
  "data": {
    "chaveAcesso": "35260764962869000108550990001366171195929648",
    "validationStatus": "VALIDATED",
    "status": "Autorizada",
    "cStat": "100",
    "xMotivo": "Autorizado o uso da NF-e",
    "protocolo": { "numero": "135262955451772", "digestValue": "oAEEuC3tGmb2W7ZJxWkNVWuBHwY=" },
    "dataAutorizacao": "2026-07-23T14:30:09Z",
    "eventos": [],
    "verifiedAt": "2026-07-23T17:16:23Z"
  }
}

信封字段：

data 字段：

注意： webhook 载荷只含语言无关的枚举值，无 *Description 字段。展示文案由接收方自理。

接收端要求

1. 验签：复算 HMAC-SHA256(secret, timestamp + "." + 原始body) 与签名头比对。必须用收到的原始字节，不要先反序列化再重序列化（字段顺序变化会破坏签名）。
2. 10 秒内返回 2xx。 其他情况（含超时）计为投递失败。
3. 失败按 1m / 5m / 30m / 2h / 6h 退避重试 5 次，仍失败进死信队列（可联系平台人工重推）。
4. 按 event_id 幂等去重（重试与多目标扇出共用同一 event_id）。

结论处置

幂等与重验

• XML 验证以 chave 为幂等键：验证进行中重复提交返回当前进度；终态结论 24 小时内复用（不重复消耗核验资源）。
• 强制重验：在 XML 验证 端点加请求头 forceRevalidate: true（不参与签名）。chave 查询为固定 GET 形状，无重验通道；需强制重验请走 XML 端点重新提交。
• 一级阻断的 REJECTED 无二级对象，重验须重新提交 XML。

错误模型

两种错误形状

业务与请求级错误（HTTP 400）为裸对象：

{ "code": 10015004, "message": "查无此票" }

鉴权层错误（HTTP 401 / 403 / 429）由平台网关在请求到达接口前产出，为平台信封形状：

{ "success": false, "errorType": 1, "code": 10009003, "message": "签名错误" }

错误处理须兼容两种形状。稳妥做法：把响应体按 JSON 解析，从任一形状读取 code，以 success=false 或 HTTP >= 400 判定失败。

鉴权与授权错误

重试指引：401 与 403 属配置错误，不修复就重试没有意义，还可能触发限流。429 可重试，用指数退避（初始 1 秒，倍增至 30 秒上限，加抖动）。

请求级与校验错误

详见各端点页：

• XML 验证：请求级错误 10015000 到 10015003（HTTP 400，裸形状，请求未进入校验流程），以及一级校验错误目录 XML_MALFORMED 到 XML_VERSION_UNSUPPORTED（HTTP 200，位于 validation.errors[]）。
• chave 查询：10015104（chave 非法）与 10015004（查无此票），HTTP 400，裸形状。
• 二级结论不是 HTTP 错误，见 结论处置。

HTTP 状态速查

响应语言

message 与 *Description 字段随请求语言返回：Language 头（zh / en / pt / es）优先，其次 Accept-Language（支持 pt-BR 与 q 值）。未提供语言头时默认葡语（pt）。

程序判断一律使用语言无关的枚举字段（validationStatus、status、errors[].code），永远不要匹配描述文案。

联调清单

1. 领取 app_secret；用 sign-helper 与本地签名实现对拍（POST 带 XML body 与 GET 空 body 各一次）。
2. POST /openapi/v3/consultas/nf-e/xml 提交一张真实授权 nfeProc：HTTP 200，五项校验全 true，validationStatus=PENDING_SEFAZ。
3. 接收 invoice.verify.completed webhook：验签通过、按 event_id 去重、拿到 VALIDATED。
4. chave 查询：查已提交过的 chave 得到 200 票面数据；查不存在的 chave 得到 400 + 10015004；校验位错误的 chave 得到 400 + 10015104。
5. 逆向用例：提交内容被篡改的 XML（SIGNATURE_INVALID）；提交无 protNFe 的 XML（仅 warning，照常受理）。
6. 幂等验证：同 chave 重复提交得到复用结论；带 forceRevalidate: true 触发重验，新结论经 webhook 推送。
7. 失败路径：故意用错误 sign 调用确认 401（code 10009003）；调用未订阅端点确认 403（code 10009005）。

排障

1. body 拼接前未去除 CR/LF；
2. GET 请求把 body 拼成了 "null"（应为空字符串）；
3. path 缺 /openapi 前缀，或带上了查询串；
4. sign 用了大写（必须小写十六进制）；
5. 拼接用的 timestamp 与请求头不是同一个字符串（两次生成）；
6. body 字节被重新编码（必须对线上实际发送的字节做哈希，UTF-8）。