FiscalAPI
CT-e

API para baixar o XML do CT-e pela chave de acesso (com certificado)

Baixe o XML completo e autorizado (cteProc) do CT-e, CT-e OS ou GTV-e pela chave de acesso usando o certificado digital A1 de quem participa do documento, sem custódia.

Atualizado em

POST /api/consultar-cte-xml devolve o XML completo e autorizado (cteProc, com protocolo e assinatura) de um CT-e a partir da chave de 44 dígitos, usando o certificado A1 (e-CNPJ ou e-CPF) de quem participa do documento. Aceita os modelos 57 (CT-e), 67 (CT-e OS) e 64 (GTV-e).

O certificado é usado só durante a consulta e nunca é armazenado.

Para uma lista de chaves, use o script pronto em Python e Node.js ou o nó do n8n. Sem programar, o painel (app.fiscalapi.com.br) baixa uma chave por vez.

Resumo

ItemValor
EndpointPOST https://api.fiscalapi.com.br/api/consultar-cte-xml
Você enviachave (44 dígitos), certificado (A1 em base64) e senha
VoltaXML cteProc em xml e status da chave
Documentos por requisição1
Certificado guardado?Não

Quanto custa cada chamada

PlanoCom créditos do planoCom créditos extras
StarterR$ 0,30R$ 0,36
ProR$ 0,195R$ 0,255
EnterpriseR$ 0,05R$ 0,05

Só cobra quando o XML volta. No painel, os 10 XML grátis por mês valem para NF-e ou CT-e (mesma cota). Veja Planos e limites.

Autenticação

Envie sua chave no header X-API-Key. Veja Autenticação para detalhes.

Corpo da requisição

Envie um JSON (Content-Type: application/json) com os campos abaixo.

CampoTipoObrigatórioDescrição
chavestringSimChave de acesso de 44 posições (uma por requisição). Separadores são ignorados. Aceita CNPJ alfanumérico do emitente. Modelo 57, 67 ou 64.
certificadostringSimCertificado A1 (.pfx/.p12) em base64, até 100 KB. O titular precisa participar do CT-e (emitente, tomador, remetente, destinatário, expedidor ou recebedor).
senhastringSimSenha do certificado.

Chave de NF-e (modelo 55) volta CHAVE_INVALIDA. Para NF-e, use o XML de NF-e.

Exemplos

Baixar o XML pela chave com o certificado A1

# codifica o certificado em base64 e envia
CERT=$(base64 < certificado.pfx | tr -d '\n')
curl -X POST "https://api.fiscalapi.com.br/api/consultar-cte-xml" \
  -H "X-API-Key: fapi_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d "{\"chave\":\"51261012345678000195570010000001231123456785\",\"certificado\":\"$CERT\",\"senha\":\"sua-senha\"}"
import { readFileSync } from "node:fs";

const certificado = readFileSync("certificado.pfx").toString("base64");

const response = await fetch(
  "https://api.fiscalapi.com.br/api/consultar-cte-xml",
  {
    method: "POST",
    headers: {
      "X-API-Key": "fapi_sua_chave_aqui",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      chave: "51261012345678000195570010000001231123456785",
      certificado,
      senha: "sua-senha",
    }),
  }
);
const data = await response.json();
console.log(data.status, data.xml);
import base64
import requests

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

response = requests.post(
    "https://api.fiscalapi.com.br/api/consultar-cte-xml",
    headers={"X-API-Key": "fapi_sua_chave_aqui"},
    json={
        "chave": "51261012345678000195570010000001231123456785",
        "certificado": certificado,
        "senha": "sua-senha",
    },
)
data = response.json()
print(data["status"], data["xml"])
$certificado = base64_encode(file_get_contents('certificado.pfx'));

$response = Http::withHeaders([
    'X-API-Key' => 'fapi_sua_chave_aqui',
])->post('https://api.fiscalapi.com.br/api/consultar-cte-xml', [
    'chave' => '51261012345678000195570010000001231123456785',
    'certificado' => $certificado,
    'senha' => 'sua-senha',
]);
$data = $response->json();
var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "fapi_sua_chave_aqui");

var certificado = Convert.ToBase64String(File.ReadAllBytes("certificado.pfx"));
var payload = new
{
    chave = "51261012345678000195570010000001231123456785",
    certificado,
    senha = "sua-senha",
};
var content = new StringContent(
    System.Text.Json.JsonSerializer.Serialize(payload),
    System.Text.Encoding.UTF8,
    "application/json"
);
var response = await client.PostAsync(
    "https://api.fiscalapi.com.br/api/consultar-cte-xml", content
);
var data = await response.Content.ReadAsStringAsync();

Resposta

