Pular para o conteúdo
FiscalAPI
FiscalAPI
CT-e

Como baixar o XML de vários CT-e de uma vez pelas chaves

Equipe FiscalAPI 5 min de leitura
CT-eXMLAPITutorial

Para baixar o XML de vários CT-e de uma vez, use a API da FiscalAPI e faça uma requisição por chave, em sequência ou com poucas em paralelo, com o certificado A1 de quem participa dos fretes: um script curto lê a lista de chaves, salva cada XML com o nome da chave e gera um relatório do que não veio.

No painel, a tela CT-e por Chave consulta uma chave por vez. Só o XML que vem é cobrado.

Atualizado em 16 de novembro de 2026.

Qual caminho usar

QuantidadeCaminhoPrecisa programar?
Poucas chavesPainel, tela CT-e por Chave, uma por vezNão
Dezenas ou milharesAPI, uma requisição por chaveSim, o script abaixo serve
Rotina diária no ERP ou no TMSAPI, chamada a cada frete recebidoSim
Todos os CT-e em que você aparece, sem ter as chavesWeb service oficial de distribuição do CT-eSim

O web service de distribuição entrega aos atores do CT-e os documentos de interesse deles, pelo número sequencial (NSU), com os documentos disponíveis por até 3 meses. O emitente não recebe os próprios CT-e por ele (MOC do CT-e, Distribuição de DF-e). A FiscalAPI consulta pela chave; para receber tudo sem ter as chaves, o caminho é esse web service.

Antes de começar

  1. Junte as chaves num arquivo chaves.txt, uma por linha. Espaços e pontos podem ficar.
  2. Separe por empresa. Cada certificado abre só os CT-e em que o titular aparece. Se a lista mistura fretes de duas empresas do grupo, faça dois arquivos e use o A1 de cada uma.
  3. Confira se são todas de CT-e. Os dígitos 21 e 22 precisam ser 57, 67 ou 64. Chave de NF-e (55) vai para o XML da NF-e pela chave.
  4. Tenha plano ou créditos extras. Pela API, os 10 XML grátis do painel não valem.

O script

O script lê chaves.txt, remove repetidas, consulta 3 chaves por vez, salva os XML na pasta xml/ e grava relatorio.csv com o resultado de cada chave. Chave que já tem XML na pasta é pulada, então rodar de novo só consulta o que faltou.

python
import base64, csv, os, re, time
from concurrent.futures import ThreadPoolExecutor
import requests

API = "https://api.fiscalapi.com.br/api/consultar-cte-xml"
HEADERS = {"X-API-Key": "SUA_CHAVE_DE_API"}
SENHA = "SENHA_DO_CERTIFICADO"

with open("certificado.pfx", "rb") as f:
    CERT = base64.b64encode(f.read()).decode()

def consultar(chave):
    if os.path.exists(f"xml/{chave}.xml"):
        return chave, "ok", "já baixado antes"
    corpo = {"chave": chave, "certificado": CERT, "senha": SENHA}
    try:
        for _ in range(3):
            r = requests.post(API, headers=HEADERS, json=corpo, timeout=120)
            espera = int(r.headers.get("Retry-After", "0"))
            if r.status_code in (429, 503) and 0 < espera <= 60:
                time.sleep(espera)
                continue
            break
    except requests.RequestException as e:
        return chave, "falha_rede", str(e)[:150]
    if r.status_code != 200:
        return chave, f"HTTP {r.status_code}", r.text[:150]
    d = r.json()
    if d["status"] == "ok":
        with open(f"xml/{chave}.xml", "w", encoding="utf-8") as out:
            out.write(d["xml"])
    return chave, d["status"], d["mensagem"]

with open("chaves.txt") as f:
    chaves = [re.sub(r"[^0-9A-Za-z]", "", linha).upper() for linha in f if linha.strip()]
chaves = list(dict.fromkeys(chaves))
os.makedirs("xml", exist_ok=True)

with ThreadPoolExecutor(max_workers=3) as pool:
    resultados = list(pool.map(consultar, chaves))

with open("relatorio.csv", "w", newline="", encoding="utf-8") as f:
    csv.writer(f).writerows([("chave", "status", "mensagem"), *resultados])
print(sum(1 for _, s, _ in resultados if s == "ok"), "de", len(chaves), "XML baixados")

Prefira poucas chamadas em paralelo. Se a conta passar do limite de consultas simultâneas ou por minuto, a API responde HTTP 429 com o cabeçalho Retry-After, e o script espera e repete a chave. A FiscalAPI não guarda os XML: o script salva cada um assim que chega. Os campos e códigos de erro estão na documentação do XML do CT-e.

Como ler o relatório

status no relatórioO que fazerFoi cobrado?
okO XML está em xml/Sim
nao_autorizadoO titular do certificado não participa deste CT-e: use o A1 de outra empresa do freteNão
nao_encontradoO CT-e não está disponível para download: confira a chave com o emitenteNão
erroFalha nossa: rode o script de novo só com essas chavesNão
HTTP 400Chave ou certificado inválido: corrija antes de repetirNão
HTTP 402O saldo não cobre o XML: recarregue créditos e rode de novoNão
HTTP 429 ou HTTP 503Limite ou indisponibilidade que não passou em 60 segundos; no 429 LIMITE_FALHAS_DIARIO, confira chaves e certificado antes de repetirNão
falha_redeA conexão caiu: rode o script de novoNão

Quanto custa uma lista de 500 chaves

PlanoPor XML entregue500 chaves, 480 com XML
Starter (R$ 50/mês)R$ 0,30R$ 144,00
Pro (R$ 130/mês)R$ 0,195R$ 93,60
Enterprise (R$ 250/mês)R$ 0,05R$ 24,00

Os valores são com créditos do plano. Com créditos extras, o XML custa R$ 0,36 no Starter, R$ 0,255 no Pro e R$ 0,05 no Enterprise. As 20 chaves que não voltaram com XML não entram na conta. Veja os planos e preços.

Perguntas frequentes

Dá para colar várias chaves de CT-e no painel? Não. O painel consulta uma chave por vez. Para várias, use a API, uma requisição por chave.

Existe uma rota que recebe várias chaves de CT-e? Não. É uma chave por requisição, em sequência ou em paralelo.

Consigo baixar todos os CT-e emitidos contra o meu CNPJ sem ter as chaves? A FiscalAPI consulta pela chave de acesso. Para receber sem ter as chaves, o web service oficial de distribuição do CT-e entrega aos atores os documentos de interesse, com os documentos disponíveis por até 3 meses.

Se parte das chaves não vier, pago pela lista inteira? Não. Só cobra o CT-e que volta com XML.

Posso usar um certificado só para fretes de várias empresas? Só se o titular participar de todos os CT-e. Caso contrário, separe as chaves por empresa.

Fontes

Artigos relacionados


Tem uma lista de chaves de CT-e? Crie sua conta, gere a chave de API e rode o script.

Compartilhar: WhatsApp LinkedIn Twitter

Baixe o XML do CT-e pela chave

XML completo e assinado do CT-e, CT-e OS ou GTV-e, com o certificado A1 de quem participa do frete. Só cobra quando o XML vem.

Ver o XML do CT-e pela chave