TF Fiscal
Documentación

Verificación de NF-e

Verificación en dos niveles de NF-e de terceros: verificación de XML, consulta por chave, veredicto final entregado por webhook, obtención del DANFE (PDF) por chave, idempotencia y modelo de errores.

Visión general

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

NivelQué haceCuándo
Nivel 1 (síncrono)Validación local del XML: sintaxis, layout XSD de la NF-e 4.00, firma digital y titularidad del certificado, estructura de la clave de acceso (chave) de 44 dígitos y coherencia con los campos del documento, integridad del protocolo de autorizaciónSe devuelve de inmediato en la respuesta de la API
Nivel 2 (asíncrono)Comprobación de autenticidad en tiempo real contra la SEFAZ (la autoridad fiscal estatal): estado de autorización, eventos de cancelación, número de protocolo y digest comparados con los registros oficialesSe ejecuta tras aprobar el nivel 1; el veredicto se entrega por webhook (vea Recepción del veredicto final), y la consulta por chave devuelve el estado actual como alternativa de sondeo

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.

Para las facturas aprobadas en la verificación (o canceladas), la obtención del DANFE devuelve el PDF directamente por chave.

Los tres endpoints requieren las tres cabeceras de firma, vea Autenticación. Las llamadas tienen límite de tasa por aplicación y por grupo de endpoints (la verificación de XML y la consulta por chave pertenecen al grupo "verificación de facturas"; la obtención del DANFE tiene su propio grupo, "obtención de DANFE", así que obtener PDF no consume la cuota del primero); las reglas y cabeceras están en Límite de tasa y backoff. Las respuestas son objetos simples (sin sobre de la plataforma; la obtención del DANFE devuelve el propio archivo PDF); los errores de solicitud son un objeto simple {code, message}.

Ciclo de vida de la verificación

