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:修正后的 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也不会让它重新开始或提前完成。 - 内容变了自动重验:同一 chave 再次提交的 XML 与上一次不是同一份(逐字节比对)时,不复用,直接完整重新验证(一级 + 二级),无需带
forceRevalidate。已取消 / 已否决 / 已作废的票除外:结论不会变,内容不同也直接返回上一次的结果。上一条与下表只适用于内容相同的重复提交。 - 终态结论按下表复用:复用时直接返回已有结论,不再访问 SEFAZ,也不推送新事件。
| 已有结论 | 普通的重复提交 | 带 forceRevalidate: true |
|---|---|---|
已取消 / 已否决 / 已作废(REJECTED 且 status 为 Cancelada / Denegada / Inutilizada) | 平台保留该验证记录期间一直复用 | 仍然复用:这几种状态不会再变 |
SEFAZ 不受理查询(VALIDATION_ERROR 且 status 为 Desconhecida,如 cStat 526) | 平台保留该验证记录期间一直复用 | 重新完整验证(一级 + 二级) |
其他结论(VALIDATED、其余 REJECTED 与 VALIDATION_ERROR) | 自得出之时起 24 小时内复用,之后重新完整验证 | 重新完整验证(一级 + 二级) |
- 验证记录过了平台保留期后,再次提交按首次提交处理。
- 复用的响应反映当初提交的那份 XML,
validationStatus为当前值;为同一 chave 提交修正后的 XML 会自动重新验证(已取消 / 已否决 / 已作废的票除外,结论不会变)。 - 强制重验:加请求头
forceRevalidate: true,按上表跳过复用,新结论作为一条新事件经 webhook 推送。chave 查询 不能强制复核,上表前两类也不会自动复核。 - 一级阻断的
REJECTED无二级对象,重验须重新提交 XML:修正后的 XML 会自动重验;原样重新提交在 24 小时内需带forceRevalidate: true。 - 验证记录归属于你的集成商账户:其他集成商验证同一张票互不影响,各自出结论。
Content-Type请求体类型(请求头)
| 取值 | 含义 |
|---|---|
| application/xml | XML 请求体 |
| text/xml | XML 请求体,等价 |
forceRevalidate强制重验(请求头)
不传即 false。
| 取值 | 含义 |
|---|---|
| true | 跳过复用,从头重新验证;已取消、已否决、已作废的结论仍然复用 |
| false | 有可复用的终态结论则直接返回:已取消、已否决、已作废与 SEFAZ 不受理查询的结论在平台保留记录期间一直复用,其他结论 24 小时内复用 |
tipo单据类型
| 取值 | 含义 |
|---|---|
| NF-e | 电子发票,用于企业间交易与发货销售 |
| NFC-e | 消费者电子发票,用于现场零售 |
modelo单据模型码
| 取值 | 含义 |
|---|---|
| 55 | NF-e |
| 65 | NFC-e |
status税务状态
| 取值 | 含义 |
|---|---|
| Autorizada | SEFAZ 已授权且没有取消事件 |
| Cancelada | 已取消,含替代性取消 |
| Denegada | SEFAZ 否决 |
| Inutilizada | 号码已作废 |
| NaoEncontrada | SEFAZ 查无此票,可能是同步延迟 |
| Desconhecida | 无法从 SEFAZ 应答判定;SEFAZ 不受理该票的查询(如 cStat 526)时也是此值 |
ambienteEmissao开票环境
| 取值 | 含义 |
|---|---|
| Producao | 正式环境 |
| Homologacao | 税务局测试环境,票无法律效力 |
tipoOperacao操作类型
| 取值 | 含义 |
|---|---|
| Saida | 货物从开票方发出(tpNF=1),如销售发货 |
| Entrada | 货物进入开票方(tpNF=0),如消费者退货、进口 |
emitente.endereco.uf / destinatario.endereco.uf州二字码
按票面原样返回。
| 取值 | 含义 |
|---|---|
| AC | Acre |
| AL | Alagoas |
| AP | Amapá |
| AM | Amazonas |
| BA | Bahia |
| CE | Ceará |
| DF | Distrito Federal |
| ES | Espírito Santo |
| GO | Goiás |
| MA | Maranhão |
| MT | Mato Grosso |
| MS | Mato Grosso do Sul |
| MG | Minas Gerais |
| PA | Pará |
| PB | Paraíba |
| PR | Paraná |
| PE | Pernambuco |
| PI | Piauí |
| RJ | Rio de Janeiro |
| RN | Rio Grande do Norte |
| RS | Rio Grande do Sul |
| RO | Rondônia |
| RR | Roraima |
| SC | Santa Catarina |
| SP | São Paulo |
| SE | Sergipe |
| TO | Tocantins |
| EX | 境外;只出现在收票方 |
itens[].cfop商品行业务代码
4 位数字,按票面原样返回。第一位表示方向与范围;完整码表是 1970 年无编号 Convênio 的 CFOP 表,见 NF-e 门户。
| 取值 | 含义 |
|---|---|
| 1xxx | 本州内进项 |
| 2xxx | 跨州进项 |
| 3xxx | 境外进项 |
| 5xxx | 本州内出项 |
| 6xxx | 跨州出项 |
| 7xxx | 出口 |
validation.validationStatus验证状态
首次同步响应只会是 PENDING_SEFAZ 或 REJECTED;其余经 invoice.verify.completed webhook 推送,也会出现在复用响应与 chave 查询中。
| 取值 | 含义 |
|---|---|
| PENDING_SEFAZ | 一级通过,排队等待 SEFAZ 核验 |
| REJECTED | 不通过,终态。一级因阻断错误,二级因 SEFAZ 状态(已取消、否决、作废、查无、协议不符);不可放行 |
| VALIDATING | 二级进行中,正在向 SEFAZ 查询 |
| VALIDATED | SEFAZ 确认真实且状态正常;终态,可放行 |
| VALIDATION_ERROR | 验证未能完成,终态,不是对发票的判定。分两类:SEFAZ 限流、查询重试耗尽或长时间不可用,24 小时内复用,可稍后带 forceRevalidate: true 重新提交;SEFAZ 不受理该票的查询(如 cStat 526),status 为 Desconhecida,在平台保留验证记录期间一直复用,重复提交不会改变结论 |
validation.errors[].code / validation.warnings[].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) |
validation.xmlVersion版式版本
其他版本以 XML_VERSION_UNSUPPORTED 判不通过。
| 取值 | 含义 |
|---|---|
| 4.00 | 现行 NF-e 与 NFC-e 版式 |
| 错误码 | HTTP | |
|---|---|---|
| 10015000 | 400 | 请求体为空。请在 body 中发送 XML。 |
| 10015001 | 400 | 超过 1 MB。检查是否包了一层或二次编码。 |
| 10015002 | 400 | 检测到 DTD(<!DOCTYPE)。请去除 DTD。 |
| 10015003 | 400 | 编码非 UTF-8。提交前请转为 UTF-8。 |
