NF-e XML to JSON: Brazil Invoice Parser (NF-e, NFC-e)

Convert Brazilian electronic invoices (NF-e, model 55, and NFC-e, model 65, layout 4.00) from XML into clean JSON, or into one row per product line ready for spreadsheets and databases. You get the issuer, buyer, every item with NCM, CFOP, GTIN, ICMS, IPI, PIS and COFINS, the totals, payment methods, installments and the SEFAZ authorization. The 44-digit access key is checked (check digit) and decoded.

The XML of an NF-e is deeply nested, uses Portuguese tag names and has dozens of tax groups (ICMS00, ICMS20, ICMSSN102...). Every accountant, ERP integration and expense tool has to write this parser. This Actor does it for thousands of files per run, through an API or a form, with English field names and CPF of individual buyers always masked.

Typical uses: bookkeeping and tax checks, importing supplier invoices into an ERP or spreadsheet, purchase and price analysis by NCM, expense apps, and AI agents that read invoices.

What you get per invoice

• Access key, check digit validation and decoded fields (state, year and month, issuer CNPJ, model, series, number)
• Number, series, issue date, operation, direction, environment, SEFAZ status and protocol
• Issuer: CNPJ, name, trade name, state registration, tax regime (CRT), address
• Buyer: CNPJ or masked CPF, name, state registration; e-mail and address only for companies
• Items: code, GTIN, description, NCM, CEST, CFOP, unit, quantity, prices, discount, ICMS (group, origin, CST/CSOSN, base, rate, value, ST), IPI, PIS, COFINS, approximate taxes
• Totals, payments (with method names), installments, carrier and additional information

Input

Field	Description
xmlUrls	Links to XML files. Up to 5,000 per run, 5 MB each.
xmlTexts	XML documents pasted directly, one per entry.
outputMode	invoices (default): one row per invoice. items: one row per item with the invoice header repeated.

{
  "xmlUrls": ["https://example.com/nfe/35261011222333000181550010000012341123456787.xml"],
  "outputMode": "items"
}

Output

One dataset item per invoice (items shortened to one entry here):

{
  "source": "text #1",
  "accessKey": "35261011222333000181550010000012341123456787",
  "accessKeyValid": true,
  "keyState": "SP",
  "keyYearMonth": "2026-10",
  "keyIssuerCnpj": "11222333000181",
  "keyModel": "55",
  "keySeries": 1,
  "keyNumber": 1234,
  "model": "NF-e",
  "series": 1,
  "number": 1234,
  "issuedAt": "2026-10-28T10:15:00-03:00",
  "operation": "Venda de mercadoria",
  "direction": "outbound",
  "environment": "production",
  "status": {
    "code": "100",
    "message": "Autorizado o uso da NF-e",
    "protocol": "135260000000001",
    "authorizedAt": "2026-10-28T10:15:30-03:00"
  },
  "authorized": true,
  "issuer": {
    "document": "11222333000181",
    "name": "EXEMPLO COMERCIO DE ELETRONICOS LTDA",
    "tradeName": "Exemplo Eletronicos",
    "stateRegistration": "110042490114",
    "taxRegime": "Normal",
    "address": {
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": null,
      "district": "Bela Vista",
      "city": "Sao Paulo",
      "cityIbgeCode": "3550308",
      "state": "SP",
      "zipCode": "01310100",
      "country": "Brasil",
      "phone": "1130000000"
    }
  },
  "buyer": {
    "document": "***456789**",
    "type": "individual",
    "name": "CONSUMIDOR DE EXEMPLO",
    "stateRegistration": null,
    "email": null,
    "address": null,
    "state": "SP"
  },
  "totals": {
    "products": 4650,
    "freight": 0,
    "insurance": 0,
    "discount": 10,
    "otherCharges": 0,
    "icmsBase": 4640,
    "icms": 835.2,
    "icmsSt": 0,
    "ipi": 0,
    "pis": 76.56,
    "cofins": 352.64,
    "approxTaxes": 1395,
    "invoice": 4640
  },
  "payments": [
    {
      "method": "15",
      "methodName": "Boleto bancário",
      "amount": 4640
    }
  ],
  "installments": [
    {
      "number": "001",
      "dueDate": "2026-11-28",
      "amount": 2320
    },
    {
      "number": "002",
      "dueDate": "2026-12-28",
      "amount": 2320
    }
  ],
  "carrier": null,
  "freightMode": "9",
  "additionalInfo": "Pedido 98765. Documento de exemplo, sem valor fiscal.",
  "itemCount": 2,
  "items": [
    {
      "itemNumber": 1,
      "code": "NB-001",
      "gtin": "7891234567895",
      "description": "NOTEBOOK 15 POL 16GB RAM",
      "ncm": "84713012",
      "cest": null,
      "cfop": "5102",
      "unit": "UN",
      "quantity": 1,
      "unitPrice": 4500,
      "totalPrice": 4500,
      "discount": null,
      "freight": null,
      "icmsGroup": "ICMS00",
      "icmsOrigin": "0",
      "icmsCst": "00",
      "icmsBase": 4500,
      "icmsRate": 18,
      "icmsValue": 810,
      "icmsStValue": null,
      "ipiCst": "53",
      "ipiValue": null,
      "pisCst": "01",
      "pisValue": 74.25,
      "cofinsCst": "01",
      "cofinsValue": 342,
      "approxTaxes": 1350,
      "additionalInfo": null
    }
  ],
  "error": null
}

