# Consulta e Download NFe por Chave de Acesso - XML + DANFE PDF (`brasildados/api-consulta-nfe-por-chave`) Actor

Consulte e baixe qualquer 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 - API & Data](https://apify.com/brasildados) (community)
- **Categories:** E-commerce, Integrations, Other
- **Stats:** 53 total users, 12 monthly users, 98.4% runs succeeded, 2 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

$40.00 / 1,000 nfe encontrada / nfe invoice founds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### Consulta NF-e por chave de acesso: XML e DANFE sem certificado digital

Informe a **chave de acesso** de uma ou várias **Notas Fiscais Eletrônicas (NF-e)** e receba, para cada nota encontrada, o **link para baixar o XML completo**, o **link para baixar o DANFE em PDF** e os principais dados da nota: modelo, série, número, natureza da operação, data de emissão e tipo de operação (entrada ou saída).

**Não precisa de certificado digital**, login na SEFAZ nem cadastro no portal da nota. Basta a chave de 44 caracteres que aparece no DANFE, no XML ou no QR Code da nota.

Você pode usar pelo Console da Apify, com poucos cliques, ou integrar pela API em sistemas de ERP, contabilidade, conciliação fiscal, logística e automações (Make, n8n, Zapier).

### Para que serve

- **Recuperar o XML de notas recebidas** para escrituração, contabilidade ou importação no ERP.
- **Gerar o DANFE em PDF** de uma nota a partir só da chave de acesso.
- **Conferir dados de uma nota** (número, série, data de emissão, natureza da operação) antes de dar entrada em mercadoria ou pagar um fornecedor.
- **Automatizar a entrada de notas** em lote: até 50 chaves por execução, todas processadas em paralelo.

### Como usar

#### Pelo Console da Apify

1. Abra o Actor e vá até a aba **Input**.
2. No campo **Chaves de acesso**, cole uma chave por linha (de 1 a 50).
3. Clique em **Start**.
4. Abra a aba **Output** (ou **Dataset**). Cada nota encontrada vira uma linha.
5. Clique no link de `xmlUrl` para baixar o XML ou de `danfeUrl` para baixar o PDF.

#### Formato da chave

A chave de acesso da NF-e tem **44 caracteres**. Você pode colar do jeito que tiver:

| Formato colado | Entende como |
|---|---|
| `35260444823938000187551090000002691092067649` | a chave |
| `3526 0444 8239 3800 0187 5510 9000 0002 6910 9206 7649` (com espaços, como no DANFE) | a mesma chave |
| `NFe35260444823938000187551090000002691092067649` (com o prefixo do XML) | a mesma chave |

Espaços, pontos, traços e o prefixo `NFe` são removidos antes da consulta. A mesma chave informada em formatos diferentes é consultada e cobrada **uma única vez**. Chaves de CNPJ alfanumérico (com letras na parte do CNPJ) também são aceitas.

### Entrada

| Campo | Obrigatório | Descrição |
|---|---|---|
| `chaves` | Sim | Lista de 1 a 50 chaves de acesso de NF-e, com ou sem formatação. |

Exemplo:

```json
{
  "chaves": [
    "35260444823938000187551090000002691092067649"
  ]
}
```

### Usar pela API

Rode e receba as notas na mesma chamada:

```bash
curl -X POST "https://api.apify.com/v2/acts/brasildados~api-consulta-nfe-por-chave/run-sync-get-dataset-items" \
  -H "Authorization: Bearer SEU_TOKEN_APIFY" \
  -H "Content-Type: application/json" \
  -d '{"chaves":["35260444823938000187551090000002691092067649"]}'
```

A resposta é a lista de notas em JSON, no formato da seção **Dados entregues**. Use o endpoint `run-sync-get-dataset-items`: ele devolve as notas. O endpoint `run-sync` devolve apenas o link do Dataset.

Para lotes, envie várias chaves na mesma chamada (até 50). Para mais de 50 chaves, divida em várias execuções.

Em Python, com o cliente oficial:

```python
from apify_client import ApifyClient

client = ApifyClient("SEU_TOKEN_APIFY")
run = client.actor("brasildados/api-consulta-nfe-por-chave").call(
    run_input={"chaves": ["35260444823938000187551090000002691092067649"]}
)
for nota in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(nota["numero"], nota["xmlUrl"], nota["danfeUrl"])
```

### Dados entregues

Cada NF-e encontrada gera **uma linha** no Dataset. Exemplo real:

```json
{
  "xmlUrl": "https://api.apify.com/v2/key-value-stores/.../records/xml-35260444823938000187551090000002691092067649?signature=...",
  "danfeUrl": "https://api.apify.com/v2/key-value-stores/.../records/danfe-35260444823938000187551090000002691092067649?signature=...",
  "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><nfeProc versao=\"4.00\" ...>...</nfeProc>",
  "chave": "35260444823938000187551090000002691092067649",
  "modelo": "55",
  "serie": "109",
  "numero": "269",
  "naturezaOperacao": "VENDA",
  "dataEmissao": "2026-04-15T18:26:21-03:00",
  "tipoOperacao": "saída",
  "consultadoEm": "2026-09-19T11:52:10.412Z",
  "erro": null
}
```

| Campo | Descrição |
|---|---|
| `xmlUrl` | Link para baixar o XML completo da NF-e. |
| `danfeUrl` | Link para baixar o DANFE em PDF. Pode vir `null` se o PDF não puder ser gerado naquele momento; o XML continua disponível. |
| `xml` | Conteúdo completo (raw) do XML da NF-e, para importar direto sem baixar o arquivo. Aparece na visão **Todos os campos**. |
| `chave` | Chave de acesso consultada, só com os 44 caracteres. |
| `modelo` | Modelo fiscal informado no XML (ex.: `55`). |
| `serie` | Série da nota. |
| `numero` | Número da nota. |
| `naturezaOperacao` | Natureza da operação (ex.: `VENDA`). |
| `dataEmissao` | Data e hora de emissão (`dhEmi` do XML), com fuso horário. |
| `tipoOperacao` | `entrada` ou `saída`, conforme o XML. |
| `consultadoEm` | Data e hora da consulta (ISO 8601, UTC). |
| `erro` | Sempre `null` nas linhas entregues. |

O XML completo (emitente, destinatário, produtos, impostos, totais) está no arquivo de `xmlUrl`. Ele não é repetido dentro do Dataset, para a linha continuar leve e fácil de exportar em CSV ou Excel.

#### Sobre os links do XML e do DANFE

- Os links abrem **sem token da Apify**, então podem ser repassados para o seu sistema ou para outra pessoa.
- Os arquivos ficam no armazenamento da execução e seguem o **período de retenção de dados da sua conta Apify**. Se precisar dos arquivos por mais tempo, baixe e guarde no seu sistema.

### O que é cobrado

A cobrança é **por nota entregue no Dataset**. Veja o preço vigente na aba **Pricing**.

| Situação | Gera linha? | Cobra? |
|---|---|---|
| Nota encontrada, com XML | Sim | Sim |
| Nota encontrada, XML ok e DANFE indisponível | Sim (`danfeUrl: null`) | Sim |
| Mesma chave repetida no lote | Uma linha só | Uma vez |
| Chave fora do formato (não tem 44 caracteres válidos) | Não | Não |
| Chave válida, mas nota não encontrada na origem | Não | Não |
| Nota localizada, mas XML indisponível na origem | Não | Não |
| Origem fora do ar ou lenta demais | Não | Não |

As chaves que não geram linha aparecem com um aviso no log da execução. Uma chave com problema não interrompe as outras.

Você pode definir um limite de gasto por execução (**Maximum cost per run**). Quando ele é atingido, a execução para e as chaves seguintes não são consultadas nem cobradas.

### Limites

- De 1 a 50 chaves por execução. Um lote com mais de 50 é recusado antes de começar; divida em várias execuções.
- A consulta depende da disponibilidade da origem. Em raras exceções, uma nota válida não retorna naquele momento; tente de novo mais tarde.
- Atende NF-e. Não consulta NFS-e (nota de serviço municipal).

### Perguntas frequentes

**Preciso de certificado digital?**
Não. Basta a chave de acesso.

**A mesma chave em dois formatos é cobrada duas vezes?**
Não. O Actor remove a formatação antes de consultar e consulta cada chave uma única vez.

**Por que uma chave não retornou nada?**
Veja o aviso no log da execução: a chave pode estar fora do formato, a nota pode não existir na origem ou a origem pode estar indisponível naquele momento. Nesses casos não há cobrança.

### Actors relacionados da BrasilDados

- [Consulta CT-e por chave de acesso](https://apify.com/brasildados/api-consulta-cte-por-chave?fpr=t5lwzq) para conhecimentos de transporte.
- [Baixar NF-es em lote](https://apify.com/brasildados/baixar-nfes-lote-api?fpr=t5lwzq) para volumes maiores.
- [Todos os Actors da BrasilDados](https://apify.com/brasildados?fpr=t5lwzq).

### Suporte

Encontrou um resultado diferente do descrito aqui? Abra uma issue na aba **Issues** do Actor com a chave consultada e o ID da execução. Não inclua tokens ou outras credenciais.

# Actor input Schema

## `chaves` (type: `array`):

Chaves de acesso da **NF-e** (44 caracteres), de 1 a 50 por execução. Pode colar com ou sem formatação: prefixo `NFe`, espaços, pontos e traços são removidos. Chaves repetidas são consultadas e cobradas uma única vez.

NF-e access keys (44 characters), 1 to 50 per run. Paste them with or without formatting: the `NFe` prefix, spaces, dots and dashes are removed. Repeated keys are looked up and charged only once.

## Actor input object example

```json
{
  "chaves": [
    "NFe35260444823938000187551090000002691092067649"
  ]
}
```

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "chaves": [
        "NFe35260444823938000187551090000002691092067649"
    ]
};

// 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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "chaves": ["NFe35260444823938000187551090000002691092067649"] }

# 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(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).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": [
    "NFe35260444823938000187551090000002691092067649"
  ]
}' |
apify call brasildados/api-consulta-nfe-por-chave --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,brasildados/api-consulta-nfe-por-chave"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/cgLcAbd5um7w5W4G1/builds/I7uCQgRoTob7eYqID/openapi.json