Qué es la validación y consulta de NF-e
Cada NF-e (Nota Fiscal Eletrônica) recibe, al emitirse, una clave de acceso única de 44 dígitos (chave de acesso) asignada por la SEFAZ, con un formato como 35200114200166000187550010000000071123456789. Esta cadena codifica el CNPJ del emisor, el número de factura, la fecha de emisión, el modelo y otros datos, y es el "documento de identidad global" de la NF-e.
La API de validación de NF-e le permite, con esa clave de 44 dígitos, consultar en tiempo real ante la SEFAZ: ¿esta factura es auténtica o falsa? ¿Fue cancelada? ¿Quién es el emisor? ¿Qué productos contiene? ¿Cuál es el importe? ¿Cuál es su historial de eventos? — todo ello en menos de 5 segundos.
Por qué necesita validar NF-e
La NF-e brasileña está diseñada para ser verificable públicamente, pero solo una interfaz profesional permite realizar la validación de forma masiva y automatizada. El "coste de confianza" de los siguientes escenarios determina si necesita esta API:
- Conformidad de recepción (el caso más común): el proveedor adjunta la NF-e al despachar la mercancía; usted debe confirmar que la factura es auténtica, que coincide con la mercancía y con el importe, antes de firmar la recepción e ingresar al inventario.
- Conciliación financiera: al cerrar el mes, valide que todas las NF-e contabilizadas del mes son reales y válidas, para evitar conciliar con facturas falsas.
- Fiscalización y antifalsificación: en auditorías internas, externas o fiscalizaciones, verifique la autenticidad de forma proactiva y detecte los problemas antes que la administración tributaria.
- Antifraude: identifique "NF-e alteradas", "NF-e canceladas que se hacen pasar por válidas" o "números de NF-e clonados".
- Consultas de atención al cliente: si un cliente cuestiona el contenido de una factura, puede recuperar de inmediato la versión oficial para compararla.
- Despacho aduanero transfronterizo: el agente aduanero necesita verificar primero la autenticidad de la NF-e antes de liberar la mercancía.
- Factoraje / crédito financiero: antes de financiar con la factura como garantía, hay que verificar que la factura existe realmente.
Capacidades clave de la API de validación de NF-e de TF Fiscal
1. Consulta completa con la clave de 44 dígitos
Ingrese la chave de acesso, llame a GET /v1/consulta/nfe/{chave} y reciba en segundos:
- Estado de autorización: Autorizada (autorizada) / Cancelada (cancelada) / Denegada (denegada) / Inexistente (no existe).
- Emisor: CNPJ, Razão Social, Inscrição Estadual, domicilio.
- Receptor: CNPJ o CPF, nombre, domicilio.
- Detalle de productos: NCM, CFOP, cantidad, precio unitario, precio total e impuestos de cada línea de producto.
- Resumen de impuestos: total de ICMS, IPI, PIS, COFINS, e importe total con impuestos.
- Fecha y número de emisión, número de autorización de la SEFAZ (protocolo), hora de autorización.
- Historial de eventos: todas las Carta de Correção, cancelaciones y eventos de confirmación de recepción (Manifestação).
2. Dos modos de respuesta: versión simplificada / versión completa
Versión simplificada (Resumo): solo devuelve el estado de autenticidad + la información principal del emisor y del receptor + el importe total. Respuesta rápida y precio bajo, ideal para el escenario de "solo quiero saber si esta factura es auténtica".
Versión completa (Completo): devuelve todos los campos tras analizar el XML completo de la NF-e, incluyendo el detalle de productos y el historial de eventos. Ideal para archivado, conciliación y verificación en profundidad.
3. Decodificación y verificación del código QR
La DANFE de la NF-e lleva un código QR. Escaneándolo con el móvil o subiendo una imagen, TF Fiscal decodifica automáticamente la clave de 44 dígitos y completa la verificación, evitando la molestia de digitar manualmente la larga cadena de 44 dígitos.
4. Validación por lotes
Envíe de una vez una lista de 100 a 1000 claves y reciba todos los resultados de forma asíncrona. Adecuado tanto para la conciliación de fin de mes como para fiscalizaciones periódicas.
5. SEFAZ en tiempo real + caché inteligente
Para escenarios "no sensibles", caché de 24 horas por defecto (la información de una NF-e ya autorizada apenas cambia), ahorrando costes de llamada. Para escenarios "sensibles" (como financiación), se puede forzar una consulta en tiempo real directa.
6. Alertas proactivas ante estados anómalos
Si se suscribe al seguimiento de ciertas NF-e clave, TF Fiscal monitoriza continuamente su estado. En cuanto detecta una "cancelación", una "denegación" o la aparición de una "Carta de Correção", le envía de inmediato una alerta por Webhook, evitando que opere con una factura ya invalidada.
Escenarios de uso típicos
- Validación de recepción en el WMS del almacén: escanee el código QR de la NF-e que acompaña la mercancía, valide automáticamente la autenticidad + coteje los bienes → ingrese al inventario solo si se aprueba.
- Conciliación financiera mensual: valide por lotes todas las NF-e contabilizadas del mes y marque automáticamente las "canceladas" o con "importe no coincidente".
- Control de riesgo en comercio electrónico: verifique la autenticidad cuando un cliente suba una NF-e para solicitar un reembolso o servicio posventa.
- Despacho aduanero en logística transfronteriza: verifique que la NF-e de salida está en estado válido antes de la declaración aduanera.
- Factoraje financiero: verifique que la factura existe realmente antes de otorgar un préstamo con las cuentas por cobrar de la NF-e como garantía.
- Autoinspección y fiscalización: en la auditoría interna de fin de año, valide por lotes el estado de todas las NF-e emitidas durante el año.
Preguntas frecuentes
P: No tengo la clave de 44 dígitos, solo el número de factura, ¿qué hago?
TF Fiscal ofrece una interfaz de consulta combinada por "número de factura + CNPJ del emisor + modelo + serie", que arma la chave de acesso a partir de esos campos y luego realiza la consulta.
P: ¿Puedo consultar NF-e emitidas por otras empresas (que no haya emitido yo)?
Sí. La interfaz de validación de NF-e es una API pública (cualquiera puede verificar la autenticidad), no se limita a las que usted mismo emitió. Por eso la SEFAZ imprime el código QR en cada DANFE: cualquiera puede escanearlo y verificarla.
P: ¿Qué diferencia hay con la página de verificación del portal oficial?
El portal oficial (NF-e Portal Nacional) solo permite consultas manuales una a una y tiene límite por IP. TF Fiscal ofrece una API a través de un canal autorizado, con soporte para lotes, automatización y caché.
P: ¿Cuánto tarda la respuesta?
La versión simplificada tarda en promedio 800 ms (menos de 100 ms con acierto de caché); la versión completa, de 2 a 3 segundos en promedio. El modo asíncrono por lotes alcanza un rendimiento global de más de 50 TPS.
P: ¿Qué significa que una NF-e esté "Cancelada"? ¿Está anulada?
Sí. Cancelada significa que el emisor canceló esta factura a través de la SEFAZ dentro de las 24 horas. Esa NF-e ya no tiene efecto legal. Una NF-e con estado Cancelada debe rechazarse y no contabilizarse.
Soluciones relacionadas