TF Fiscal
Documentación

Verificación de NF-e

Verificación de XML

Envía el XML de la NF-e; devuelve el veredicto de nivel 1 y los datos de la factura e inicia la verificación en la SEFAZ.

POST/openapi/v3/consultas/nf-e/xml

Requiere las cabeceras de firma token, timestamp y sign, vea Autenticación.

Envía el XML sin procesar de la NF-e. Devuelve de forma síncrona el veredicto de nivel 1 y los datos de la factura ya interpretados; si el nivel 1 se aprueba, la verificación de nivel 2 en la SEFAZ empieza automáticamente y el veredicto final llega por el webhook invoice.verify.completed (vea Verificación de NF-e).

HTTP 200 significa que la solicitud fue aceptada, no que la factura fue aprobada. Un XML bien formado que no supera la validación también devuelve 200; el veredicto está en el bloque validation. Nunca decida la validez por el estado HTTP.

Parámetros

Cabeceras

  • Content-Typestringobligatorio

    application/xml o text/xml.

  • forceRevalidatebooleanopcional

    Opcional, por defecto false. Envíe true para forzar una nueva verificación aunque exista un veredicto terminal reutilizable. No participa en la firma. Vea Idempotencia y nueva verificación más abajo.

Respuestas

200

Solicitud aceptada. Datos de la factura interpretados más el bloque validation con el veredicto de nivel 1. Incluye los casos en que la validación falló: compruebe validation.validationStatus y validation.errors.

  • tipostring

    Tipo de documento.

    Valores:NF-eNFC-e
  • modelostring

    Modelo del documento.

    Valores:5565
  • statusstring

    Estado fiscal en la SEFAZ.

    Valores:AutorizadaCanceladaDenegadaInutilizadaNaoEncontradaDesconhecida
  • statusDescriptionstring

    Descripción localizada de status, según el idioma de la solicitud (vea Localización de las respuestas en Verificación de NF-e).

  • ambienteEmissaostring

    Entorno en el que se emitió el documento.

    Valores:ProducaoHomologacao
  • numerostring

    Número de la factura nNF, sin ceros a la izquierda.

  • seriestring

    Número de serie.

  • dataEmissaostring

    Fecha y hora de emisión dhEmi, ISO-8601 con desplazamiento UTC, tal como figura en el documento (p. ej. 2026-07-23T11:20:05-03:00).

  • chaveAcessostring

    Clave de acceso de 44 dígitos.

  • emitenteobject

    Emisor.

  • destinatarioobject

    Destinatario.

  • itensarray

    Líneas de la factura.

  • dataAutorizacaostring | null

    Fecha y hora de autorización en la SEFAZ dhRecbto (ISO-8601); null cuando el XML enviado no trae nodo de protocolo.

  • protocoloobject | null

    Protocolo de autorización; null cuando no hay nodo de protocolo.

  • valorTotalnumber

    Total neto de la factura vNF (tras descuentos), 2 decimales.

  • validationobject

    Bloque del veredicto de nivel 1. Solo está presente en este endpoint.

Errores

CódigoHTTP
10015000400

Cuerpo de la solicitud vacío. Envíe el XML en el cuerpo.

10015001400

El cuerpo supera 1 MB. Una NF-e auténtica nunca supera este límite; compruebe que no la está envolviendo ni codificando dos veces.

10015002400

DTD detectado (<!DOCTYPE). Elimine los DTD; se rechazan como protección contra XXE.

10015003400

La codificación no es UTF-8. Convierta a UTF-8 antes de enviar.

Cuerpo de la solicitud y firma

  • Preferible: el documento autorizado nfeProc completo (incluido el nodo de protocolo protNFe). Una NFe sin el nodo de protocolo también se acepta: genera un aviso, pero se procesa con normalidad.
  • Límites estrictos: máximo 1 MB, solo UTF-8, DTD prohibido (cualquier <!DOCTYPE se rechaza de inmediato).
  • Firma: el cuerpo participa en la firma tras eliminar todos los CR y LF, mientras que el cuerpo enviado permanece sin cambios:
text
sign = md5Hex(app_secret + "/openapi/v3/consultas/nf-e/xml" + xmlSinCrLf + timestamp)

La cabecera forceRevalidate no participa en la firma. Reglas completas en Autenticación.

Semántica de los importes

El itens[].valorTotal de cada línea es el importe bruto de la línea (vProd, antes del descuento); el valorTotal de la raíz es el total neto de la factura (vNF, tras el descuento). La diferencia es el descuento total.

Errores de validación de nivel 1

Se devuelven con HTTP 200 dentro de validation.errors[]. No son errores de transporte: la solicitud tuvo éxito, el documento no pasó. Todos son bloqueantes (REJECTED terminal) salvo PROTOCOL_MISSING, que es un aviso.

errors[].codeCódigo numéricoSignificado
XML_MALFORMED10015100Sintaxis XML inválida
XSD_INVALID10015101No conforme al layout XSD de la NF-e 4.00
SIGNATURE_INVALID10015102Falló la verificación de la firma digital (contenido alterado o certificado caducado en el momento de firmar)
SIGNATURE_CERT_MISMATCH10015103El CNPJ del certificado de firma no coincide con el emisor
ACCESS_KEY_INVALID10015104Estructura o dígito verificador de la chave inválidos
ACCESS_KEY_MISMATCH10015105Los segmentos de la chave no coinciden con los campos del documento
PROTOCOL_MISMATCH10015106Bloque de protocolo incoherente con el documento
PROTOCOL_MISSING10015107Sin nodo de protocolo (aviso, no bloqueante)
XML_VERSION_UNSUPPORTED10015108La versión del layout no es 4.00

Resultados de nivel 2 (webhook)

Una vez aprobado el nivel 1, el veredicto final llega solo por el webhook invoice.verify.completed; cabeceras, carga y requisitos del receptor están en Verificación de NF-e. No son errores HTTP.

validationStatus¿Terminal?Acción
VALIDATEDSíSeguro continuar (liberar mercancía, liquidar, etc.)
REJECTEDSíNo continuar; reason explica el veredicto de la SEFAZ (cancelada / denegada / inutilizada / no encontrada / protocolo divergente)
VALIDATION_ERRORNoFallo de verificación del lado de la plataforma, no es un juicio sobre la factura; reenvíe más tarde con forceRevalidate: true

Idempotencia y nueva verificación

  • La verificación de XML es idempotente por la chave: reenviar mientras una verificación está en curso devuelve el progreso actual; los veredictos terminales se reutilizan durante 24 horas (sin coste de verificación duplicado).
  • Nueva verificación forzada: envíe la cabecera forceRevalidate: true (no forma parte de la firma). La consulta por chave tiene forma GET fija y no dispone de canal de nueva verificación; para forzar una nueva comprobación, reenvíe por este endpoint.
  • Un REJECTED bloqueante de nivel 1 no tiene registro de nivel 2; la nueva verificación exige reenviar el XML.
AnteriorVerificación de NF-eSiguienteConsulta por chave