In items mode each row has source, accessKey, number, issuedAt, issuerDocument, issuerName, buyerDocument, buyerName and the item fields. Files that cannot be read, or that are not an NF-e, come back with error filled in and are not charged.

How much does it cost?

Pay per event: one invoice per invoice parsed, with all its items included (also in items mode). Invalid files, failed downloads and documents that are not an NF-e are free.

$0.004 per invoice (invoice event, pay per event). Charged once per invoice parsed, with all its items included. Invalid files, failed downloads and non NF-e documents are free.

You get	Free tier	Bronze tier (10% off)	Gold tier (30% off)
100 invoices	$0.40	$0.36	$0.28
1,000 invoices	$4.00	$3.60	$2.80
10,000 invoices	$40.00	$36.00	$28.00

Discounts follow your Apify subscription tier: Bronze 10%, Silver 20%, Gold and above 30%. No subscription to this Actor and no charge for platform usage: you pay only for results. The Apify Free plan includes $5 of monthly credit, enough for about 1,250 invoices at the list price. You can cap the cost of any run with Maximum cost per run; the Actor stops when it is reached.

Data source and limits

The Actor reads only the XML files you give it; nothing is sent to SEFAZ or any other service. It follows the NF-e layout 4.00 (Manual de Orientação do Contribuinte). The authorization status is the one written in the XML (protNFe): to confirm that an invoice was not cancelled later, check it on the SEFAZ portal.

Limits: XML only (extract ZIP files first; DANFE PDFs are not read). CT-e, MDF-e and NFS-e are not supported. CPF of individual buyers and carriers is masked, and their e-mail and street address are not returned.

Use it via API

Run it from any language and get the results as JSON. Replace <YOUR_API_TOKEN> with your Apify API token.

