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. Es un endpoint de consulta pura y no trae veredicto de verificación.

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; la consulta por chave puede servir 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) y después se aparcan en una cola de mensajes muertos (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).

Tratamiento del veredicto

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 en el endpoint de verificación de XML (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 el endpoint de XML.
• Un REJECTED bloqueante de nivel 1 no tiene registro de nivel 2; la nueva verificación exige reenviar el XML.

Modelo de errores

Dos formas de error

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

{ "code": 10015004, "message": "Invoice not found" }

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; 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).