text
envío del XML ──► Nivel 1
├─ error bloqueante ─────────────► REJECTED (terminal)
└─ aprobado ──► PENDING_SEFAZ ──► VALIDATING (Nivel 2)
├──► VALIDATED (terminal)
├──► REJECTED (terminal, con reason)
└──► VALIDATION_ERROR (terminal, con reason)
validationStatusSignificado
VALIDATEDLa SEFAZ confirma que la factura es auténtica y válida (autorizada, sin cancelación, protocolo coincide)
REJECTEDVerificación fallida: error bloqueante de nivel 1, o la SEFAZ informa de que la factura está cancelada / denegada / inutilizada / no encontrada / con protocolo divergente. Se informa reason
VALIDATION_ERRORLa verificación no pudo completarse. No es un juicio sobre la factura en sí; se informa reason. Dos tipos: (1) limitación de la SEFAZ, fallos de consulta tras los reintentos o SEFAZ no disponible durante mucho tiempo: reenvíe más tarde con forceRevalidate: true; (2) la SEFAZ no acepta consultas de esta factura (por ejemplo, cStat 526, emitida hace demasiado tiempo): status es Desconhecida y reenviar no cambiará el veredicto (vea Solución de problemas)

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}; para obtener PDF, habilita además GET /openapi/v3/consultas/danfe/{chave} (un alcance aparte, que no viene incluido en la consulta por 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

EndpointFinalidad
POST /openapi/v3/consultas/nf-e/xmlEnvía el XML sin procesar de la NF-e; devuelve el veredicto de nivel 1 y la factura interpretada, inicia el nivel 2
GET /openapi/v3/consultas/nf-e/{chave}Consulta por clave de acceso; devuelve los datos de la factura y, para las chaves que usted envió, el bloque validation actual
GET /openapi/v3/consultas/danfe/{chave}Obtiene el DANFE por clave de acceso; devuelve el PDF de una factura verificada por su cuenta (alcance habilitado por separado)

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

CabeceraDescripción
X-Tffiscal-Eventinvoice.verify.completed
X-Tffiscal-Event-IdId del evento, la clave de idempotencia: no cambia entre reintentos; deduplique por ella
X-Tffiscal-Delivery-IdId de la entrega, uno por URL de destino; no cambia entre los reintentos a ese destino (deduplique por el id del evento, no por este)
X-Tffiscal-TimestampSegundos Unix, regenerado en cada intento
X-Tffiscal-Signaturehex( HMAC-SHA256( secret, timestamp + "." + body ) ), en minúsculas; secret = su app_secret para una URL de webhook a nivel de aplicación (una URL de respaldo a nivel de tenant se firma con el secret configurado para ella)

Carga

json
{
"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 cuando la SEFAZ no acepta consultas de la factura (por ejemplo, cStat 526):

json
{
"chaveAcesso": "31241064962869000108550990001366171195929642",
"validationStatus": "VALIDATION_ERROR",
"status": "Desconhecida",
"cStat": "526",
"xMotivo": "Rejeição: Consulta a uma Chave de Acesso muito antiga",
"protocolo": null,
"dataAutorizacao": null,
"eventos": [],
"verifiedAt": "2026-07-23T17:16:23Z",
"reason": "SEFAZ does not answer this chave (cStat=526: Rejeicao: Consulta a uma Chave de Acesso muito antiga), not retryable"
}

Campos del sobre:

CampoTipoPresenciaDescripción
versionstringsiempreVersión del esquema de la carga, actualmente 1.0
event_idstringsiempreId del evento, la clave de idempotencia; idéntico entre reintentos
event_typestringsiempreinvoice.verify.completed
occurred_atstringsiempreHora del evento, ISO-8601 UTC
dataobjectsiempreCuerpo del veredicto, más abajo

Campos de data:

CampoTipoPresenciaDescripción
chaveAcessostringsiempreClave de acceso de 44 dígitos de la factura verificada; clave de unión con su envío
validationStatusstringsiempreVeredicto final: VALIDATED / REJECTED / VALIDATION_ERROR (vea Ciclo de vida de la verificación)
statusstring | nullanulableEstado fiscal en la SEFAZ: Autorizada / Cancelada / Denegada / Inutilizada / NaoEncontrada / Desconhecida; null en VALIDATION_ERROR (no se obtuvo veredicto de la SEFAZ), salvo Desconhecida cuando la SEFAZ no acepta consultas de la factura (vea el ejemplo anterior)
cStatstring | nullanulableCódigo de retorno bruto de la SEFAZ (p. ej. 100 = autorizada, 101 = cancelada); null cuando no se alcanzó la SEFAZ
xMotivostring | nullanulableMensaje de retorno bruto de la SEFAZ (portugués, literal)
protocoloobject | nullanulableObjeto Protocol (numero, digestValue), como en la respuesta de la verificación de XML; del registro oficial
dataAutorizacaostring | nullanulableHora de autorización en la SEFAZ, ISO-8601 UTC
eventos[]arraysiempre (puede estar vacío)Eventos fiscales registrados contra la factura (cancelación, cartas de corrección); vacío cuando no hay
verifiedAtstringsiempreCuándo se completó la verificación de nivel 2, ISO-8601 UTC
reasonstringsolo en falloPresente solo para REJECTED / VALIDATION_ERROR; texto estable en inglés que explica el veredicto, pensado para diagnóstico y registro; para decidir en el código use validationStatus / status. Cuando la SEFAZ no acepta consultas, dice SEFAZ does not answer this chave (cStat=…: …), not retryable (xMotivo sin tildes)

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 con contenido XML distinto, un reenvío pasado el periodo de reutilización o una comprobación en segundo plano disparada por la consulta por chave (vea Idempotencia y nueva verificación) 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. Reutilizar un veredicto existente no genera un evento nuevo.

Tratamiento del veredicto

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_ERROR (status null)Sí, reintentableFallo de verificación del lado de la plataforma, no es un juicio sobre la factura. Como cualquier veredicto, se reutiliza durante 24 horas; reenvíe más tarde con forceRevalidate: true
VALIDATION_ERROR (status Desconhecida)Sí, reintentar no lo cambiaráLa SEFAZ no acepta consultas de esta factura (por ejemplo, cStat 526, emitida hace demasiado tiempo). No es un juicio sobre la factura; no significa que la factura sea falsa. El veredicto se reutiliza; no hace falta reintentar. Confírmelo por otros medios si es necesario

Idempotencia y nueva verificación

  • La verificación de XML es idempotente por la chave (la clave de acceso dentro del XML enviado), y la reutilización solo aplica a reenvíos con contenido idéntico:
    • Si el contenido cambia, se verifica de nuevo automáticamente: si el XML que envía para una chave no es el mismo que el anterior (comparado byte a byte, aunque difiera en un solo carácter), no se reutiliza nada y se ejecutan de nuevo el nivel 1 y el nivel 2 completos; no hace falta forceRevalidate. La excepción son las facturas canceladas / denegadas / inutilizadas: su veredicto no cambia, así que se devuelve el resultado anterior aunque el contenido sea distinto. Los puntos siguientes solo aplican a reenvíos con contenido idéntico.

    • 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.

    • Los veredictos terminales se reutilizan según la tabla siguiente. Un veredicto reutilizado se devuelve tal cual, sin consultar a la SEFAZ y sin un evento de webhook nuevo:

      Veredicto existenteReenvío normalCon forceRevalidate: true
      Cancelada / denegada / inutilizada (REJECTED con status Cancelada / Denegada / Inutilizada)Se reutiliza mientras la plataforma conserve el registro de la verificaciónSe sigue reutilizando: estas situaciones ya no cambian
      La SEFAZ no acepta consultas (VALIDATION_ERROR con status Desconhecida, por ejemplo cStat 526)Se reutiliza mientras la plataforma conserve el registro de la verificaciónNueva verificación completa (nivel 1 + nivel 2)
      Cualquier otro veredicto (VALIDATED, los demás REJECTED y VALIDATION_ERROR)Se reutiliza durante 24 horas desde el momento en que se obtuvo; después, nueva verificación completaNueva verificación completa (nivel 1 + nivel 2)
    • Cuando la plataforma ya no conserva el registro de la verificación, un nuevo envío se trata como un primer envío.

    • Una respuesta reutilizada refleja el XML enviado originalmente (datos de la factura, comprobaciones de nivel 1, errores y avisos) junto con el validationStatus actual. Un XML corregido para la misma chave se verifica de nuevo automáticamente, por lo que no recibirá el resultado anterior (salvo las facturas canceladas / denegadas / inutilizadas, cuyo veredicto no cambia).

  • Nueva verificación forzada: envíe la cabecera forceRevalidate: true en el endpoint de verificación de XML (no forma parte de la firma). Según la tabla anterior, 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, y nunca para las dos primeras filas de la tabla (vea consulta por chave).
  • Un REJECTED bloqueante de nivel 1 no tiene registro de nivel 2; para verificar de nuevo, reenvíe el XML: un XML corregido se verifica de nuevo automáticamente; reenviar el mismo XML dentro de la ventana de 24 horas requiere forceRevalidate: true.
  • 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 se devuelven como objeto simple (HTTP 400 en la verificación de XML y en la consulta por chave; la obtención del DANFE también usa 404 / 409 / 500 / 503, vea Obtención del DANFE):

json
{ "code": 10015004, "message": "Factura no encontrada: 35260764962869000108550990001366171195929648" }
CampoTipoDescripción
codeintegerCódigo de error de la plataforma
messagestringExplicación legible, localizada (vea Localización de las respuestas)

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:

json
{ "success": false, "errorType": 1, "code": 10009003, "message": "Signature error" }
CampoTipoDescripción
successbooleanfalse en todo error
errorTypeintegerClase del error: 1 error de API, 2 rechazo de la SEFAZ, 3 fallo del sistema, 4 fallo de validación de campos
codeintegerCódigo de error de la plataforma
messagestringExplicación legible, localizada
dataobject | nullNo se rellena en los errores

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

HTTPcodeSignificadoAcción
40110009000Faltan cabeceras de firma (token / sign / timestamp)Corrija el cliente: envíe las tres cabeceras en cada solicitud
40110009001Timestamp inválido o desfase de reloj superior a ±300 sSincronice el reloj (NTP); genere el timestamp en cada solicitud, nunca lo reutilice
40110009002Token inválidoCompruebe el app_secret; si se rotó, actualice la configuración
40110009003Firma no coincideRecalcule la firma; vea la lista en Solución de problemas
40310009004Aplicación desactivadaContacte con la plataforma
40310009015Aplicación no vigente (pendiente de aprobación o rechazada)Espere la aprobación / contacte con la plataforma
40310009014Cuenta del integrador desactivadaContacte con la plataforma
40310009005API no suscritaSolicite la suscripción al endpoint llamado
42910009006Límite de tasa superado, o la aplicación está en bloqueo temporalEspere el Retry-After y reintente; suavice la tasa de llamadas. Reglas y cabeceras: Límite de tasa y backoff
41310009027El cuerpo de la solicitud supera el límite de tamaño del gatewayLa verificación de XML acepta como máximo 1 MB; envíe una sola NF-e por solicitud

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: espere primero el Retry-After y, si sigue rechazado, retroceda exponencialmente (empiece en 1 s, duplique hasta 30 s, añada jitter); ignorar el 429 y reenviar sin parar lleva a un bloqueo temporal (vea Bloqueo temporal).

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.
  • Obtención del DANFE: 10015104 (chave malformada, 400), 10015300 (su cuenta no tiene registro de verificación de la factura, 404), 10015301 a 10015303 (verificación no terminada / el veredicto no genera PDF / falta el XML original, 409), 10015304 y 10015305 (XML original aún en archivo / generación ocupada, 503 con Retry-After), 10001000 (error interno de la plataforma, 500), forma simple; los errores llegan en JSON aunque la solicitud lleve Accept: application/pdf.
  • Los resultados de nivel 2 no son errores HTTP; vea Tratamiento del veredicto.

Referencia rápida de estados HTTP

HTTPEscenarioForma del cuerpo
200Solicitud aceptada, incluida la validación fallida (compruebe el bloque validation); la obtención del DANFE devuelve el archivo PDFDatos simples; application/pdf en la obtención del DANFE
400La propia solicitud es inválida (vacía / demasiado grande / DTD / codificación / chave malformada / no encontrada){code, message} simple
404Obtención del DANFE: su cuenta no tiene registro de verificación de la factura{code, message} simple
409Obtención del DANFE: verificación no terminada / el veredicto no genera PDF / falta el XML original{code, message} simple
503Obtención del DANFE: XML original aún en archivo / generación ocupada (lleva Retry-After){code, message} simple
401Fallo de autenticación (token / sign / timestamp)Sobre de la plataforma
413Cuerpo por encima del límite de tamaño del gatewaySobre de la plataforma
403Aplicación desactivada / no vigente / integrador desactivado / no suscritaSobre de la plataforma
429Límite de tasa superado o aplicación en bloqueo temporal (lleva Retry-After y X-RateLimit-*, vea Límite de tasa y backoff)Sobre de la plataforma
Otros 5xxFallo del lado de la plataformaReintente con backoff; si persiste, contacte con la plataforma con el timestamp y la ruta de la solicitud fallida

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; envíe una factura cancelada con forceRevalidate: true y reciba el veredicto original.
  7. Rutas de fallo: llame con un sign incorrecto (401, código 10009003); llame a un endpoint no suscrito (403, código 10009005).
  8. DANFE (requiere su alcance): obtenga una factura VALIDATED y reciba 200 application/pdf con X-Tffiscal-Nfe-Status: Autorizada; obtenga una factura aún en verificación y reciba 409 + 10015301; obtenga una chave que su cuenta nunca envió y reciba 404 + 10015300; con Accept: application/pdf, los errores siguen en JSON.

Solución de problemas

¿La firma nunca coincide (401, código 10009003)?

Compruebe, por orden de frecuencia:

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

¿HTTP 200 pero la factura es falsa?

El nivel 1 solo juzga si el XML es internamente coherente. La autenticidad la decide el nivel 2 contra la SEFAZ y se entrega por webhook; condicione su acción de negocio (liberación, liquidación) al VALIDATED del webhook, nunca solo a la respuesta síncrona.

¿El status de la respuesta síncrona es el estado en la SEFAZ?

No. En la primera respuesta, el status se lee del protocolo dentro del XML que usted envió; todavía no se ha consultado a la SEFAZ. El estado confirmado por la SEFAZ llega con el veredicto de nivel 2: el status del webhook, o la consulta por chave una vez que el nivel 2 obtiene respuesta.

REJECTED con status NaoEncontrada: ¿la factura es falsa?

No necesariamente. La SEFAZ respondió "no encontrada" (cStat 217). La plataforma no concluye con el primer 217: vuelve a consultar a la SEFAZ varias veces a lo largo de unos minutos, porque una factura recién autorizada puede tardar en ser consultable, y solo un 217 persistente se convierte en REJECTED con NaoEncontrada. Causas habituales:

  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.

¿La firma del webhook sigue fallando?

La causa más común es deserializar la carga y volver a serializarla antes de calcular el HMAC, lo que cambia el orden de los campos o los espacios en blanco. Haga siempre el hash de los bytes recibidos sin procesar.

¿VALIDATION_ERROR es un problema de la factura?

No. Significa que la plataforma no pudo completar la comprobación; la factura en sí no fue juzgada. Hay dos tipos:

  1. status es Desconhecida y el reason empieza por SEFAZ does not answer this chave: la SEFAZ no acepta consultas de esta factura (actualmente cStat 526, facturas emitidas hace demasiado tiempo). La plataforma consulta una vez y devuelve el veredicto en el acto; volver a consultar no lo cambiaría. No significa que la factura sea falsa; simplemente no puede verificarse a través de la SEFAZ, así que confírmelo por otros medios si es necesario. El veredicto se reutiliza mientras la plataforma conserve el registro de la verificación, de modo que los reenvíos y las consultas por chave no vuelven a consultar a la SEFAZ; si de verdad necesita una consulta más, reenvíe con forceRevalidate: true.
  2. Cualquier otro caso significa que falló el canal de verificación (por ejemplo, limitación de la SEFAZ o una caída prolongada de la SEFAZ). Reenvíe más tarde con forceRevalidate: true. En este tipo el status es null en los webhooks, pero en las respuestas síncronas (la respuesta reutilizada del endpoint de XML y la consulta por chave) sigue trayendo la situación del XML enviado, así que no lo use para distinguir los tipos.

¿La obtención del DANFE devuelve 409 + 10015303?

La plataforma no tiene el XML original de esta factura (por ejemplo, tras un fallo del almacenamiento de archivo). Como se describe en "Cuando falta el XML original" en Obtención del DANFE, reenvíe el mismo XML sin cambios por la verificación de XML (sin forceRevalidate) y vuelva a obtener el PDF.

¿La obtención del DANFE sigue devolviendo 503?

Reintente tras el Retry-After. 10015304 significa que el XML original aún se está archivando y suele estar listo en segundos; 10015305 significa que la generación está ocupada o temporalmente no disponible; si dura más de unos minutos, contacte con la plataforma.

¿La obtención del DANFE devuelve 403 + 10009005?

Su aplicación no tiene el alcance de obtención del DANFE; se habilita por separado de la consulta por chave.

¿Desfase de reloj (401, código 10009001)?

El reloj de su servidor difiere del nuestro en más de 300 segundos. Use NTP. Nunca guarde en caché ni reutilice timestamps entre solicitudes.