curl -X POST "https://api.apify.com/v2/acts/br_data_hub~br-nfe-xml-parser/run-sync-get-dataset-items?token=<YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"xmlTexts": ["<?xml version=\"1.0\" encoding=\"UTF-8\"?><nfeProc xmlns=\"http://www.portalfiscal.inf.br/nfe\" versao=\"4.00\"><NFe><infNFe Id=\"NFe35261011222333000181550010000012341123456787\" versao=\"4.00\"><ide><cUF>35</cUF><cNF>12345678</cNF><natOp>Venda de mercadoria</natOp><mod>55</mod><serie>1</serie><nNF>1234</nNF><dhEmi>2026-10-28T10:15:00-03:00</dhEmi><tpNF>1</tpNF><idDest>1</idDest><cMunFG>3550308</cMunFG><tpImp>1</tpImp><tpEmis>1</tpEmis><cDV>7</cDV><tpAmb>1</tpAmb><finNFe>1</finNFe><indFinal>1</indFinal><indPres>1</indPres><procEmi>0</procEmi><verProc>1.0</verProc></ide><emit><CNPJ>11222333000181</CNPJ><xNome>EXEMPLO COMERCIO DE ELETRONICOS LTDA</xNome><xFant>Exemplo Eletronicos</xFant><enderEmit><xLgr>Avenida Paulista</xLgr><nro>1000</nro><xBairro>Bela Vista</xBairro><cMun>3550308</cMun><xMun>Sao Paulo</xMun><UF>SP</UF><CEP>01310100</CEP><cPais>1058</cPais><xPais>Brasil</xPais><fone>1130000000</fone></enderEmit><IE>110042490114</IE><CRT>3</CRT></emit><dest><CPF>12345678909</CPF><xNome>CONSUMIDOR DE EXEMPLO</xNome><enderDest><xLgr>Rua das Flores</xLgr><nro>10</nro><xBairro>Centro</xBairro><cMun>3550308</cMun><xMun>Sao Paulo</xMun><UF>SP</UF><CEP>01001000</CEP></enderDest><indIEDest>9</indIEDest><email>consumidor@example.com</email></dest><det nItem=\"1\"><prod><cProd>NB-001</cProd><cEAN>7891234567895</cEAN><xProd>NOTEBOOK 15 POL 16GB RAM</xProd><NCM>84713012</NCM><CFOP>5102</CFOP><uCom>UN</uCom><qCom>1.0000</qCom><vUnCom>4500.00</vUnCom><vProd>4500.00</vProd><cEANTrib>7891234567895</cEANTrib><uTrib>UN</uTrib><qTrib>1.0000</qTrib><vUnTrib>4500.00</vUnTrib><indTot>1</indTot></prod><imposto><vTotTrib>1350.00</vTotTrib><ICMS><ICMS00><orig>0</orig><CST>00</CST><modBC>3</modBC><vBC>4500.00</vBC><pICMS>18.00</pICMS><vICMS>810.00</vICMS></ICMS00></ICMS><IPI><cEnq>999</cEnq><IPINT><CST>53</CST></IPINT></IPI><PIS><PISAliq><CST>01</CST><vBC>4500.00</vBC><pPIS>1.65</pPIS><vPIS>74.25</vPIS></PISAliq></PIS><COFINS><COFINSAliq><CST>01</CST><vBC>4500.00</vBC><pCOFINS>7.60</pCOFINS><vCOFINS>342.00</vCOFINS></COFINSAliq></COFINS></imposto></det><det nItem=\"2\"><prod><cProd>MS-010</cProd><cEAN>SEM GTIN</cEAN><xProd>MOUSE SEM FIO</xProd><NCM>84716053</NCM><CFOP>5102</CFOP><uCom>UN</uCom><qCom>2.0000</qCom><vUnCom>75.00</vUnCom><vProd>150.00</vProd><cEANTrib>SEM GTIN</cEANTrib><uTrib>UN</uTrib><qTrib>2.0000</qTrib><vUnTrib>75.00</vUnTrib><vDesc>10.00</vDesc><indTot>1</indTot></prod><imposto><vTotTrib>45.00</vTotTrib><ICMS><ICMS00><orig>0</orig><CST>00</CST><modBC>3</modBC><vBC>140.00</vBC><pICMS>18.00</pICMS><vICMS>25.20</vICMS></ICMS00></ICMS><PIS><PISAliq><CST>01</CST><vBC>140.00</vBC><pPIS>1.65</pPIS><vPIS>2.31</vPIS></PISAliq></PIS><COFINS><COFINSAliq><CST>01</CST><vBC>140.00</vBC><pCOFINS>7.60</pCOFINS><vCOFINS>10.64</vCOFINS></COFINSAliq></COFINS></imposto></det><total><ICMSTot><vBC>4640.00</vBC><vICMS>835.20</vICMS><vICMSDeson>0.00</vICMSDeson><vFCP>0.00</vFCP><vBCST>0.00</vBCST><vST>0.00</vST><vFCPST>0.00</vFCPST><vFCPSTRet>0.00</vFCPSTRet><vProd>4650.00</vProd><vFrete>0.00</vFrete><vSeg>0.00</vSeg><vDesc>10.00</vDesc><vII>0.00</vII><vIPI>0.00</vIPI><vIPIDevol>0.00</vIPIDevol><vPIS>76.56</vPIS><vCOFINS>352.64</vCOFINS><vOutro>0.00</vOutro><vNF>4640.00</vNF><vTotTrib>1395.00</vTotTrib></ICMSTot></total><transp><modFrete>9</modFrete></transp><cobr><fat><nFat>1234</nFat><vOrig>4650.00</vOrig><vDesc>10.00</vDesc><vLiq>4640.00</vLiq></fat><dup><nDup>001</nDup><dVenc>2026-11-28</dVenc><vDup>2320.00</vDup></dup><dup><nDup>002</nDup><dVenc>2026-12-28</dVenc><vDup>2320.00</vDup></dup></cobr><pag><detPag><tPag>15</tPag><vPag>4640.00</vPag></detPag></pag><infAdic><infCpl>Pedido 98765. Documento de exemplo, sem valor fiscal.</infCpl></infAdic></infNFe></NFe><protNFe versao=\"4.00\"><infProt><tpAmb>1</tpAmb><verAplic>SP_NFE_PL009_V4</verAplic><chNFe>35261011222333000181550010000012341123456787</chNFe><dhRecbto>2026-10-28T10:15:30-03:00</dhRecbto><nProt>135260000000001</nProt><digVal>abc=</digVal><cStat>100</cStat><xMotivo>Autorizado o uso da NF-e</xMotivo></infProt></protNFe></nfeProc>"]}'

