Verificación de NF-e
Obtención del DANFE
Devuelve el DANFE de una NF-e verificada por su cuenta, por clave de acceso, como archivo PDF.
/openapi/v3/consultas/danfe/{chave}token, timestamp y sign, vea Autenticación.Devuelve el DANFE (formato A4) de una NF-e verificada por su cuenta, como archivo PDF. Cada llamada genera el PDF a partir del veredicto de verificación más reciente de la factura en ese momento; la plataforma no almacena los PDF, la obtención en sí no consulta a la SEFAZ y no se cobra aparte.
Este endpoint tiene su propio alcance, que la plataforma habilita por separado: tener la consulta por chave no da acceso al PDF, y viceversa.
Los fallos devuelven un estado HTTP y un objeto simple {code, message} (códigos al final de la página); los errores llegan en JSON aunque la solicitud lleve Accept: application/pdf. Los fallos de autenticación (401 / 403 / 429) usan el sobre de la plataforma, vea Errores de autenticación y autorización.
Parámetros de ruta
chave* | string | Clave de acceso |
* Campo obligatorio
Content-Type: application/pdf; Content-Disposition: inline; filename="{chave}.pdf"; Cache-Control: no-store; X-Tffiscal-Nfe-Status, la situación fiscal que refleja este PDF, Autorizada (versión normal) o Cancelada (con marca de agua de cancelada), para distinguirlas sin interpretar el PDF.La autenticación es la misma que en la consulta por chave: envíe las cabeceras token, timestamp y sign; el cuerpo del GET es la cadena vacía y la chave forma parte de la ruta firmada (reglas completas en Autenticación). Con app_secret = sk_live_9f8e7d6c5b4a, la chave 35260764962869000108550990001366171195929648 y timestamp = 1784906308, la cadena firmada es:
sign_input = "sk_live_9f8e7d6c5b4a"+ "/openapi/v3/consultas/danfe/35260764962869000108550990001366171195929648"+ ""+ "1784906308"sign = md5Hex(sign_input)
Que se genere o no el PDF depende del veredicto de la verificación de la factura en el momento en que lo obtiene:
| Veredicto actual | Resultado |
|---|---|
VALIDATED | DANFE normal |
REJECTED con status Cancelada | DANFE con la marca de agua CANCELADA en todas las páginas |
Verificación en curso (PENDING_SEFAZ / VALIDATING) | 409 + 10015301; obténgalo después del webhook |
Cualquier otro (los demás REJECTED, VALIDATION_ERROR) | 409 + 10015302; sin PDF |
- Solo se genera el DANFE de NF-e (modelo 55).
- Para un XML enviado sin el protocolo de autorización (protNFe), el número de protocolo y la fecha de autorización impresos en el PDF provienen del registro oficial que la plataforma obtuvo de la SEFAZ.
- El PDF refleja el veredicto más reciente en el momento en que lo obtiene, así que la misma factura puede dar PDF distintos con el tiempo. Por ejemplo, si la factura se cancela después y la nueva verificación de la plataforma devuelve
Cancelada, la siguiente obtención trae la versión con marca de agua. Obtener el PDF no actualiza el veredicto; los veredictos cambian según las reglas de Idempotencia y nueva verificación, y cada veredicto nuevo se envía por el webhook. - La respuesta lleva
Cache-Control: no-store: no la guarde en la caché de proxies ni gateways; si necesita conservar el archivo, guárdelo usted mismo. - Durante cuánto tiempo puede obtenerlo: mientras la plataforma conserve el registro de la verificación (3 meses por defecto); después, envíe de nuevo la factura a verificación.
- Al recibir
invoice.verify.completed, responda 2xx primero y obtenga el PDF de forma asíncrona. No lo obtenga dentro del manejador del webhook: un manejador más lento reduce la tasa con la que la plataforma puede enviarle webhooks (los requisitos del manejador están en Requisitos del receptor). - Obtenga el PDF solo para
VALIDATEDy, si los necesita, para veredictos constatusCancelada; cualquier otro veredicto devuelve 409. - Reintente el 503 tras el
Retry-After; no reintente a ciegas 404 ni 409 (10015301: espere el webhook;10015303: primero reenvíe el XML como se describe en "Cuando falta el XML original", justo debajo). - Límite de tasa: este endpoint tiene su propio grupo de endpoints, "obtención de DANFE", que no consume la cuota del grupo "verificación de facturas"; la cuota de la aplicación se sigue compartiendo con los demás endpoints. Obtener el PDF de todas las facturas duplica aproximadamente el volumen de llamadas respecto a los envíos, así que acuerde las cuotas con la plataforma (vea Límite de tasa y backoff).
La plataforma genera el DANFE a partir del XML que usted envió. En casos raros (por ejemplo, un fallo del almacenamiento de archivo), la plataforma no conservó el XML original de la factura, y la obtención del PDF devuelve 409 + 10015303. Para resolverlo:
- Reenvíe el mismo XML sin cambios (idéntico byte a byte al envío anterior) por la verificación de XML, sin
forceRevalidate. Mientras el veredicto siga dentro de su periodo de reutilización (vea Idempotencia y nueva verificación: por ejemplo,VALIDATEDdurante 24 horas desde que se obtuvo, las facturas canceladas siempre), la plataforma reutiliza el veredicto existente (sin nueva verificación ni evento de webhook nuevo) y guarda el XML original. Pasado el periodo de reutilización, el reenvío se verifica de nuevo por completo según las reglas habituales y el nuevo veredicto se envía por el webhook. - Vuelva a obtener el PDF (tras una verificación completa, cuando llegue el nuevo veredicto).
Notas:
- Un XML con contenido distinto se verifica de nuevo por completo según Idempotencia y nueva verificación; para las facturas canceladas / denegadas / inutilizadas, un contenido distinto se reutiliza tal cual y no se guarda nada. Reenvíe siempre el XML sin cambios.
- Si tampoco tiene ya el XML, la plataforma no puede generar el DANFE (la consulta de situación en la SEFAZ no devuelve el detalle de los ítems).
| Código | HTTP | |
|---|---|---|
| 10015104 | 400 | Chave malformada (longitud / caracteres / dígito verificador). Valide localmente antes: 44 dígitos, el último es dígito verificador mod-11. |
| 10015300 | 404 | Su cuenta no tiene registro de verificación de esta factura (la verificación hecha por otro integrador no cuenta). Envíela antes por la verificación de XML; no reintente. |
| 10015301 | 409 | Verificación aún no terminada (PENDING_SEFAZ / VALIDATING). Obtenga el PDF después de recibir invoice.verify.completed. |
| 10015302 | 409 | El veredicto actual no genera PDF: solo lo generan VALIDATED y REJECTED con status Cancelada. No reintente. |
| 10015303 | 409 | La plataforma no tiene el XML original de esta factura. Reenvíe el mismo XML sin cambios por la verificación de XML, sin forceRevalidate, y vuelva a obtenerlo (vea "Cuando falta el XML original" en esta página). |
| 10015304 | 503 | El XML original aún se está archivando. Reintente tras el Retry-After (5 segundos). |
| 10015305 | 503 | Generación ocupada o temporalmente no disponible. Reintente tras el Retry-After; si dura más de unos minutos, contacte con la plataforma. |
| 10001000 | 500 | Error interno de la plataforma. Reintente con backoff; si persiste, contacte con la plataforma con el timestamp y la ruta de la solicitud. |
