Pular para o conteúdo
FiscalAPI
FiscalAPI
CT-e

API para baixar o XML do CT-e pela chave de acesso

Equipe FiscalAPI 5 min de leitura
CT-eXMLAPITutorial

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

ItemValor
RotaPOST https://api.fiscalapi.com.br/api/consultar-cte-xml
AutenticaçãoCabeçalho X-API-Key com a sua chave de API
CorpoJSON com chave, certificado (A1 em base64, até 100 KB) e senha
Documentos por requisição1
Modelos aceitos57, 67 e 64
RespostaJSON 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

bash
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

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.

javascript
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

json
{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "chave": "51261012345678000195570010000001231123456785",
  "status": "ok",
  "xml": "<cteProc versao=\"4.00\" ...>...</cteProc>",
  "mensagem": "Documento localizado.",
  "creditos_cobrados": 3
}
statusO que significaÉ cobrado?
okO XML completo veio em xmlSim
nao_autorizadoO titular do certificado não participa deste CT-eNão
nao_encontradoO CT-e não está disponível para downloadNão
erroFalha nossa; tente de novoNã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.

python
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

PlanoCom créditos do planoCom créditos extras
Starter (R$ 50/mês)R$ 0,30R$ 0,36
Pro (R$ 130/mês)R$ 0,195R$ 0,255
Enterprise (R$ 250/mês)R$ 0,05R$ 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

Artigos relacionados


Vai integrar no ERP ou no TMS? Crie sua conta, gere a chave de API e veja os campos na documentação.

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