from apify_client import ApifyClient

client = ApifyClient("<YOUR_API_TOKEN>")
run = client.actor("br_data_hub/br-nfe-xml-parser").call(run_input={'xmlTexts': ['<?xml version="1.0" encoding="UTF-8"?><nfeProc '
                                                   'xmlns="http://www.portalfiscal.inf.br/nfe" versao="4.00"><NFe><infNFe '
                                                   'Id="NFe35261011222333000181550010000012341123456787" '
                                                   'versao="4.00"><ide><cUF>35</cUF><cNF>12345678</cNF><natOp>Venda de '
                                                   'mercadoria</natOp><mod>55</mod><serie>1</serie><nNF>1234</nNF><dhEmi>2026-10-28T10:15:00-03:00</dhEmi><tpNF>1</tpNF><idDest>1</idDest><cMunFG>3550308</cMunFG><tpImp>1</tpImp><tpEmis>1</tpEmis><cDV>7</cDV><tpAmb>1</tpAmb><finNFe>1</finNFe><indFinal>1</indFinal><indPres>1</indPres><procEmi>0</procEmi><verProc>1.0</verProc></ide><emit><CNPJ>11222333000181</CNPJ><xNome>EXEMPLO '
                                                   'COMERCIO DE ELETRONICOS LTDA</xNome><xFant>Exemplo '
                                                   'Eletronicos</xFant><enderEmit><xLgr>Avenida '
                                                   'Paulista</xLgr><nro>1000</nro><xBairro>Bela '
                                                   'Vista</xBairro><cMun>3550308</cMun><xMun>Sao '
                                                   'Paulo</xMun><UF>SP</UF><CEP>01310100</CEP><cPais>1058</cPais><xPais>Brasil</xPais><fone>1130000000</fone></enderEmit><IE>110042490114</IE><CRT>3</CRT></emit><dest><CPF>12345678909</CPF><xNome>CONSUMIDOR '
                                                   'DE EXEMPLO</xNome><enderDest><xLgr>Rua das '
                                                   'Flores</xLgr><nro>10</nro><xBairro>Centro</xBairro><cMun>3550308</cMun><xMun>Sao '
                                                   'Paulo</xMun><UF>SP</UF><CEP>01001000</CEP></enderDest><indIEDest>9</indIEDest><email>consumidor@example.com</email></dest><det '
                                                   'nItem="1"><prod><cProd>NB-001</cProd><cEAN>7891234567895</cEAN><xProd>NOTEBOOK '
                                                   '15 POL 16GB '
                                                   'RAM</xProd><NCM>84713012</NCM><CFOP>5102</CFOP><uCom>UN</uCom><qCom>1.0000</qCom><vUnCom>4500.00</vUnCom><vProd>4500.00</vProd><cEANTrib>7891234567895</cEANTrib><uTrib>UN</uTrib><qTrib>1.0000</qTrib><vUnTrib>4500.00</vUnTrib><indTot>1</indTot></prod><imposto><vTotTrib>1350.00</vTotTrib><ICMS><ICMS00><orig>0</orig><CST>00</CST><modBC>3</modBC><vBC>4500.00</vBC><pICMS>18.00</pICMS><vICMS>810.00</vICMS></ICMS00></ICMS><IPI><cEnq>999</cEnq><IPINT><CST>53</CST></IPINT></IPI><PIS><PISAliq><CST>01</CST><vBC>4500.00</vBC><pPIS>1.65</pPIS><vPIS>74.25</vPIS></PISAliq></PIS><COFINS><COFINSAliq><CST>01</CST><vBC>4500.00</vBC><pCOFINS>7.60</pCOFINS><vCOFINS>342.00</vCOFINS></COFINSAliq></COFINS></imposto></det><det '
                                                   'nItem="2"><prod><cProd>MS-010</cProd><cEAN>SEM GTIN</cEAN><xProd>MOUSE '
                                                   'SEM '
                                                   'FIO</xProd><NCM>84716053</NCM><CFOP>5102</CFOP><uCom>UN</uCom><qCom>2.0000</qCom><vUnCom>75.00</vUnCom><vProd>150.00</vProd><cEANTrib>SEM '
                                                   'GTIN</cEANTrib><uTrib>UN</uTrib><qTrib>2.0000</qTrib><vUnTrib>75.00</vUnTrib><vDesc>10.00</vDesc><indTot>1</indTot></prod><imposto><vTotTrib>45.00</vTotTrib><ICMS><ICMS00><orig>0</orig><CST>00</CST><modBC>3</modBC><vBC>140.00</vBC><pICMS>18.00</pICMS><vICMS>25.20</vICMS></ICMS00></ICMS><PIS><PISAliq><CST>01</CST><vBC>140.00</vBC><pPIS>1.65</pPIS><vPIS>2.31</vPIS></PISAliq></PIS><COFINS><COFINSAliq><CST>01</CST><vBC>140.00</vBC><pCOFINS>7.60</pCOFINS><vCOFINS>10.64</vCOFINS></COFINSAliq></COFINS></imposto></det><total><ICMSTot><vBC>4640.00</vBC><vICMS>835.20</vICMS><vICMSDeson>0.00</vICMSDeson><vFCP>0.00</vFCP><vBCST>0.00</vBCST><vST>0.00</vST><vFCPST>0.00</vFCPST><vFCPSTRet>0.00</vFCPSTRet><vProd>4650.00</vProd><vFrete>0.00</vFrete><vSeg>0.00</vSeg><vDesc>10.00</vDesc><vII>0.00</vII><vIPI>0.00</vIPI><vIPIDevol>0.00</vIPIDevol><vPIS>76.56</vPIS><vCOFINS>352.64</vCOFINS><vOutro>0.00</vOutro><vNF>4640.00</vNF><vTotTrib>1395.00</vTotTrib></ICMSTot></total><transp><modFrete>9</modFrete></transp><cobr><fat><nFat>1234</nFat><vOrig>4650.00</vOrig><vDesc>10.00</vDesc><vLiq>4640.00</vLiq></fat><dup><nDup>001</nDup><dVenc>2026-11-28</dVenc><vDup>2320.00</vDup></dup><dup><nDup>002</nDup><dVenc>2026-12-28</dVenc><vDup>2320.00</vDup></dup></cobr><pag><detPag><tPag>15</tPag><vPag>4640.00</vPag></detPag></pag><infAdic><infCpl>Pedido '
                                                   '98765. Documento de exemplo, sem valor '
                                                   'fiscal.</infCpl></infAdic></infNFe></NFe><protNFe '
                                                   'versao="4.00"><infProt><tpAmb>1</tpAmb><verAplic>SP_NFE_PL009_V4</verAplic><chNFe>35261011222333000181550010000012341123456787</chNFe><dhRecbto>2026-10-28T10:15:30-03:00</dhRecbto><nProt>135260000000001</nProt><digVal>abc=</digVal><cStat>100</cStat><xMotivo>Autorizado '
                                                   'o uso da NF-e</xMotivo></infProt></protNFe></nfeProc>']})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

