API para baixar o XML do CT-e pela chave de acesso
Para baixar o XML do CT-e pela chave via API, faça um POST https://api.fiscalapi.com.br/api/consultar-cte-xml com a chave de 44 posições, o certificado A1 em base64 e a senha: a resposta em JSON traz o XML completo e assinado (cteProc) no campo xml.
O certificado precisa ser de quem participa do CT-e. Ele é usado só durante a consulta e nunca é guardado. A rota aceita CT-e (modelo 57), CT-e OS (67) e GTV-e (64), e só cobra quando o XML vem.
Atualizado em 16 de novembro de 2026.
O contrato
| Item | Valor |
|---|---|
| Rota | POST https://api.fiscalapi.com.br/api/consultar-cte-xml |
| Autenticação | Cabeçalho X-API-Key com a sua chave de API |
| Corpo | JSON com chave, certificado (A1 em base64, até 100 KB) e senha |
| Documentos por requisição | 1 |
| Modelos aceitos | 57, 67 e 64 |
| Resposta | JSON plano: request_id, chave, status, xml, mensagem, creditos_cobrados |
A chave pode vir com espaços ou pontos: os separadores são ignorados. Ela também aceita o CNPJ alfanumérico do emitente. O titular do certificado precisa ser emitente, tomador, remetente, destinatário, expedidor ou recebedor do CT-e.
cURL
CERT=$(base64 < certificado.pfx | tr -d '\n')
curl -X POST "https://api.fiscalapi.com.br/api/consultar-cte-xml" \
-H "X-API-Key: SUA_CHAVE_DE_API" \
-H "Content-Type: application/json" \
-d "{\"chave\":\"51261012345678000195570010000001231123456785\",\"certificado\":\"$CERT\",\"senha\":\"SENHA_DO_CERTIFICADO\"}" Se a senha tiver aspas ou barra invertida, monte o JSON num arquivo e envie com -d @corpo.json.
Python
import base64
import requests
API = "https://api.fiscalapi.com.br/api/consultar-cte-xml"
HEADERS = {"X-API-Key": "SUA_CHAVE_DE_API"}
with open("certificado.pfx", "rb") as f:
certificado = base64.b64encode(f.read()).decode()
chave = "51261012345678000195570010000001231123456785"
resp = requests.post(
API,
headers=HEADERS,
json={"chave": chave, "certificado": certificado, "senha": "SENHA_DO_CERTIFICADO"},
timeout=120,
)
resp.raise_for_status()
dados = resp.json()
if dados["status"] == "ok":
with open(f"{dados['chave']}.xml", "w", encoding="utf-8") as out:
out.write(dados["xml"])
else:
print(dados["status"], dados["mensagem"]) Node.js
Salve como baixar-cte.mjs (o await no topo do arquivo exige módulo ES) e rode com Node 18 ou mais novo.
import { readFileSync, writeFileSync } from "node:fs";
const certificado = readFileSync("certificado.pfx").toString("base64");
const resp = await fetch("https://api.fiscalapi.com.br/api/consultar-cte-xml", {
method: "POST",
headers: { "X-API-Key": "SUA_CHAVE_DE_API", "Content-Type": "application/json" },
body: JSON.stringify({
chave: "51261012345678000195570010000001231123456785",
certificado,
senha: "SENHA_DO_CERTIFICADO",
}),
});
const dados = await resp.json();
if (!resp.ok) console.log("HTTP", resp.status, dados);
else if (dados.status === "ok") writeFileSync(`${dados.chave}.xml`, dados.xml, "utf8");
else console.log(dados.status, dados.mensagem); Os SDKs fiscalapi-br no npm e no PyPI já trazem a consulta de CT-e, com os métodos consultarCteXml e consultar_cte_xml.
A resposta
{
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"chave": "51261012345678000195570010000001231123456785",
"status": "ok",
"xml": "<cteProc versao=\"4.00\" ...>...</cteProc>",
"mensagem": "Documento localizado.",
"creditos_cobrados": 3
} | status | O que significa | É cobrado? |
|---|---|---|
| ok | O XML completo veio em xml | Sim |
| nao_autorizado | O titular do certificado não participa deste CT-e | Não |
| nao_encontrado | O CT-e não está disponível para download | Não |
| erro | Falha nossa; tente de novo | Não |
O campo creditos_cobrados diz quantas consultas do saldo a chamada usou: 3 nos planos Starter e Pro, 1 no Enterprise, 0 quando o XML não vem.
Erros de entrada voltam com HTTP 400, sem cobrança: PARAMETRO_AUSENTE (sem chave), CHAVE_INVALIDA (tamanho, caractere, dígito verificador ou modelo, inclusive chave de NF-e) e CERTIFICADO_INVALIDO (base64 inválido, senha errada, arquivo que não é A1 ou certificado vencido). A lista completa, com os códigos 402, 429 e 503, está na documentação do XML do CT-e.
Várias chaves: uma requisição por chave
Não existe lote. Para uma lista, percorra as chaves e faça uma chamada para cada uma, em sequência ou com poucas em paralelo. Se vier HTTP 429 ou 503 com o cabeçalho Retry-After curto, espere o tempo indicado e tente de novo a mesma chave. O 429 LIMITE_FALHAS_DIARIO pede outra coisa: conferir as chaves e o certificado antes de repetir, e por isso o exemplo só espera quando o tempo é de até 60 segundos.
import re
import time
def baixar(chave):
for _ in range(3):
resp = requests.post(
API,
headers=HEADERS,
json={"chave": chave, "certificado": certificado, "senha": "SENHA_DO_CERTIFICADO"},
timeout=120,
)
espera = int(resp.headers.get("Retry-After", "0"))
if resp.status_code in (429, 503) and 0 < espera <= 60:
time.sleep(espera)
continue
return resp
return resp
with open("chaves.txt") as f:
limpas = (re.sub(r"[^0-9A-Za-z]", "", linha).upper() for linha in f)
chaves = list(dict.fromkeys(c for c in limpas if c))
for chave in chaves:
resp = baixar(chave)
if resp.status_code != 200:
print(chave, "HTTP", resp.status_code, resp.text[:200])
continue
dados = resp.json()
if dados["status"] == "ok":
with open(f"{dados['chave']}.xml", "w", encoding="utf-8") as out:
out.write(dados["xml"])
else:
print(chave, dados["status"], dados["mensagem"]) Cada certificado abre só os CT-e do seu titular. Se a lista mistura fretes de empresas diferentes, separe as chaves por empresa e use o A1 de cada uma. Um roteiro maior, com relatório em CSV, está em como baixar o XML de vários CT-e de uma vez.
Quanto custa
| Plano | Com créditos do plano | Com créditos extras |
|---|---|---|
| Starter (R$ 50/mês) | R$ 0,30 | R$ 0,36 |
| Pro (R$ 130/mês) | R$ 0,195 | R$ 0,255 |
| Enterprise (R$ 250/mês) | R$ 0,05 | R$ 0,05 |
Pela API, é preciso ter plano ou créditos extras; os 10 XML grátis por mês valem no painel.
Perguntas frequentes
Qual API usar para baixar o XML do CT-e pela chave de acesso? A da FiscalAPI: um POST em /api/consultar-cte-xml com a chave, o certificado A1 em base64 e a senha. O XML completo (cteProc) vem no JSON.
A API baixa CT-e sem certificado? Não. O XML do CT-e exige o certificado A1 de quem participa do documento.
Posso mandar várias chaves numa requisição? Não. É uma chave por requisição; para várias, faça um laço.
A FiscalAPI guarda o certificado ou o XML? Não. O certificado e a senha são descartados ao fim da consulta, e o XML vem só na resposta. Salve o arquivo assim que ele chegar.
Serve certificado A3? Não. A API recebe o arquivo do A1 (.pfx ou .p12).
Fontes
- XML do CT-e pela chave, documentação da FiscalAPI
- MOC do CT-e, Visão Geral, item 4.4: chave de acesso de 44 posições
Artigos relacionados
- Chave de acesso do CT-e: o que significa cada um dos 44 dígitos
- Como baixar o XML de vários CT-e de uma vez pelas chaves
- Como baixar o XML do CT-e pela chave de acesso
- API para baixar XML de NF-e por chave
Vai integrar no ERP ou no TMS? Crie sua conta, gere a chave de API e veja os campos na documentação.
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