Baixar NFes em Lote: XML + DANFE PDF em ZIP - API

O que faz o Baixar NF-e em Lote?

O Baixar NF-e em Lote consulta chaves de acesso de NF-e modelo 55 e entrega um único arquivo ZIP com os documentos encontrados. Envie várias chaves em uma execução, receba XMLs e DANFEs organizados e acompanhe um resumo simples no Dataset. O fluxo não exige certificado digital e foi pensado para contadores, equipes fiscais, ERPs, conciliações e rotinas de arquivamento eletrônico.

O Actor valida cada chave, consulta as notas em paralelo e reúne os arquivos disponíveis em nfe-lote.zip. O Dataset padrão recebe somente uma linha de resumo por execução. Assim, uma execução com muitas notas não cria dezenas de linhas difíceis de relacionar. O ZIP contém os documentos e um manifest.json com o resultado individual de cada chave, incluindo chaves inválidas e notas não encontradas.

O arquivo é armazenado no Key-Value Store da execução. O campo zipUrl do Dataset aponta diretamente para esse arquivo. Use o link durante a retenção da execução ou baixe o ZIP para o seu próprio sistema quando precisar de armazenamento permanente.

Por que usar o Baixar NF-e em Lote?

• 📦 Um único ZIP por lote: XMLs e DANFEs ficam agrupados em pastas previsíveis.
• ⚡ Processamento paralelo: várias chaves são consultadas na mesma execução, reduzindo o trabalho de integração.
• 🧾 Sem certificado digital: informe somente as chaves de acesso que deseja consultar.
• 🔎 Resultado auditável: o manifesto registra o status, o horário, a referência da consulta e a disponibilidade de XML e DANFE.
• 📊 Dataset simples: a saída principal tem uma linha com o link do ZIP e os totais da execução.
• 💳 Cobrança alinhada ao resultado: somente NF-es localizadas e baixadas geram cobrança. Chaves inválidas e notas não encontradas não geram cobrança.
• 🔗 Integração por API: o mesmo formato pode ser usado no Console da Apify ou em uma chamada HTTP.

O limite é de até 30 chaves por execução. Para uma quantidade maior, divida as chaves em lotes e execute chamadas sequenciais. O limite também ajuda a manter o tamanho do ZIP e o tempo de processamento previsíveis.

Como usar o Baixar NF-e em Lote

1. Prepare as chaves. Separe as chaves de acesso com 44 a 47 caracteres. Letras e números são preservados; espaços e pontuação podem ser enviados, pois são removidos durante o processamento.
2. Abra o Actor. No Console da Apify, informe as chaves no campo de entrada. Você pode colar uma chave por linha ou enviar uma lista pelo JSON da API.
3. Inicie a execução. Clique em Save & Start. O Actor valida as chaves, consulta as notas e monta o ZIP.
4. Confira o resumo. Na aba Output, leia totalEncontradas, totalNaoEncontradas e totalInvalidas.
5. Baixe os documentos. Abra o link de zipUrl para baixar nfe-lote.zip. Dentro do arquivo, consulte xmls/, danfes/ e manifest.json.
6. Automatize quando necessário. Use o endpoint de execução síncrona para receber o item do Dataset diretamente em sua aplicação.

Se uma chave inválida estiver misturada com chaves válidas, o Actor avisa sobre a entrada inválida e continua com as demais. Uma nota não encontrada também permanece registrada no manifesto, sem criar um arquivo vazio.

Input

Informe uma lista de chaves de acesso. Cada chave deve ter entre 44 e 47 caracteres alfanuméricos após a normalização. Se houver mais de 30 chaves válidas, somente as primeiras 30 serão processadas.

{
  "chaves": [
    "35260444823938000187551090000002691092067649",
    "35260444823938000187551090000002691092067650"
  ]
}

Campo	Tipo	Obrigatório	Descrição
chaves	lista de textos	Não	Chaves de acesso NF-e com 44 a 47 caracteres. Letras e números são preservados; espaços e pontuação são ignorados. O máximo é de 30 chaves válidas por execução.
chave	texto	Não	Uma única chave de acesso para facilitar chamadas pela API.

Na API, envie o mesmo objeto JSON no corpo da requisição. O exemplo abaixo usa o endpoint oficial de execução síncrona:

curl -X POST "https://api.apify.com/v2/acts/brasildados~baixar-nfes-lote-api/run-sync-get-dataset-items" \
  -H "Authorization: Bearer SEU_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chaves":["35260444823938000187551090000002691092067649"]}'

Substitua SEU_APIFY_TOKEN pelo token da sua conta e mantenha-o no header Authorization. Não coloque credenciais na URL, no código-fonte ou em arquivos compartilhados.

Para uma única chave, também é possível enviar:

{
  "chave": "35260444823938000187551090000002691092067649"
}

Output

O Dataset padrão contém exatamente uma linha de resumo por execução. Essa linha não repete os dados de cada NF-e. Use zipUrl para baixar o arquivo ZIP, que contém os XMLs, os DANFEs disponíveis e o manifesto completo.

{
  "zipUrl": "https://api.apify.com/v2/key-value-stores/<store-id>/records/nfe-lote.zip?signature=<assinatura-temporaria>",
  "totalChaves": 1,
  "totalEncontradas": 1,
  "totalNaoEncontradas": 0,
  "totalInvalidas": 0,
  "geradoEm": "2026-09-15T13:58:27.060Z"
}