You can also schedule runs, send results to webhooks, or connect the Actor to Make, Zapier, n8n, Google Sheets and other integrations.

Use it with AI agents (MCP)

This Actor is ready for AI agents: typed input and output schemas, pay-per-event pricing, limited permissions and short runs.

• Apify MCP server: add https://mcp.apify.com/?tools=br_data_hub/br-nfe-xml-parser to Claude, ChatGPT, Cursor, VS Code or any MCP client, and the agent can call this Actor as a tool.
• Agent frameworks: call it from LangChain, LlamaIndex, CrewAI or the OpenAI Agents SDK through the Apify integrations, or with the API call above.
• Results come as structured JSON with stable field names, documented in the Output tab.

FAQ

Where does the data come from?

The Actor reads only the XML files you give it; nothing is sent to SEFAZ or any other service. It follows the NF-e layout 4.00 (Manual de Orientação do Contribuinte). The authorization status is the one written in the XML (protNFe): to confirm that an invoice was not cancelled later, check it on the SEFAZ portal.

How much does it cost?

$0.004 per invoice. Discounts follow your Apify subscription tier: Bronze 10%, Silver 20%, Gold and above 30%. See How much does it cost? above for examples.

Do I pay for errors or empty results?

No. Charged once per invoice parsed, with all its items included. Invalid files, failed downloads and non NF-e documents are free.

