FiscalAPI
Guias

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-br na 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_KEY e a senha do certificado em CERT_SENHA.
  • O certificado em certificado.pfx, na mesma pasta do script.
  • Um arquivo chaves.txt com uma chave por linha. Pontos, espaços e o prefixo CTe do 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:

statusO que quer dizerÉ cobradoO que o script faz
okO XML completo (cteProc, com protocolo e assinatura) veio em xml.SimGrava xml/<chave>.xml e marca a chave como concluída.
nao_autorizadoO titular do certificado não participa deste CT-e.NãoMarca 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_encontradoO CT-e não está disponível para download.NãoMarca como concluída. Repetir logo em seguida devolve o mesmo resultado.
erroFalha nossa, passageira.NãoVai para falhas.jsonl e entra na próxima rodada.

Como ele lida com cada erro HTTP

ErroO que o script faz
429 RATE_LIMIT_EXCEEDED ou CONSULTAS_SIMULTANEASEspera 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_DIARIOPara. Muitas chaves sem resultado no dia: confira se as chaves são do certificado usado.
503 PFX_OCUPADO ou ERRO_ABRIR_CERTIFICADOEspera o Retry-After e tenta de novo. Não é problema do certificado.
400 CERTIFICADO_INVALIDO ou 422Para. Senha errada, certificado vencido, arquivo que não é A1 ou acima de 100 KB valem para todas as chaves.
400 CHAVE_INVALIDA ou PARAMETRO_AUSENTEGrava o código no resultado e segue. Chave de NF-e (modelo 55) cai aqui.
402 LIMITE_ATINGIDOPara. O saldo de créditos não cobre o XML. Compre créditos extras ou mude de plano e rode de novo.
403Para. Chave de API ausente, inválida ou revogada.
500, 502, 504 ou redeA chave vai para falhas.jsonl e entra na próxima rodada.
Interrupçãoresultado.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

PlanoCom créditos do planoCom créditos extrasXML por mês com os créditos do plano
Starter (R$ 50/mês)R$ 0,30R$ 0,36166
Pro (R$ 130/mês)R$ 0,195R$ 0,255666
Enterprise (R$ 250/mês)R$ 0,05R$ 0,055.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?

On this page