Como baixar o XML de vários CT-e de uma vez pelas chaves
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
| Quantidade | Caminho | Precisa programar? |
|---|---|---|
| Poucas chaves | Painel, tela CT-e por Chave, uma por vez | Não |
| Dezenas ou milhares | API, uma requisição por chave | Sim, o script abaixo serve |
| Rotina diária no ERP ou no TMS | API, chamada a cada frete recebido | Sim |
| Todos os CT-e em que você aparece, sem ter as chaves | Web service oficial de distribuição do CT-e | Sim |
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
- Junte as chaves num arquivo
chaves.txt, uma por linha. Espaços e pontos podem ficar. - 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.
- 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.
- 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.
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ório | O que fazer | Foi cobrado? |
|---|---|---|
| ok | O XML está em xml/ | Sim |
| nao_autorizado | O titular do certificado não participa deste CT-e: use o A1 de outra empresa do frete | Não |
| nao_encontrado | O CT-e não está disponível para download: confira a chave com o emitente | Não |
| erro | Falha nossa: rode o script de novo só com essas chaves | Não |
| HTTP 400 | Chave ou certificado inválido: corrija antes de repetir | Não |
| HTTP 402 | O saldo não cobre o XML: recarregue créditos e rode de novo | Não |
| HTTP 429 ou HTTP 503 | Limite ou indisponibilidade que não passou em 60 segundos; no 429 LIMITE_FALHAS_DIARIO, confira chaves e certificado antes de repetir | Não |
| falha_rede | A conexão caiu: rode o script de novo | Não |
Quanto custa uma lista de 500 chaves
| Plano | Por XML entregue | 500 chaves, 480 com XML |
|---|---|---|
| Starter (R$ 50/mês) | R$ 0,30 | R$ 144,00 |
| Pro (R$ 130/mês) | R$ 0,195 | R$ 93,60 |
| Enterprise (R$ 250/mês) | R$ 0,05 | R$ 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
- XML do CT-e pela chave, documentação da FiscalAPI
- MOC do CT-e, Distribuição de DF-e: atores atendidos e disponibilidade de 3 meses
Artigos relacionados
- API para baixar o XML do CT-e pela chave de acesso
- Como baixar o XML do CT-e pela chave de acesso
- Chave de acesso do CT-e: o que significa cada um dos 44 dígitos
- Como baixar o XML de várias NF-e de uma vez pelas chaves
Tem uma lista de chaves de CT-e? Crie sua conta, gere a chave de API e rode o script.
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