# Consulta NFe por Chave de Acesso - XML e DANFE PDF (`brasildados/api-consulta-nfe-por-chave`) Actor
Consulte a Nota Fiscal Eletrônica (NF-e) pela chave de acesso e receba o XML completo da nota e o DANFE em PDF. Modelo 55, em lote ou API REST. Exporte em JSON, CSV ou Excel, rode via API e agende. | NFe lookup by 44-digit access key: full NFe XML and DANFE PDF.
- **URL**: https://apify.com/brasildados/api-consulta-nfe-por-chave.md
- **Developed by:** [BrasilDados.org](https://apify.com/brasildados) (community)
- **Categories:** E-commerce, Integrations
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet
## Pricing
from $70.00 / 1,000 nfe encontrada / nfe invoice founds
This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.
Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event
## What's an Apify Actor?
Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".
## How to integrate an Actor?
If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.
In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):
```bash
npm install apify-client
```
In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):
```bash
pip install apify-client
```
In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):
````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash
In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).
If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).
For usage examples, see the [API](#api) section below.
For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).
# README
### Consulta NFe por Chave de Acesso
**Consulta NFe por Chave de Acesso** é uma API para consultar a **Nota Fiscal Eletrônica (NF-e, modelo 55)** no Brasil a partir da **chave de acesso de 44 dígitos**. Informe a chave e receba o **XML completo** da nota (layout `nfeProc` 4.00) em um único campo, mais **links de download** prontos para o **XML** e o **DANFE em PDF**. Cada chave gera um registro estruturado com a situação da consulta, pronto para escrituração fiscal, conciliação contábil, validação de notas e integração com ERP. Processe **até 50 chaves** por execução e exporte em **JSON, CSV, Excel ou XML**, rode via **API**, agende e monitore execuções, use **webhooks** ou consulte em tempo real pela **API REST Standby** (`POST /check`). Chave com dígito verificador inválido falha localmente, **sem cobrança**.
### Casos de uso
- **Escrituração fiscal:** capturar o XML da NF-e pela chave para SPED, EFD e obrigações acessórias
- **Conciliação contábil:** validar notas recebidas e cruzar valores com lançamentos
- **Validação e antifraude:** confirmar autorização (protocolo e situação) direto da origem
- **Importação para ERP:** trazer o XML completo da nota pronto para importar
- **Auditoria em lote:** processar centenas de chaves e exportar para planilha ou data lake
- **Download com um clique:** baixar o XML e o DANFE em PDF de cada nota pelos links retornados
### O que este Actor retorna?
| | |
|---|---|
| 🧾 **XML completo** | `xml.data` com o `nfeProc` (layout 4.00) inteiro, sem alterações |
| 📥 **Download do XML** | `xmlUrl`: link público para baixar o XML com um clique |
| 📄 **Download do DANFE** | `danfeUrl`: link público para baixar o DANFE em PDF |
| 🔑 **Identificação** | `chave`, `encontrado`, `consultadoEm`, `referenciaConsulta` |
| ⚠️ **Erros** | `erro` claro para chave inválida ou nota não localizada |
### Por que usar este Actor?
- 🧾 **Só a chave:** a chave de acesso de 44 dígitos é tudo o que você precisa informar
- 📥 **XML inteiro:** a nota completa em um campo só, estável a mudanças de layout
- 🔗 **Links de download:** XML (`xmlUrl`) e DANFE em PDF (`danfeUrl`) prontos para clicar, em toda nota encontrada
- 📤 **Lote:** até **50 chaves** por execução, com exportação em JSON, CSV, Excel ou XML
- ⚡ **API Standby:** `POST /check` para ERP, contabilidade e automações em tempo real
- 💰 **Cobrança justa:** só nota com `encontrado: true`; chave inválida não é cobrada
### Como consultar NFe em lote
1. Abra o actor no [Console Apify](https://console.apify.com/) na aba **Input**.
2. Cole as chaves na lista **`chaves`** (uma por linha, 44 dígitos cada).
3. Clique em **Start** e exporte o Dataset em **JSON**, **CSV** ou **XLSX**.
**Exemplo de entrada:**
```json
{
"chaves": ["35260444823938000187551090000002691092067649"]
}
````
### Exemplo de saída
```json
{
"chave": "35260444823938000187551090000002691092067649",
"encontrado": true,
"consultadoEm": "2026-06-03T11:00:00.000Z",
"referenciaConsulta": "bd-af03c0f94e82",
"xml": {
"name": "NFE-35260444823938000187551090000002691092067649.xml",
"type": "NFE",
"format": "XML",
"data": "..."
},
"xmlUrl": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/xml-35260444823938000187551090000002691092067649?signature=...",
"danfeUrl": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/danfe-35260444823938000187551090000002691092067649?signature=...",
"erro": null
}
```
### API Standby (consulta em tempo real)
Mantenha o actor em **Standby** e consulte a NF-e por uma requisição REST:
```bash
curl -X POST "https://brasildados--api-consulta-nfe-por-chave.apify.actor/check?token=SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"chaves":["35260444823938000187551090000002691092067649"]}'
```
Retorna um array com um registro por chave, ideal para integrar em ERP, sistemas contábeis e fluxos antifraude.
### Perguntas frequentes
**Preciso informar mais alguma coisa além da chave?**
Não. A chave de acesso de 44 dígitos é o único dado obrigatório.
**O actor parseia os campos do XML?**
Nesta versão, não. O XML completo é entregue em um campo só (`xml.data`), o que mantém o actor estável a mudanças de layout. Você parseia exatamente os campos que precisar.
**Como baixo o XML e o DANFE?**
Toda nota encontrada já vem com `xmlUrl` (download do XML) e `danfeUrl` (download do DANFE em PDF). São links públicos clicáveis, sem precisar de token. A validade segue o período de retenção do run, então baixe dentro desse prazo se precisar arquivar.
**Funciona com notas antigas?**
A consulta é feita pela chave de acesso, sem janela de data fixa. Notas não localizadas na origem retornam `encontrado: false`.
**Quando há cobrança?**
Apenas quando a nota é encontrada (`encontrado: true`). Chave inválida ou não localizada não é cobrada.
**Posso usar via API e agendamento?**
Sim. Rode por API, agende execuções, configure webhooks ou use a API Standby para tempo real, tudo pela plataforma Apify.
***
### 🇬🇧 English
#### Brazilian NFe Lookup by Access Key
Look up a Brazilian electronic invoice (**NF-e, model 55**) by its **44-digit access key** and get the **full NFe XML** (`nfeProc` 4.00 layout) in a single field, plus ready-to-use **download links** for the **XML** (`xmlUrl`) and the **DANFE PDF** (`danfeUrl`). Each key returns one structured record with the lookup status, ready for tax bookkeeping, accounting reconciliation, invoice validation and ERP integration. Process **up to 50 keys** per run and export to **JSON, CSV, Excel or XML**, run via **API**, schedule and monitor runs, use **webhooks**, or query in real time through the **Standby REST API** (`POST /check`). An invalid check digit fails locally, with no charge.
**Use cases**
- Capture the NF-e XML by access key for tax bookkeeping and accessory obligations
- Reconcile received invoices and cross-check totals with accounting entries
- Confirm authorization (protocol and status) straight from the source for anti-fraud
- Import the complete invoice XML into your ERP
- Audit hundreds of keys in batch and export to spreadsheets or a data lake
- Download the XML and DANFE PDF of each note with a single click
This version does not parse XML fields - it delivers the complete XML so your system can parse exactly what it needs, staying resilient to layout changes. Billing only applies when the note is found (`encontrado: true`).
***
📧 **contato@brasildados.org** · 🌐 **[brasildados.org](https://brasildados.org)**
# Actor input Schema
## `chaves` (type: `array`):
Chaves de acesso da **NF-e** (44 dígitos, modelo 55). Pontuação e espaços são ignorados. Inválidas: erro local sem cobrança. Máx. 50. | NF-e access keys (44 digits, model 55). Punctuation ignored. Max 50.
## Actor input object example
```json
{
"chaves": [
"35260444823938000187551090000002691092067649"
]
}
```
# Actor output Schema
## `resultados` (type: `string`):
URL da API Apify para baixar os itens do dataset.
# API
You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.
## JavaScript example
```javascript
import { ApifyClient } from 'apify-client';
// Initialize the ApifyClient with your Apify API token
// Replace the '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {
"chaves": [
"35260444823938000187551090000002691092067649"
]
};
// Run the Actor and wait for it to finish
const run = await client.actor("brasildados/api-consulta-nfe-por-chave").call(input);
// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
console.dir(item);
});
// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs
```
## Python example
```python
from apify_client import ApifyClient
# Initialize the ApifyClient with your Apify API token
# Replace '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = { "chaves": ["35260444823938000187551090000002691092067649"] }
# Run the Actor and wait for it to finish
run = client.actor("brasildados/api-consulta-nfe-por-chave").call(run_input=run_input)
# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
print(item)
# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start
```
## CLI example
```bash
echo '{
"chaves": [
"35260444823938000187551090000002691092067649"
]
}' |
apify call brasildados/api-consulta-nfe-por-chave --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=brasildados/api-consulta-nfe-por-chave",
"--header",
"Authorization: Bearer "
]
}
}
}
```
## OpenAPI specification
```json
{
"openapi": "3.0.1",
"info": {
"title": "Consulta NFe por Chave de Acesso - XML e DANFE PDF",
"description": "Consulte a Nota Fiscal Eletrônica (NF-e) pela chave de acesso e receba o XML completo da nota e o DANFE em PDF. Modelo 55, em lote ou API REST. Exporte em JSON, CSV ou Excel, rode via API e agende. | NFe lookup by 44-digit access key: full NFe XML and DANFE PDF.",
"version": "1.0",
"x-build-id": "wEfleUdsFE4OoBftu"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/brasildados~api-consulta-nfe-por-chave/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-brasildados-api-consulta-nfe-por-chave",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/acts/brasildados~api-consulta-nfe-por-chave/runs": {
"post": {
"operationId": "runs-sync-brasildados-api-consulta-nfe-por-chave",
"x-openai-isConsequential": false,
"summary": "Executes an Actor and returns information about the initiated run in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/runsResponseSchema"
}
}
}
}
}
}
},
"/acts/brasildados~api-consulta-nfe-por-chave/run-sync": {
"post": {
"operationId": "run-sync-brasildados-api-consulta-nfe-por-chave",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
}
},
"components": {
"schemas": {
"inputSchema": {
"type": "object",
"required": [
"chaves"
],
"properties": {
"chaves": {
"title": "Chaves de acesso / Access keys",
"minItems": 1,
"maxItems": 50,
"type": "array",
"description": "Chaves de acesso da **NF-e** (44 dígitos, modelo 55). Pontuação e espaços são ignorados. Inválidas: erro local sem cobrança. Máx. 50. | NF-e access keys (44 digits, model 55). Punctuation ignored. Max 50.",
"items": {
"type": "string"
}
}
}
},
"runsResponseSchema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"actId": {
"type": "string"
},
"userId": {
"type": "string"
},
"startedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"finishedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"status": {
"type": "string",
"example": "READY"
},
"meta": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"example": "API"
},
"userAgent": {
"type": "string"
}
}
},
"stats": {
"type": "object",
"properties": {
"inputBodyLen": {
"type": "integer",
"example": 2000
},
"rebootCount": {
"type": "integer",
"example": 0
},
"restartCount": {
"type": "integer",
"example": 0
},
"resurrectCount": {
"type": "integer",
"example": 0
},
"computeUnits": {
"type": "integer",
"example": 0
}
}
},
"options": {
"type": "object",
"properties": {
"build": {
"type": "string",
"example": "latest"
},
"timeoutSecs": {
"type": "integer",
"example": 300
},
"memoryMbytes": {
"type": "integer",
"example": 1024
},
"diskMbytes": {
"type": "integer",
"example": 2048
}
}
},
"buildId": {
"type": "string"
},
"defaultKeyValueStoreId": {
"type": "string"
},
"defaultDatasetId": {
"type": "string"
},
"defaultRequestQueueId": {
"type": "string"
},
"buildNumber": {
"type": "string",
"example": "1.0.0"
},
"containerUrl": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "integer",
"example": 1
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
},
"usageTotalUsd": {
"type": "number",
"example": 0.00005
},
"usageUsd": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "number",
"example": 0.00005
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
}
}
}
}
}
}
}
}
```