Can I run it on a schedule or connect it to other tools?

Yes. Use Apify schedules to run it daily or weekly, webhooks to get notified, and integrations such as Make, Zapier, n8n and Google Sheets. Everything also works through the API.

Can AI agents use it?

Yes. It works as a tool in the Apify MCP server and in agent frameworks, and AI agents can pay per event. See Use it with AI agents (MCP).

Is it legal to use this data?

The Actor reads only public, official sources and keeps personal data masked as the source publishes it. You are responsible for how you use the data, including LGPD compliance.

I found a bug or need a feature. What should I do?

Open an issue in the Issues tab. We answer within 14 days, usually much sooner.

More Actors from BR Data Hub

Actor	What it does
Brazil CNPJ Lookup API (Consulta CNPJ)	Look up Brazilian companies by CNPJ: registration status, partners (masked CPF), activities, tax regime and sc
Brazil Public Contracts API (PNCP Contratos)	Get Brazilian government contracts from PNCP, the official national procurement portal: buyer, supplier, objec
Brazil Open Tenders API (Licitações Abertas)	Find Brazilian government tenders that are open for proposals right now, from PNCP, the official national proc
Brazil Municipalities & IBGE Codes (Municípios)	List Brazilian municipalities, search them by name (accents and typos tolerated) or resolve IBGE codes
Brazil Holidays & Business Days (Feriados)	Brazilian national and state holidays for all 27 states, with the law behind each one
Brazil Banks & Pix Directory (Bancos e ISPB)	Every Brazilian bank and payment institution from official Banco Central lists: ISPB, COMPE bank code, short a
Brazil Boleto Validator & Parser (Boleto)	Validate Brazilian boletos in bulk (digitable line or barcode, bank and utility/tax slips): check digits per f

See all our Actors at apify.com/br_data_hub.

Usar em português

Converte XML de NF-e e NFC-e em JSON ou em uma linha por item, pronto para planilha: emitente, destinatário, produtos com NCM, CFOP, GTIN, ICMS, IPI, PIS e COFINS, totais, formas de pagamento, duplicatas e protocolo da SEFAZ. A chave de acesso é validada pelo dígito verificador. CPF de pessoa física sai sempre mascarado. Cobrança por nota lida; arquivos inválidos não são cobrados.

Quanto custa: $0.004 por resultado (invoice); 1.000 resultados saem por $4.00. Desconto pelo nível da assinatura Apify: Bronze 10%, Silver 20%, Gold ou acima 30%. Erros e consultas sem resultado não são cobrados. Use também pela API ou por agentes de IA no servidor MCP da Apify (https://mcp.apify.com/?tools=br_data_hub/br-nfe-xml-parser).