Verificación de NF-e

Visión general

La plataforma realiza una verificación en dos niveles de NF-e de terceros (modelo 55):

Una consulta por chave independiente devuelve los datos de la factura por clave de acceso. Para una chave que usted envió por la verificación de XML, también devuelve el bloque validation actual y sirve como alternativa de sondeo cuando se pierde una entrega del webhook.

Ambos endpoints requieren las tres cabeceras de firma, vea Autenticación. Las respuestas son objetos simples (sin sobre de la plataforma); los errores de solicitud son un objeto simple {code, message}.

Ciclo de vida de la verificación

envío del XML ──► Nivel 1
                   ├─ error bloqueante ─────────────► REJECTED          (terminal)
                   └─ aprobado ──► PENDING_SEFAZ ──► VALIDATING (Nivel 2)
                                                     ├──► VALIDATED       (terminal)
                                                     ├──► REJECTED        (terminal, con reason)
                                                     └──► VALIDATION_ERROR (reintentable, con reason)

Requisitos previos (una sola vez)

1. Credencial de la aplicación: solicite una aplicación y reciba el app_secret. Se muestra una sola vez; guárdelo de forma segura. Si se filtra, solicite la rotación.
2. Suscripción a la API: la plataforma habilita su aplicación para POST /openapi/v3/consultas/nf-e/xml y GET /openapi/v3/consultas/nf-e/{chave}.
3. Endpoint de webhook: registre la URL de callback en Registrar webhook y suscríbase al evento invoice.verify.completed (el único canal de envío de los veredictos de nivel 2). Al guardar la URL, la plataforma envía de inmediato una entrega de prueba con event_type=webhook.verify; su endpoint debe responder 2xx para que el guardado tenga éxito (responder 200 sin procesar basta para el evento de prueba).

Endpoints

Recepción del veredicto final

Cuando la verificación de nivel 2 en la SEFAZ concluye, la plataforma hace un POST a la URL de webhook registrada. Este es el único canal de envío de los veredictos finales; si se pierde una entrega, la consulta por chave devuelve el validationStatus actual y sirve como alternativa de sondeo.

Cabeceras de la solicitud

Carga

{
  "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"
  }
}

Campos del sobre:

Campos de data:

Nota: las cargas de webhook solo llevan valores enumerados independientes del idioma; aquí no hay campos *Description. El texto de presentación corre a cargo del receptor.

Requisitos del receptor

1. Verifique la firma: recalcule HMAC-SHA256(secret, timestamp + "." + rawBody) y compárelo con la cabecera. Use los bytes recibidos sin procesar; no deserialice y vuelva a serializar antes (reordenar los campos rompe la firma).
2. Responda 2xx en menos de 10 segundos. Cualquier otra cosa, incluidos los timeouts, cuenta como entrega fallida.
3. Las entregas fallidas se reintentan con backoff 1m / 5m / 30m / 2h / 6h (5 intentos); reenvío manual disponible bajo petición.
4. Deduplique por event_id (los reintentos y el fan-out a varios destinos comparten el mismo event_id).
5. Una misma chave puede generar varios eventos con el tiempo: una nueva verificación con forceRevalidate: true, un reenvío pasada la ventana de 24 horas o una comprobación en segundo plano disparada por la consulta por chave terminan, cada uno, en un evento nuevo con su propio event_id. Quédese con el veredicto del evento con el occurred_at más reciente.

Tratamiento del veredicto

Idempotencia y nueva verificación

• La verificación de XML es idempotente por la chave (la clave de acceso dentro del XML enviado):
  • Mientras el nivel 2 está en curso (PENDING_SEFAZ / VALIDATING), reenviar devuelve el progreso actual y no inicia otra comprobación. forceRevalidate: true no reinicia ni acelera una comprobación que ya está en marcha.
  • Un veredicto terminal (VALIDATED / REJECTED / VALIDATION_ERROR) se reutiliza durante 24 horas desde el momento en que se obtuvo: reenviar dentro de esa ventana lo devuelve sin volver a consultar a la SEFAZ. Pasadas 24 horas, un reenvío normal ejecuta de nuevo la verificación completa (nivel 1 + nivel 2).
  • Una respuesta reutilizada refleja el XML enviado originalmente (datos de la factura, comprobaciones de nivel 1, errores y avisos) junto con el validationStatus actual. Si reenvía un XML corregido para la misma chave dentro de la ventana, envíe forceRevalidate: true; de lo contrario recibe el resultado anterior.
