Como baixar o XML de vários CT-e pelas chaves de acesso (Python e Node.js)?
Script pronto com o SDK oficial: uma requisição por chave, poucas ao mesmo tempo, um arquivo .xml por CT-e e retomada de onde parou.
Atualizado em
Não existe lote no CT-e: o script desta página faz uma chamada a POST /api/consultar-cte-xml por chave, poucas ao mesmo tempo, grava um arquivo .xml por CT-e e, se parar (queda, saldo, Ctrl+C), continua de onde parou.
- Custo: só o XML entregue é cobrado. R$ 0,30 no Starter, R$ 0,195 no Pro e R$ 0,05 no Enterprise, com os créditos do plano (tabela).
- Precisa: o certificado A1 (e-CNPJ ou e-CPF) de quem participa dos CT-e (emitente, tomador, remetente, destinatário, expedidor ou recebedor) e a senha dele.
- Para testar: a API pede plano ou créditos extras, a partir de R$ 50 por mês. No painel, sem programar, a conta sem plano tem 10 XML grátis por mês, uma chave por vez (condições).
- Comece: crie a conta e a chave de API.
Contrato completo da rota (campos, códigos de erro): XML de CT-e pela chave.
Antes de começar
- Python 3.9 ou mais novo, ou Node.js 18 ou mais novo. SDK
fiscalapi-brna versão 0.3.0 ou mais nova (é a que tem o método de CT-e). - A chave de API na variável
FISCALAPI_API_KEYe a senha do certificado emCERT_SENHA. - O certificado em
certificado.pfx, na mesma pasta do script. - Um arquivo
chaves.txtcom uma chave por linha. Pontos, espaços e o prefixoCTedo Id do XML são aceitos.
pip install "fiscalapi-br>=0.3.0" # Python
npm install fiscalapi-br@^0.3.0 # Node.js
export FISCALAPI_API_KEY="fapi_sua_chave_aqui"
export CERT_SENHA="senha-do-certificado"Cada chave usa um certificado só. Se os CT-e são de empresas diferentes, separe as chaves por certificado e rode o script uma vez para cada um, cada um na sua pasta.
O script em Python
Salve como baixar_cte.py:
"""Baixa o XML de uma lista de CT-e pela chave de acesso, com retomada."""
import json
import os
import sys
import threading
import time
from concurrent.futures import ThreadPoolExecutor
from datetime import datetime, timezone
from fiscalapi_br import (
APIConnectionError,
AuthenticationError,
BadRequestError,
FiscalAPI,
InsufficientBalanceError,
RateLimitError,
ServerError,
)
ENTRADA = "chaves.txt" # uma chave por linha
PASTA = "xml" # um arquivo <chave>.xml por CT-e baixado
SAIDA = "resultado.jsonl" # uma linha por chave concluída (é também o checkpoint)
FALHAS = "falhas.jsonl" # falhas passageiras: entram de novo na próxima rodada
SIMULTANEAS = 3 # chamadas ao mesmo tempo
TENTATIVAS = 5 # por chave, em 429 e 503
api = FiscalAPI(max_retries=0) # lê FISCALAPI_API_KEY; as novas tentativas ficam com o script
with open("certificado.pfx", "rb") as f:
PFX = f.read()
SENHA = os.environ["CERT_SENHA"]
trava = threading.Lock()
parar = threading.Event()
def limpar(valor: str) -> str:
chave = "".join(c for c in valor if c.isascii() and c.isalnum()).upper()
return chave[3:] if len(chave) == 47 and chave.startswith("CTE") else chave
def gravar(arquivo: str, registro: dict) -> None:
registro["consultado_em"] = datetime.now(timezone.utc).isoformat()
with trava, open(arquivo, "a", encoding="utf-8") as f:
f.write(json.dumps(registro, ensure_ascii=False) + "\n")
def ja_concluidas() -> set[str]:
try:
with open(SAIDA, encoding="utf-8") as f:
return {json.loads(linha)["chave"] for linha in f if linha.strip()}
except FileNotFoundError:
return set()
def segundos(erro) -> float:
"""Espera pedida no header Retry-After (10 s se não vier)."""
valor = erro.headers.get("Retry-After") or erro.headers.get("retry-after")
try:
return float(valor) if valor else 10.0
except ValueError:
return 10.0
def interromper(motivo: str) -> None:
if not parar.is_set():
parar.set()
print(f"Parei: {motivo}")
def baixar(chave: str) -> None:
resp = None
for _ in range(TENTATIVAS):
if parar.is_set():
return
try:
resp = api.consultar_cte_xml(chave, certificado=PFX, senha=SENHA)
break
except RateLimitError as e:
if e.code == "LIMITE_FALHAS_DIARIO":
interromper(f"{e.message} Confira as chaves e o certificado.")
return
time.sleep(segundos(e)) # limite por minuto ou consultas simultâneas
except ServerError as e:
if e.status_code != 503: # 500, 502, 504: fica para a próxima rodada
gravar(FALHAS, {"chave": chave, "erro": e.code or e.status_code, "mensagem": e.message})
return
time.sleep(segundos(e)) # PFX_OCUPADO, ERRO_ABRIR_CERTIFICADO: passageiro
except BadRequestError as e:
if e.code == "CERTIFICADO_INVALIDO" or e.status_code == 422: # 422: certificado acima de 100 KB
interromper(f"certificado recusado: {e.message}") # vale para todas as chaves
else:
gravar(SAIDA, {"chave": chave, "status": e.code, "mensagem": e.message})
return
except InsufficientBalanceError as e:
interromper(f"{e.message} Rode de novo depois de recarregar.")
return
except AuthenticationError as e:
interromper(f"chave de API recusada: {e.message}")
return
except APIConnectionError as e:
gravar(FALHAS, {"chave": chave, "erro": "REDE", "mensagem": e.message})
return
if resp is None:
gravar(FALHAS, {"chave": chave, "erro": "TENTATIVAS", "mensagem": "429 ou 503 repetidos"})
return
if resp["status"] == "ok":
caminho = os.path.join(PASTA, f"{chave}.xml")
with open(caminho, "w", encoding="utf-8") as f:
f.write(resp["xml"])
gravar(SAIDA, {"chave": chave, "status": "ok", "arquivo": caminho,
"creditos_cobrados": resp["creditos_cobrados"]})
elif resp["status"] == "erro":
gravar(FALHAS, {"chave": chave, "erro": "erro", "mensagem": resp["mensagem"]})
else: # nao_autorizado ou nao_encontrado: não cobra e não adianta repetir agora
gravar(SAIDA, {"chave": chave, "status": resp["status"], "mensagem": resp["mensagem"]})
def main() -> None:
os.makedirs(PASTA, exist_ok=True)
with open(ENTRADA, encoding="utf-8") as f:
chaves = [limpar(linha) for linha in f]
feitas = ja_concluidas()
pendentes = list(dict.fromkeys(c for c in chaves if c and c not in feitas))
print(f"{len(feitas)} já concluídas, {len(pendentes)} pendentes")
with ThreadPoolExecutor(max_workers=SIMULTANEAS) as grupo:
list(grupo.map(baixar, pendentes))
if parar.is_set():
sys.exit(2)
print("Fim. As chaves de falhas.jsonl entram de novo se você rodar outra vez.")
if __name__ == "__main__":
main()Rode com python baixar_cte.py.
O script em Node.js
Salve como baixar-cte.mjs:
// Baixa o XML de uma lista de CT-e pela chave de acesso, com retomada.
import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { setTimeout as dormir } from 'node:timers/promises';
import {
APIConnectionError,
AuthenticationError,
BadRequestError,
FiscalAPI,
InsufficientBalanceError,
RateLimitError,
ServerError,
} from 'fiscalapi-br';
const ENTRADA = 'chaves.txt'; // uma chave por linha
const PASTA = 'xml'; // um arquivo <chave>.xml por CT-e baixado
const SAIDA = 'resultado.jsonl'; // uma linha por chave concluída (é também o checkpoint)
const FALHAS = 'falhas.jsonl'; // falhas passageiras: entram de novo na próxima rodada
const SIMULTANEAS = 3; // chamadas ao mesmo tempo
const TENTATIVAS = 5; // por chave, em 429 e 503
const api = new FiscalAPI({ maxRetries: 0 }); // lê FISCALAPI_API_KEY; as novas tentativas ficam com o script
const certificado = readFileSync('certificado.pfx');
const senha = process.env.CERT_SENHA;
let parada = null;
function limpar(valor) {
const chave = valor.replace(/[^0-9A-Za-z]/g, '').toUpperCase();
return chave.length === 47 && chave.startsWith('CTE') ? chave.slice(3) : chave;
}
function gravar(arquivo, registro) {
registro.consultado_em = new Date().toISOString();
appendFileSync(arquivo, JSON.stringify(registro) + '\n');
}
function jaConcluidas() {
if (!existsSync(SAIDA)) return new Set();
return new Set(
readFileSync(SAIDA, 'utf8')
.split('\n')
.filter(Boolean)
.map((linha) => JSON.parse(linha).chave),
);
}
// Espera pedida no header Retry-After (10 s se não vier).
const segundos = (e) => Number(e.headers['retry-after']) || 10;
function interromper(motivo) {
if (!parada) {
parada = motivo;
console.error(`Parei: ${motivo}`);
}
}
async function baixar(chave) {
let resp = null;
for (let i = 0; i < TENTATIVAS && !resp; i++) {
if (parada) return;
try {
resp = await api.consultarCteXml({ chave, certificado, senha });
} catch (e) {
if (e instanceof RateLimitError) {
if (e.code === 'LIMITE_FALHAS_DIARIO') {
return interromper(`${e.message} Confira as chaves e o certificado.`);
}
await dormir(segundos(e) * 1000); // limite por minuto ou consultas simultâneas
} else if (e instanceof ServerError) {
if (e.status !== 503) {
// 500, 502, 504: fica para a próxima rodada
return gravar(FALHAS, { chave, erro: e.code ?? e.status, mensagem: e.message });
}
await dormir(segundos(e) * 1000); // PFX_OCUPADO, ERRO_ABRIR_CERTIFICADO: passageiro
} else if (e instanceof BadRequestError) {
if (e.code === 'CERTIFICADO_INVALIDO' || e.status === 422) {
// 422: certificado acima de 100 KB
return interromper(`certificado recusado: ${e.message}`); // vale para todas as chaves
}
return gravar(SAIDA, { chave, status: e.code, mensagem: e.message });
} else if (e instanceof InsufficientBalanceError) {
return interromper(`${e.message} Rode de novo depois de recarregar.`);
} else if (e instanceof AuthenticationError) {
return interromper(`chave de API recusada: ${e.message}`);
} else if (e instanceof APIConnectionError) {
return gravar(FALHAS, { chave, erro: 'REDE', mensagem: e.message });
} else {
throw e;
}
}
}
if (!resp) {
return gravar(FALHAS, { chave, erro: 'TENTATIVAS', mensagem: '429 ou 503 repetidos' });
}
if (resp.status === 'ok') {
const arquivo = join(PASTA, `${chave}.xml`);
writeFileSync(arquivo, resp.xml, 'utf8');
gravar(SAIDA, { chave, status: 'ok', arquivo, creditos_cobrados: resp.creditos_cobrados });
} else if (resp.status === 'erro') {
gravar(FALHAS, { chave, erro: 'erro', mensagem: resp.mensagem });
} else {
// nao_autorizado ou nao_encontrado: não cobra e não adianta repetir agora
gravar(SAIDA, { chave, status: resp.status, mensagem: resp.mensagem });
}
}
mkdirSync(PASTA, { recursive: true });
const feitas = jaConcluidas();
const fila = [
...new Set(
readFileSync(ENTRADA, 'utf8')
.split('\n')
.map(limpar)
.filter((chave) => chave && !feitas.has(chave)),
),
];
console.log(`${feitas.size} já concluídas, ${fila.length} pendentes`);
async function trabalhador() {
while (fila.length && !parada) await baixar(fila.shift());
}
await Promise.all(Array.from({ length: SIMULTANEAS }, trabalhador));
if (parada) process.exit(2);
console.log('Fim. As chaves de falhas.jsonl entram de novo se você rodar outra vez.');Rode com node baixar-cte.mjs. Use a chave de API só no servidor, nunca no navegador.
O que fazer com cada status
A resposta de cada chave vem em HTTP 200 com um destes valores em status:
status | O que quer dizer | É cobrado | O que o script faz |
|---|---|---|---|
ok | O XML completo (cteProc, com protocolo e assinatura) veio em xml. | Sim | Grava xml/<chave>.xml e marca a chave como concluída. |
nao_autorizado | O titular do certificado não participa deste CT-e. | Não | Marca como concluída. Rode essa chave de novo com o certificado de outro participante, numa pasta separada (ou apague a linha dela em resultado.jsonl). |
nao_encontrado | O CT-e não está disponível para download. | Não | Marca como concluída. Repetir logo em seguida devolve o mesmo resultado. |
erro | Falha nossa, passageira. | Não | Vai para falhas.jsonl e entra na próxima rodada. |
Como ele lida com cada erro HTTP
| Erro | O que o script faz |
|---|---|
429 RATE_LIMIT_EXCEEDED ou CONSULTAS_SIMULTANEAS | Espera os segundos do header Retry-After e tenta a mesma chave de novo, até 5 vezes. Se a conta bate muito nesse erro, diminua SIMULTANEAS. O limite é da conta: não rode dois scripts ao mesmo tempo. |
429 LIMITE_FALHAS_DIARIO | Para. Muitas chaves sem resultado no dia: confira se as chaves são do certificado usado. |
503 PFX_OCUPADO ou ERRO_ABRIR_CERTIFICADO | Espera o Retry-After e tenta de novo. Não é problema do certificado. |
400 CERTIFICADO_INVALIDO ou 422 | Para. Senha errada, certificado vencido, arquivo que não é A1 ou acima de 100 KB valem para todas as chaves. |
400 CHAVE_INVALIDA ou PARAMETRO_AUSENTE | Grava o código no resultado e segue. Chave de NF-e (modelo 55) cai aqui. |
402 LIMITE_ATINGIDO | Para. O saldo de créditos não cobre o XML. Compre créditos extras ou mude de plano e rode de novo. |
403 | Para. Chave de API ausente, inválida ou revogada. |
500, 502, 504 ou rede | A chave vai para falhas.jsonl e entra na próxima rodada. |
| Interrupção | resultado.jsonl é o checkpoint: na próxima rodada, as chaves concluídas são puladas. |
O SDK é criado com max_retries=0 (maxRetries: 0 no Node) para que só o script decida quando repetir. O tempo máximo da rota é de 95 s; o SDK espera até 200 s por resposta, então não reduza o timeout dele abaixo disso.
Sem SDK: HTTP puro
A mesma chamada com requests, uma chave de cada vez. O código do erro vem em title ou em error, conforme o formato (Tratamento de erros).
import base64
import os
import time
import requests
URL = "https://api.fiscalapi.com.br/api/consultar-cte-xml"
HEADERS = {"X-API-Key": os.environ["FISCALAPI_API_KEY"]}
with open("certificado.pfx", "rb") as f:
CERT = base64.b64encode(f.read()).decode()
os.makedirs("xml", exist_ok=True)
for chave in (linha.strip() for linha in open("chaves.txt", encoding="utf-8")):
if not chave:
continue
for _ in range(5):
r = requests.post(URL, headers=HEADERS, timeout=120,
json={"chave": chave, "certificado": CERT, "senha": os.environ["CERT_SENHA"]})
if r.status_code not in (429, 503):
break
time.sleep(float(r.headers.get("Retry-After", 10)))
corpo = r.json() if "json" in r.headers.get("content-type", "") else {} # 5xx pode vir em HTML
if r.status_code != 200:
codigo = corpo.get("title") or corpo.get("error")
print(chave, r.status_code, codigo)
if r.status_code in (402, 403, 422) or codigo in ("CERTIFICADO_INVALIDO", "LIMITE_FALHAS_DIARIO"):
break # repetir não resolve
continue
if corpo["status"] == "ok":
with open(f"xml/{corpo['chave']}.xml", "w", encoding="utf-8") as f:
f.write(corpo["xml"])
print(chave, corpo["status"], corpo["mensagem"])Com curl, o exemplo de uma chave está na página da rota.
Quanto custa
| Plano | Com créditos do plano | Com créditos extras | XML por mês com os créditos do plano |
|---|---|---|---|
| Starter (R$ 50/mês) | R$ 0,30 | R$ 0,36 | 166 |
| Pro (R$ 130/mês) | R$ 0,195 | R$ 0,255 | 666 |
| Enterprise (R$ 250/mês) | R$ 0,05 | R$ 0,05 | 5.000 |
Cada XML entregue (status: "ok") é uma cobrança. nao_autorizado, nao_encontrado, erro e os erros HTTP não são cobrados. Depois dos créditos do plano, vale o preço da coluna de créditos extras. Para mais de 5.000 XML por mês, há o plano Sob medida: contato@fiscalapi.com.br. Veja Planos e limites.
Para testar: conta que nunca assinou plano, com e-mail confirmado e sem créditos extras, tem 10 XML grátis por mês no painel, somando NF-e e CT-e com certificado. Pela API, a consulta pede plano ou créditos extras. Criar conta.
Perguntas frequentes
Dá para baixar o XML de vários CT-e de uma vez?
Não em uma chamada só: a rota recebe uma chave por requisição. Para uma lista, faça uma chamada por chave, algumas em paralelo, como o script desta página.
Como baixar o XML do CT-e em lote com Python?
Com o SDK fiscalapi-br (0.3.0 ou mais novo), chame FiscalAPI().consultar_cte_xml(chave, certificado="certificado.pfx", senha=...) para cada chave e grave o campo xml quando status for ok. O script desta página faz isso com 3 chamadas simultâneas e retoma de onde parou.
Qual é o método de CT-e nos SDKs da FiscalAPI?
consultar_cte_xml no Python (PyPI fiscalapi-br), consultarCteXml no Node.js (npm fiscalapi-br) e no PHP (fiscalapi-br/fiscalapi-php), todos a partir da versão 0.3.0. No n8n, é o recurso CTe do nó n8n-nodes-fiscalapi (guia do n8n).
Posso usar um certificado para CT-e de empresas diferentes?
Só para os CT-e de que o titular do certificado participa. Chave de outra empresa volta nao_autorizado, sem cobrança; rode essas chaves com o certificado dela.
Chave que não devolve XML é cobrada?
Não. Só status: "ok", com o XML na resposta, é cobrado.
XML do CT-e pela chave de acesso · Planos e preços
Esta pagina foi util?
Como consultar as certidões de um fornecedor por API?
Script pronto em Python: CND Federal, CNDT e CRF do FGTS de uma lista de CNPJs, com a situação, a validade e o PDF de cada certidão.
Como migrar do SintegrAPI ou do SintegraWS para a FiscalAPI?
Equivalência de endpoints, parâmetros, campos e erros entre o SintegrAPI, o SintegraWS e a FiscalAPI na consulta de inscrição estadual, com o que muda no código e o custo por consulta pelos preços públicos.