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

URL: https://docs.fiscalapi.com.br/docs/guias/cte-xml-lote
Atualizado em 16/11/2026

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](#quanto-custa)).
* **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](#quanto-custa)).
* **Comece:** [crie a conta e a chave de API](https://app.fiscalapi.com.br?utm_source=docs\&utm_medium=docs\&utm_campaign=guia-cte).

Contrato completo da rota (campos, códigos de erro): [XML de CT-e pela chave](/docs/cte/consultar-cte-xml).

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

```bash
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`:

```python
"""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`:

```javascript
// 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](/docs/referencia/error-handling)).

```python
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](/docs/cte/consultar-cte-xml#exemplos).

## ## 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](mailto:contato@fiscalapi.com.br). Veja [Planos e limites](/docs/referencia/plans-and-limits).

**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](https://app.fiscalapi.com.br?utm_source=docs\&utm_medium=docs\&utm_campaign=guia-cte).

## ## 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](/docs/guias/n8n#xml-de-ct-e-pela-chave)).

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