NF-e XML Parser to Excel/CSV — Converter XML de Nota Fiscal

Convert Brazilian NF-e and NFC-e XML files into Excel-ready CSV and JSON, in bulk. Upload single XMLs or whole ZIP archives exported from your ERP, accounting system or SEFAZ portal. You get one row per invoice (header, totals and taxes) and, optionally, one row per item (product, NCM, CFOP, quantities and taxes). Results are saved as a dataset and as CSV files you can open directly in Excel or Google Sheets.

It works entirely on the files you provide: no SEFAZ login, no certificate and no scraping.

🇧🇷 Português: converta XML de NF-e (NFe) e NFC-e em planilha Excel/CSV e JSON, em lote. Veja a seção Em português no final desta página.

What does it do?

• NF-e (modelo 55) and NFC-e (modelo 65), layout 4.00 (layout 3.10 also parsed): nfeProc (authorized, with protocol), bare NFe and enviNFe batches
• Events: cancelamento (110111/110112), carta de correção (110110) and manifestação do destinatário, plus inutilização records (voided number ranges, procInutNFe). Invoices cancelled by an event in the same batch are flagged cancelled: true
• ZIP support: folders, nested ZIPs and thousands of XMLs per archive. Non-XML files are ignored
• Access key (chave de acesso) validation: check digit (DV), plus a cross-check of the key against the invoice content (UF, date, CNPJ, model, series, number)
• Taxes: ICMS, ICMS-ST, FCP, IPI, PIS, COFINS, ISS, DIFAL (ICMSUFDest), installments (duplicatas) and payments, approximate taxes (Lei 12.741), and the new IBS / CBS fields of the tax reform (NT 2025.002)
• Protocol status: authorized, denied (denegada), rejected or no protocol, with the protocol number and date
• CSV exports (INVOICES.csv, ITEMS.csv, EVENTS.csv) in standard or Excel Brasil format (semicolon, decimal comma, UTF-8 BOM)
• Privacy by default (LGPD): recipient CPF masked as ***.456.789-**, no recipient street/e-mail/phone, no free-text notes, and XML content is never logged
• Pay only per invoice parsed: errors, events and duplicates are free

Use cases

• Accounting and bookkeeping: import purchase (entrada) and sales (saída) invoices into Excel or your accounting system, and check totals, CFOPs and taxes per client
• ERP imports: turn a folder or ZIP of supplier XMLs into CSV/JSON rows your ERP, database or Power BI can load
• Tax reconciliation and audit: reconcile ICMS, ICMS-ST, IPI, PIS/COFINS and IBS/CBS per invoice or per item (NCM/CFOP) against your tax books (SPED) and payments
• Invoice status checks: list which invoices in a batch are authorized, denied, without protocol or cancelled
• Automation: parse the XMLs that arrive by e-mail or upload in Make, Zapier or n8n and push structured rows to Sheets, a database or your ERP

Input

Field	Description
files	Upload XML or ZIP files directly in Apify Console
xmlUrls	Direct links to XML/ZIP files (S3, your server, key-value store record URLs, etc.)
privateXmlUrls	Links that carry a token or signature (S3 pre-signed URLs, ?token=...), one per line. Stored encrypted (secret input); the query string is never written to the output
keyValueStoreId / keyValueStorePrefix	Process every XML/ZIP record of an Apify key-value store, optionally only keys starting with a prefix (handy for automations)
xmlContent	Paste one XML for a quick test. In Apify Console it is pre-filled with a fictitious demo NF-e (homologation, no fiscal value), so you can click Start and see real output right away. The demo is ignored automatically when you also provide files, xmlUrls or a keyValueStoreId. Running the demo on its own parses 1 invoice (charged like any other invoice)
outputMode	invoices (default), items or both
csvFormat	standard or excel-br
keepCpf	Disable CPF masking (default false)
includeAdditionalInfo	Include free-text notes (infCpl, infAdProd). Default false
deduplicate	Skip repeated access keys (default true)
maxConcurrency	Files/URLs processed in parallel (default 4, max 10)

Input example

The input of a real test run on a fictitious NF-e stored in a key-value store (store ID replaced):

{
  "keyValueStoreId": "YOUR_STORE_ID",
  "keyValueStorePrefix": "nfe55-proc-b2b",
  "outputMode": "both"
}

With URLs and Excel Brasil CSVs:

{
  "xmlUrls": ["https://example.com/notas/setembro.zip"],
  "outputMode": "both",
  "csvFormat": "excel-br"
}

Output

