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
| Item | Valor |
|---|---|
| Endpoint | POST https://api.fiscalapi.com.br/api/consultar-cte-xml |
| Você envia | chave (44 dígitos), certificado (A1 em base64) e senha |
| Volta | XML cteProc em xml e status da chave |
| Documentos por requisição | 1 |
| Certificado guardado? | Não |
Quanto custa cada chamada
| Plano | Com créditos do plano | Com créditos extras |
|---|---|---|
| Starter | R$ 0,30 | R$ 0,36 |
| Pro | R$ 0,195 | R$ 0,255 |
| Enterprise | R$ 0,05 | R$ 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.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
chave | string | Sim | Chave 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. |
certificado | string | Sim | Certificado A1 (.pfx/.p12) em base64, até 100 KB. O titular precisa participar do CT-e (emitente, tomador, remetente, destinatário, expedidor ou recebedor). |
senha | string | Sim | Senha 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.
| Campo | Tipo | Descrição |
|---|---|---|
request_id | string | Identificador único da requisição. |
chave | string | Chave de acesso (44 posições). |
status | string | Resultado da chave. Veja a tabela abaixo. |
xml | string | null | XML completo (cteProc) quando status = ok; caso contrário null. |
mensagem | string | Texto curto do resultado; sem XML, o motivo. |
creditos_cobrados | integer | Quantas 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
| Status | Significado | É cobrada |
|---|---|---|
ok | XML 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 |
erro | Falha 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ódigo | HTTP Status | Descrição |
|---|---|---|
PARAMETRO_AUSENTE | 400 | Chave de acesso não informada. |
CHAVE_INVALIDA | 400 | Chave 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_INVALIDO | 400 | Certificado vazio ou base64 inválido, senha incorreta, arquivo que não é A1 (.pfx/.p12) ou certificado expirado. A mensagem diz o motivo. |
LIMITE_ATINGIDO | 402 | O saldo de créditos (do plano e extras) não cobre o documento. |
RATE_LIMIT_EXCEEDED | 429 | Limite de requisições por minuto do plano. Aguarde (header Retry-After). |
LIMITE_FALHAS_DIARIO | 429 | Muitas consultas sem resultado no dia. Confira as chaves e o certificado antes de repetir. |
CONSULTAS_SIMULTANEAS | 429 | Consultas de CT-e simultâneas demais na conta. Aguarde alguma terminar (header Retry-After). |
PFX_OCUPADO / ERRO_ABRIR_CERTIFICADO | 503 | Indisponí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?
API para baixar o XML da NF-e só com a chave (sem certificado)
Baixe o XML de uma NF-e só pela chave de acesso, sem certificado digital. Cópia para leitura, sem a assinatura digital.
API de DIFAL de saída: pendência de DIFAL por UF de destino (Beta)
Veja, mês a mês e por UF de destino, as NF-e com DIFAL e FCP destacados, a situação da guia de cada nota e o valor em aberto, com o certificado A1 do próprio emitente e sem custódia.