• Nueva verificación forzada: envíe la cabecera forceRevalidate: true en el endpoint de verificación de XML (no forma parte de la firma). Omite la reutilización y ejecuta de nuevo el nivel 1 y el nivel 2; el nuevo veredicto llega como un nuevo evento de webhook.
• Consulta por chave: no puede forzar una comprobación. Programa una por su cuenta solo cuando la última respuesta de la SEFAZ tiene más de 24 horas (vea consulta por chave).
• Un REJECTED bloqueante de nivel 1 no tiene registro de nivel 2; para verificar de nuevo, reenvíe el XML (con forceRevalidate: true dentro de la ventana de 24 horas).
• Las verificaciones pertenecen a su cuenta de integrador: la reutilización, la consulta por chave y los webhooks solo ven los envíos de su cuenta. Que otro integrador verifique la misma factura no afecta a la suya; cada cuenta se verifica de forma independiente y recibe su propio veredicto.

Modelo de errores

Dos formas de error

Los errores de negocio y de solicitud (HTTP 400) se devuelven como objeto simple:

{ "code": 10015004, "message": "Factura no encontrada: 35260764962869000108550990001366171195929648" }

Los errores de la capa de autenticación (HTTP 401 / 403 / 429) los produce el gateway de la plataforma antes de que la solicitud llegue a la API, y usan el sobre de la plataforma:

{ "success": false, "errorType": 1, "code": 10009003, "message": "Signature error" }

Su gestor de errores debe aceptar ambas formas. Una regla robusta: interprete el cuerpo como JSON, lea code de cualquiera de las formas y trate success=false o HTTP >= 400 como fallo.

Errores de autenticación y autorización

Guía de reintentos: 401 y 403 son errores de configuración; reintentar sin corregir es inútil y puede disparar el límite de tasa. 429 es reintentable con backoff exponencial (empiece en 1 s, duplique hasta 30 s, añada jitter).

Errores de solicitud y de validación

Documentados en cada página de endpoint:

• Verificación de XML: errores de solicitud 10015000 a 10015003 (HTTP 400, forma simple, la solicitud nunca entra en la validación) y el catálogo de validación de nivel 1 de XML_MALFORMED a XML_VERSION_UNSUPPORTED (HTTP 200, dentro de validation.errors[]).
• Consulta por chave: 10015104 (chave malformada) y 10015004 (factura no encontrada), HTTP 400, forma simple.
• Los resultados de nivel 2 no son errores HTTP; vea Tratamiento del veredicto.

Referencia rápida de estados HTTP

Localización de las respuestas

Los campos message y *Description siguen el idioma de la solicitud: la cabecera Language (en / pt / es / zh) tiene prioridad, después Accept-Language (admite pt-BR y valores q). Sin cabecera de idioma, las respuestas usan portugués (pt) por defecto.

Para las decisiones programáticas use siempre los campos enumerados independientes del idioma (validationStatus, status, errors[].code); nunca compare textos descriptivos.

Lista de comprobación de integración

1. Obtenga el app_secret; contraste su implementación de firma con la salida del asistente de firma (una vez para POST con cuerpo XML, una vez para GET con cuerpo vacío).
2. POST /openapi/v3/consultas/nf-e/xml con un nfeProc autorizado genuino: HTTP 200, las cinco comprobaciones de validación en true, validationStatus=PENDING_SEFAZ.
3. Reciba el webhook invoice.verify.completed: la firma se verifica, deduplicado por event_id, veredicto VALIDATED.
4. Consulta por chave: una chave enviada previamente devuelve 200 con los datos de la factura y el bloque validation (el mismo validationStatus que el veredicto del webhook); una chave inexistente devuelve 400 + 10015004; una chave con dígito verificador incorrecto devuelve 400 + 10015104.
5. Casos negativos: envíe un XML alterado (SIGNATURE_INVALID); envíe un XML sin protNFe (solo aviso, se sigue aceptando).
6. Idempotencia: reenvíe la misma chave y reciba el veredicto reutilizado; envíe con forceRevalidate: true y reciba una nueva verificación con nuevo veredicto vía webhook.
7. Rutas de fallo: llame con un sign incorrecto (401, código 10009003); llame a un endpoint no suscrito (403, código 10009005).

Solución de problemas

1. CR/LF no eliminados del cuerpo antes de la concatenación;
2. una solicitud GET concatenó "null" en lugar de la cadena vacía como cuerpo;
3. path sin el prefijo /openapi, o incluyendo la query string;
4. sign enviado en mayúsculas (debe ser hex en minúsculas);
5. el valor de timestamp usado en la concatenación difiere del de la cabecera (regenerado entre ambos);
6. bytes del cuerpo recodificados (hay que hacer el hash exactamente de los bytes enviados por la red, UTF-8).

1. la factura se autorizó hace instantes y la SEFAZ aún no terminó de propagarla; verifique de nuevo más tarde con forceRevalidate: true;
2. la factura se emitió en el ambiente de homologación de la SEFAZ (ambienteEmissao=Homologacao): el nivel 2 consulta el ambiente de producción, donde las facturas de prueba no existen;
3. la factura nunca se autorizó con esa chave.

Esto es distinto del 10015004 de la consulta por chave, que significa que ninguna fuente de datos de la plataforma conoce la chave.