Every dataset row has a rowType (invoice, item, event or error) and a status (success, duplicate or error). The dataset has views for Invoices, Items, Events and Errors. The key-value store contains INVOICES.csv, ITEMS.csv, EVENTS.csv (split into parts every 100,000 rows) and a SUMMARY.

The examples below come from the test run above: a fictitious B2B NF-e (homologation environment, no fiscal value) with ICMS-ST and IBS/CBS.

Output example: invoice row

{
  "rowType": "invoice",
  "status": "success",
  "sourceFile": "kvs:YOUR_STORE_ID/nfe55-proc-b2b-st-ibscbs.xml",
  "accessKey": "35260998765432000198550010000010021112233441",
  "accessKeyValid": true,
  "accessKeyMatchesContent": true,
  "documentType": "NF-e",
  "model": "55",
  "layoutVersion": "4.00",
  "series": "1",
  "number": "1002",
  "issueDate": "2026-09-12T09:00:00-03:00",
  "exitEntryDate": "2026-09-12T09:00:00-03:00",
  "operationType": "saida",
  "operationNature": "VENDA DE MERCADORIA",
  "purpose": "normal",
  "environment": "homologation",
  "issueTypeCode": "1",
  "finalConsumer": false,
  "ufCode": "35",
  "issuerDocument": "98.765.432/0001-98",
  "issuerDocumentType": "CNPJ",
  "issuerName": "EMPRESA FICTICIA DE TESTES LTDA",
  "issuerTradeName": "FICTICIA",
  "issuerStateRegistration": "111222333444",
  "issuerTaxRegime": "Regime Normal",
  "issuerCity": "São Paulo",
  "issuerCityCode": "3550308",
  "issuerState": "SP",
  "recipientDocument": "13.579.246/0001-01",
  "recipientDocumentType": "CNPJ",
  "recipientName": "NF-E EMITIDA EM AMBIENTE DE HOMOLOGACAO - SEM VALOR FISCAL",
  "recipientStateRegistration": "0012345670089",
  "recipientCity": "Belo Horizonte",
  "recipientState": "MG",
  "itemCount": 2,
  "totalProducts": 1260,
  "totalInvoice": 1350.72,
  "discount": 0,
  "freight": 0,
  "insurance": 0,
  "otherExpenses": 0,
  "icmsBase": 1260,
  "icmsValue": 226.8,
  "icmsRelief": 0,
  "fcpValue": 0,
  "icmsStBase": 1764,
  "icmsStValue": 90.72,
  "fcpStValue": 0,
  "ipiValue": 0,
  "ipiReturnedValue": 0,
  "importTaxValue": 0,
  "pisValue": 20.79,
  "cofinsValue": 95.76,
  "issValue": null,
  "approxTotalTaxes": 378,
  "ibsValue": 1.26,
  "cbsValue": 11.34,
  "freightMode": "emitente (CIF)",
  "paymentMethods": ["boleto"],
  "paymentTotal": 1350.72,
  "protocolStatusCode": "100",
  "protocolMessage": "Autorizado o uso da NF-e",
  "protocolNumber": "135260000000002",
  "authorizationDate": "2026-09-12T09:00:00-03:00",
  "authorizationStatus": "authorized",
  "cancelled": false,
  "cancellationDate": null,
  "warnings": [],
  "charged": true,
  "processedAt": "2026-09-28T17:22:24.105Z"
}

Output example: item row

{
  "rowType": "item",
  "status": "success",
  "sourceFile": "kvs:YOUR_STORE_ID/nfe55-proc-b2b-st-ibscbs.xml",
  "accessKey": "35260998765432000198550010000010021112233441",
  "documentType": "NF-e",
  "series": "1",
  "invoiceNumber": "1002",
  "issueDate": "2026-09-12T09:00:00-03:00",
  "issuerDocument": "98.765.432/0001-98",
  "issuerName": "EMPRESA FICTICIA DE TESTES LTDA",
  "recipientDocument": "13.579.246/0001-01",
  "recipientName": "NF-E EMITIDA EM AMBIENTE DE HOMOLOGACAO - SEM VALOR FISCAL",
  "authorizationStatus": "authorized",
  "cancelled": false,
  "itemNumber": 1,
  "productCode": "B100",
  "gtin": null,
  "description": "CERVEJA LATA 350ML CX 12",
  "ncm": "22030000",
  "cest": "0302100",
  "cfop": "6401",
  "unit": "CX",
  "quantity": 20,
  "unitPrice": 45,
  "totalValue": 900,
  "discount": null,
  "freight": null,
  "icmsOrigin": "0",
  "icmsCst": "10",
  "icmsBase": 900,
  "icmsRate": 18,
  "icmsValue": 162,
  "icmsStValue": 64.8,
  "ipiCst": null,
  "ipiRate": null,
  "ipiValue": null,
  "pisCst": "01",
  "pisValue": 14.85,
  "cofinsCst": "01",
  "cofinsValue": 68.4,
  "approxTaxes": 270,
  "ibsCbsCst": "000",
  "ibsValue": 0.9,
  "cbsValue": 8.1,
  "processedAt": "2026-09-28T17:22:24.105Z"
}

