NF-e Validation & Lookup API

What is NF-e Validation & Lookup

When an NF-e (Nota Fiscal Eletrônica) is issued, SEFAZ assigns it a unique 44-digit access key (chave de acesso), formatted like 35200114200166000187550010000000071123456789. This string encodes the issuer's CNPJ, the invoice number, the issue date, the model and more — it is the NF-e's "global ID number".

The NF-e Validation API lets you use this 44-digit key to query SEFAZ in real time: Is this invoice genuine or fake? Has it been cancelled? Who is the issuer? What are the goods? What is the amount? What is the event history? — all returned within 5 seconds.

Why You Need NF-e Validation

The Brazilian NF-e is designed to be publicly verifiable, but only a professional interface can perform validation in bulk and automatically. The "cost of trust" in the following scenarios determines whether you need this API:

• Goods-receipt checks (most common): a supplier ships goods with an NF-e, and you need to confirm the invoice is genuine, matches the goods and matches the amount before signing for and stocking it
• Financial reconciliation: at month-end, verify that all NF-e booked during the month are genuine and valid, to avoid fake invoices being used to offset accounts
• Audit and anti-counterfeiting: proactively verify authenticity during internal audits, external audits and tax inspections — spotting problems before the tax authority does
• Anti-fraud: identify "modified NF-e", "cancelled NF-e posing as valid" and "cloned NF-e numbers"
• Customer support queries: when a customer disputes invoice content, you can instantly pull up the official version for comparison
• Cross-border customs clearance: customs brokers need to verify the authenticity of the NF-e before releasing the goods
• Financial factoring / credit: before using an invoice as collateral for financing, verify that the invoice genuinely exists

Core Capabilities of TF Fiscal's NF-e Validation API

1. Complete Lookup with a 44-Digit Key

Enter the chave de acesso and call GET /v1/consulta/nfe/{chave} to get back in seconds:

• Authorization status: Autorizada (authorized) / Cancelada (cancelled) / Denegada (denied) / Inexistente (does not exist)
• Issuer: CNPJ, Razão Social, Inscrição Estadual, address
• Recipient: CNPJ or CPF, name, address
• Line items: each item's NCM, CFOP, quantity, unit price, total price and individual tax amounts
• Tax summary: total ICMS, IPI, PIS and COFINS, and the tax-inclusive total
• Issue date and number, SEFAZ authorization number (protocolo), authorization time
• Event history: all Carta de Correção events, cancellations and Manifestação receipt-confirmation events

2. Two Return Modes: Summary / Complete

Summary (Resumo): returns only the authenticity status + the issuer and recipient core information + the total amount. Fast and low-cost, ideal for the "I just want to know if this invoice is genuine" scenario.
Complete (Completo): returns all fields after parsing the full NF-e XML, including line items and event history. Ideal for archiving, reconciliation and in-depth verification.

3. QR Code Decoding and Verification

The NF-e's DANFE carries a QR Code. Scan it with a phone or upload an image, and TF Fiscal automatically decodes the 44-digit key and completes verification, saving you the trouble of manually entering the 44-digit string.

4. Batch Validation

Submit a list of 100–1,000 keys at once and get all results back asynchronously. Suitable for month-end reconciliation and periodic audits.

5. Real-time SEFAZ + Smart Cache

For "non-sensitive" scenarios, a 24-hour cache applies by default (an authorized NF-e's information rarely changes), saving call cost. For "highly sensitive" scenarios (such as financial financing), real-time pass-through queries can be forced.

6. Proactive Alerts on Anomalous Status

If you subscribe to certain key NF-e, TF Fiscal continuously monitors their status. As soon as it detects "cancelled", "denied" or "a Carta de Correção", it pushes a Webhook alert immediately, preventing you from proceeding on an invalidated invoice.

Typical Use Cases

• Warehouse WMS goods-receipt verification: scan the QR Code on the accompanying NF-e to auto-verify + compare against the goods → only stock it if it passes
• Monthly financial reconciliation: batch-validate all NF-e booked during the month, automatically flagging "cancelled" or "amount mismatch"
• E-commerce risk control: verify authenticity when a customer uploads an NF-e to request a refund / after-sales service
• Cross-border logistics clearance: verify that the outbound NF-e is in a valid state before customs declaration
• Financial factoring: before lending against NF-e receivables as collateral, verify that the invoice genuinely exists
• Audit self-checks: at year-end internal audit, batch-verify the status of all NF-e issued during the year

FAQ

Related Solutions

• NF-e Goods Invoice API · issuer-side scenarios
• Consulta CNPJ · jointly verify the issuer's credentials
• DANFE PDF Generation · source of the QR Code
• SEFAZ Status Monitoring