A resposta é plana, sem envelope.

CampoTipoDescrição
request_idstringIdentificador único da requisição.
chavestringChave de acesso (44 posições).
statusstringResultado da chave. Veja a tabela abaixo.
xmlstring | nullXML completo (cteProc) quando status = ok; caso contrário null.
mensagemstringTexto curto do resultado; sem XML, o motivo.
creditos_cobradosintegerQuantas consultas do saldo a chamada usou: 3 quando o XML volta nos planos Starter e Pro; 1 no Enterprise; 0 sem XML. O preço em R$ está na tabela acima.

Valores de status

StatusSignificadoÉ cobrada
okXML completo retornado em xml.Sim
nao_autorizado"O titular do certificado não é participante deste CT-e."Não
nao_encontrado"Este CT-e não está disponível para download."Não
erroFalha nossa, com mensagem de "tente novamente".Não

Exemplo de resposta

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "chave": "51261012345678000195570010000001231123456785",
  "status": "ok",
  "xml": "<cteProc versao=\"4.00\" ...>...</cteProc>",
  "mensagem": "Documento localizado.",
  "creditos_cobrados": 3
}

Códigos de erro

CódigoHTTP StatusDescrição
PARAMETRO_AUSENTE400Chave de acesso não informada.
CHAVE_INVALIDA400Chave fora do padrão (tamanho, caracteres, dígito verificador) ou de outro modelo. Chave de NF-e: "Esta consulta aceita apenas chaves de CT-e, CT-e OS ou GTV-e".
CERTIFICADO_INVALIDO400Certificado vazio ou base64 inválido, senha incorreta, arquivo que não é A1 (.pfx/.p12) ou certificado expirado. A mensagem diz o motivo.
LIMITE_ATINGIDO402O saldo de créditos (do plano e extras) não cobre o documento.
RATE_LIMIT_EXCEEDED429Limite de requisições por minuto do plano. Aguarde (header Retry-After).
LIMITE_FALHAS_DIARIO429Muitas consultas sem resultado no dia. Confira as chaves e o certificado antes de repetir.
CONSULTAS_SIMULTANEAS429Consultas de CT-e simultâneas demais na conta. Aguarde alguma terminar (header Retry-After).
PFX_OCUPADO / ERRO_ABRIR_CERTIFICADO503Indisponível agora, não é problema do certificado. Tente de novo (header Retry-After).

Perguntas frequentes

Dá para consultar vários CT-e de uma vez?

Não há lote. Faça uma requisição por chave, em paralelo ou em sequência. O guia de vários CT-e traz o script pronto, com um .xml por chave.

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, sem histórico salvo.

Dá para baixar o XML do CT-e sem certificado digital?

Não na FiscalAPI: o XML do CT-e só sai com o certificado A1 de quem participa do documento. Sem certificado, peça o arquivo ao emitente, que tem de enviá-lo ou deixá-lo para download ao tomador do serviço (Ajuste SINIEF 09/07, cláusula oitava, § 9º).

O tomador do frete consegue baixar o XML do CT-e?

Sim. Com o certificado A1 do tomador (e-CNPJ ou e-CPF), a rota devolve o XML completo; também valem os certificados do emitente, remetente, destinatário, expedidor ou recebedor.

Qual a diferença entre DACTE e XML do CT-e?

O XML é o próprio CT-e, assinado e com a autorização de uso, e é o arquivo que transportador e tomador devem guardar (Ajuste SINIEF 09/07, cláusula décima segunda). O DACTE é o documento auxiliar que acompanha a carga e facilita a consulta do CT-e (cláusula décima primeira); esta rota devolve o XML, não o DACTE.

Funciona para CT-e OS e GTV-e?

Sim. A chave pode ser de CT-e (modelo 57), de CT-e OS (modelo 67, de transporte de pessoas, de valores e de excesso de bagagem, pelo Ajuste SINIEF 36/19) ou de GTV-e (modelo 64, a guia de transporte de valores, pelo Ajuste SINIEF 03/20).

Quanto custa baixar o XML de um CT-e pela API?

Com os créditos do plano, R$ 0,30 no Starter, R$ 0,195 no Pro e R$ 0,05 no Enterprise, por XML entregue. Chave sem XML (nao_autorizado, nao_encontrado ou erro) não é cobrada.

Tem como testar grátis?

Sim, no painel: conta que nunca assinou plano, com e-mail confirmado e sem créditos extras, tem 10 XML grátis por mês, somando NF-e e CT-e com certificado, sem cartão. Pela API, a consulta pede plano ou créditos extras, a partir de R$ 50 por mês.

XML do CT-e pela chave de acesso · Planos e preços

Esta pagina foi util?

On this page