Event and error rows

From our fixture tests (a cancellation event and a malformed file):

{ "rowType": "event", "status": "success", "eventType": "110111", "eventTypeDescription": "Cancelamento", "isCancellation": true, "cancelledProtocol": "135260000000001", "eventProtocolStatusCode": "135", "eventRegistered": true, "charged": false }

{ "rowType": "error", "status": "error", "sourceFile": "notas.zip/x.xml", "errorMessage": "Malformed XML (near line 3)", "charged": false }

Invoices with a wrong access key check digit, a key that doesn't match the content, or item values that don't add up to vProd are still parsed. The problem is listed in warnings.

Pricing

This Actor uses pay per event pricing:

Charged	invoice event: US$0.003 per NF-e/NFC-e successfully parsed (US$3 per 1,000). Items are included: an invoice with 50 items costs the same as one with 1 item, in every outputMode
Free	Event XMLs (cancellation, correction, manifestação, inutilização), files that fail to parse or aren't NF-e/NFC-e, duplicate access keys (with deduplicate on), and runs without any input file (they finish with status: "NO_INPUT" in SUMMARY)
No	Start fee or monthly rental

The test run above parsed 1 invoice with 2 items, so it cost US$0.003 in events. The current price is always shown on the Actor's Pricing tab.

To cap your spend, set "Max cost per run" in the run options (or maxTotalChargeUsd in the API). The Actor stops at your limit, never charges beyond it, and reports in SUMMARY how many invoices were not processed.

Integrations and API

• Apify API: upload your XML/ZIP somewhere reachable (or into a key-value store) and start a run over HTTP. For small batches, run-sync-get-dataset-items returns the rows in the same request:

curl -X POST "https://api.apify.com/v2/acts/brasil_utils~nfe-xml-parser/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"xmlUrls": ["https://example.com/notas/setembro.zip"], "outputMode": "invoices"}'

• Make, Zapier and n8n: use Apify's integrations for these platforms ("Run an Actor" / "Get dataset items") to parse XMLs received by e-mail, Drive or upload, then send the rows to Google Sheets, a database or your ERP.
• CSV download: INVOICES.csv and ITEMS.csv are in the run's key-value store at https://api.apify.com/v2/key-value-stores/{storeId}/records/INVOICES.csv.
• Webhooks, Google Sheets, Slack and more: in the Actor's Integrations tab in Apify Console.