O ZIP usa esta organização:

nfe-lote.zip
├── xmls/
│   └── 35260444...xml    <- XML completo da NF-e
├── danfes/
│   └── 35260444...pdf    <- DANFE em PDF
└── manifest.json          <- detalhes de todas as chaves processadas

• xmls/: XML completo de cada NF-e encontrada.
• danfes/: DANFE em PDF quando disponível.
• manifest.json: detalhes de todas as chaves processadas, inclusive inválidas e não encontradas.

O manifesto é o local indicado para auditoria detalhada. Ele identifica a chave, informa se a NF-e foi encontrada, registra quando a consulta ocorreu e indica se XML e DANFE foram incluídos. O Dataset pode ser baixado pela Apify em JSON, CSV ou Excel, mas o documento fiscal e seus detalhes devem ser obtidos pelo ZIP.

Campos retornados

Campo	Tipo	Significado
zipUrl	texto	URL para baixar o ZIP da execução. O acesso depende da autorização da conta que executou o Actor e da retenção configurada para a execução.
totalChaves	inteiro	Quantidade total de chaves recebidas, incluindo válidas e inválidas.
totalEncontradas	inteiro	Quantidade de NF-es localizadas e baixadas. Essas são as NF-es que geram cobrança.
totalNaoEncontradas	inteiro	Quantidade de chaves válidas para as quais nenhuma NF-e foi localizada.
totalInvalidas	inteiro	Quantidade de chaves rejeitadas por comprimento fora de 44 a 47 caracteres.
geradoEm	data e hora	Momento em que o ZIP e o resumo foram gerados, no formato ISO 8601.

Os campos encontrado, temXml, temDanfe, consultadoEm, referenciaConsulta e erro pertencem aos registros do manifesto. Eles não aparecem na linha resumida do Dataset porque podem existir várias entradas para uma única execução.

Tips / Dicas

• ✅ Separe lotes grandes: use até 30 chaves por execução para manter o processamento previsível.
• 🧹 Normalize antes de enviar: remover espaços e pontuação no seu sistema facilita a conferência, embora o Actor também faça essa normalização.
• 📁 Baixe o ZIP logo após a execução: o link segue a política de retenção da execução na Apify. Para arquivamento fiscal, copie o arquivo para o seu armazenamento.
• 🔍 Use o manifesto para reconciliação: compare totalEncontradas, totalNaoEncontradas e totalInvalidas com as entradas do manifest.json.
• 🧾 Não trate o Dataset como a lista de documentos: ele é um resumo por execução. Os documentos e o detalhamento por chave estão no ZIP.
• 💳 Controle o volume enviado: somente NF-es efetivamente encontradas são cobradas, mas dividir lotes ajuda a identificar rapidamente erros de entrada.
• 🔐 Proteja o link e o token: o zipUrl dá acesso aos arquivos da execução para quem tiver autorização adequada.

FAQ, avisos e suporte

Quais documentos são suportados?

O Actor é destinado a NF-e modelo 55, utilizada para documentar operações com mercadorias. NFS-e e CT-e possuem estruturas e finalidades diferentes. Para CT-e, use o Actor relacionado indicado abaixo.

O que acontece com uma chave inválida?

Ela é ignorada para a consulta, recebe um aviso no log e aparece no manifesto com o motivo da invalidação. O processamento continua com as chaves restantes e não há cobrança por essa entrada.

O que acontece quando a NF-e não é encontrada?

A chave válida fica registrada como não encontrada no manifesto. O resumo incrementa totalNaoEncontradas, não cria um XML ou PDF vazio e não há cobrança por essa entrada.

E se o XML existir sem DANFE?

O XML disponível é incluído no ZIP. O manifesto informa temXml: true e temDanfe: false, permitindo que seu processo diferencie documento XML disponível de PDF ausente.

Por quanto tempo o ZIP fica disponível?

O link segue a política de retenção da execução e do plano da Apify. Baixe o arquivo e mantenha uma cópia em seu ambiente quando houver obrigação de arquivamento.

Posso usar os documentos para qualquer finalidade?

Você é responsável por garantir autorização para consultar, baixar, armazenar e tratar as chaves e documentos enviados. Use os arquivos de acordo com a legislação aplicável, as regras fiscais e as políticas de proteção de dados da sua organização.

Precisa de ajuda?

Abra uma solicitação na aba Issues do Actor ou fale com a equipe pelo contato abaixo. Para integrações com ERPs, rotinas fiscais e volumes recorrentes, descreva o formato esperado e o fluxo de trabalho.

Outros Actors do BrasilDados

Actor	Quando usar
Consulta NF-e por Chave	Consultar uma NF-e individual com dados estruturados.
Baixar CT-e em Lote	Baixar XMLs e DACTEs de vários conhecimentos de transporte.
API Reputação de Empresas por CNPJ	Enriquecer análises cadastrais e de reputação empresarial.

🛒 Todos os Actors: apify.com/brasildados

English summary

This Actor validates up to 30 Brazilian NF-e model 55 access keys, downloads available XML and DANFE files, and stores them in one ZIP. The default Dataset contains one summary row per run. Use zipUrl to download the ZIP and inspect manifest.json for per-key details. Invalid and not-found keys are not billed. Use the API example above with an Apify token in the Authorization: Bearer header.

📧 contato@brasildados.org · 🌐 brasildados.org · 🛒 BrasilDados na Apify Store