JavaScript / TypeScript (npm install apify-client):

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('brasil_utils/nfe-xml-parser').call({
    xmlUrls: ['https://example.com/notas/setembro.zip'],
    outputMode: 'both',
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
const invoices = items.filter((r) => r.rowType === 'invoice');
console.log(invoices.map((r) => [r.number, r.issuerName, r.totalInvoice, r.authorizationStatus]));

// Excel-ready CSV from the run's key-value store
const { value: invoicesCsv } = await client.keyValueStore(run.defaultKeyValueStoreId).getRecord('INVOICES.csv');

Python (pip install apify-client):

import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("brasil_utils/nfe-xml-parser").call(
    run_input={"xmlUrls": ["https://example.com/notas/setembro.zip"], "outputMode": "both"}
)
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    if row["rowType"] == "invoice":
        print(row["number"], row["issuerName"], row["totalInvoice"], row["authorizationStatus"])

Limits and data sources

• Data source: only the XML files you provide. The Actor does not connect to SEFAZ, does not download invoices by access key and does not verify digital signatures. authorizationStatus comes from the protocol embedded in the XML (protNFe).
• Supported: NF-e (55) and NFC-e (65), layouts 4.00 and 3.10, plus their events and inutilização records. Not supported: CT-e, MDF-e, NFS-e and DF-e summaries (resNFe). These return a clear error row and are not charged.
• Size: up to 100 MB per file/URL, 500 MB uncompressed and 50,000 entries per ZIP.
• Speed: at the default 256 MB of memory, about 250 invoices per second in our tests (5,000 invoices with 22,500 items in about 20 seconds). For 100k+ invoices, use 1 GB of memory.
• Privacy: files are processed inside your own Apify run; results go to your own dataset and key-value store, and XML contents are never written to logs.

FAQ

How do I convert NF-e XML to Excel? Upload the XMLs (or a ZIP) in files, choose csvFormat: "excel-br", run, and download INVOICES.csv / ITEMS.csv from the Storage tab. They open in Excel with correct accents and decimal commas. You can also export the dataset as XLSX.

What happens if I start a run without any file? The run finishes successfully with a single error row explaining which fields to fill, SUMMARY.status is NO_INPUT, and nothing is charged.

Can I get one row per product (item)? Yes. Set outputMode to items or both. Each item row repeats the invoice's key, number, date, issuer and recipient so it can be analyzed on its own.

Does it detect cancelled invoices? Yes, when the cancellation event XML (procEventoNFe) is in the same run. The invoice gets cancelled: true and cancellationDate.

What about personal data (LGPD)? Recipient CPFs (and CPFs of individual issuers or event authors) are masked by default. Recipient street address, e-mail and phone are never extracted, and free-text notes are off by default. Enable keepCpf only if you have a legal basis.

Does it support the tax reform (IBS/CBS)? Yes, the IBS and CBS values and the IBS/CBS CST are extracted per invoice and per item when present (NT 2025.002).

Do I need a digital certificate? No. The Actor only reads XML files; it never talks to SEFAZ.

---

🇧🇷 Em português

Converta XML de NF-e (NFe) e NFC-e em planilha Excel/CSV e JSON, em lote. Envie arquivos XML soltos ou ZIP com milhares de notas. O Actor gera uma linha por nota com chave de acesso (com validação do dígito verificador), número, série, data de emissão, emitente (CNPJ, razão social, UF), destinatário, valor dos produtos, valor total da nota e os totais de ICMS, ICMS-ST, IPI, PIS, COFINS, IBS e CBS, além da situação do protocolo (autorizada, denegada, rejeitada) e se a nota foi cancelada (evento de cancelamento no mesmo lote). Opcionalmente, também gera uma linha por item: produto, NCM, CEST, CFOP, quantidade, valor unitário, CST e impostos.

O que o Actor faz

• Lê procNFe, NFe, enviNFe, procEventoNFe (cancelamento, carta de correção, manifestação) e procInutNFe (inutilização)
• Gera arquivos CSV no formato Excel Brasil (ponto e vírgula e vírgula decimal) e JSON
• Valida a chave de acesso e compara com o conteúdo da nota
• Mascara o CPF do destinatário por padrão (***.456.789-**), em linha com a LGPD
• Não acessa a SEFAZ e não precisa de certificado digital: processa apenas os XMLs que você envia
• O campo xmlContent vem preenchido com uma NF-e fictícia de demonstração para testar na hora; ela é ignorada automaticamente quando você envia arquivos, URLs ou um key-value store. Execução sem nenhum arquivo termina com status NO_INPUT, sem cobrança

Casos de uso

• Contabilidade e escritórios contábeis: importar notas de entrada e saída para Excel ou para o sistema contábil
• Importação para ERP: transformar uma pasta ou ZIP de XMLs de fornecedores em linhas CSV/JSON
• Conciliação fiscal e auditoria: conferir ICMS, ICMS-ST, IPI, PIS/COFINS e IBS/CBS por nota ou por item (NCM/CFOP)
• Conferência de status: ver quais notas do lote estão autorizadas, denegadas, sem protocolo ou canceladas

Preço

US$0,003 por nota (NF-e/NFC-e) processada com sucesso (US$3 por 1.000), com todos os itens incluídos. Eventos, erros e chaves duplicadas não são cobrados. Sem taxa de início e sem mensalidade. Use o limite "Max cost per run" para definir o valor máximo por execução.

Integração

Rode pelo Apify Console, agende execuções ou chame pela API do Apify (exemplos em JavaScript, Python e curl acima). Também dá para conectar ao Make, Zapier e n8n pelas integrações do Apify.

Perguntas frequentes

Como converter XML da NF-e para Excel? Envie os XMLs ou o ZIP no campo files, escolha csvFormat: "excel-br" e baixe INVOICES.csv e ITEMS.csv na aba Storage.

O Actor baixa notas pela chave de acesso? Não. Ele só lê os XMLs que você fornece.

Quais documentos não são suportados? CT-e, MDF-e, NFS-e e resumos (resNFe). Eles geram uma linha de erro, sem cobrança.