# 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.

URL: https://docs.fiscalapi.com.br/docs/cte/consultar-cte-xml
Atualizado em 16/11/2026

`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](/docs/guias/cte-xml-lote) ou o [nó do n8n](/docs/guias/n8n#xml-de-ct-e-pela-chave). Sem programar, o painel ([app.fiscalapi.com.br](https://app.fiscalapi.com.br?utm_source=docs\&utm_medium=docs\&utm_campaign=cte-xml)) 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](/docs/referencia/plans-and-limits).

## ## Autenticação

Envie sua chave no header `X-API-Key`. Veja [Autenticação](/docs/getting-started/authentication) 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.                                                                                                                                                |

<Callout type="warn">
  Chave de NF-e (modelo 55) volta `CHAVE_INVALIDA`. Para NF-e, use o [XML de NF-e](/docs/nfe/consultar-nfe-chave).
</Callout>

## ## Exemplos

### ### Baixar o XML pela chave com o certificado A1

<Tabs items="[&#x22;curl&#x22;, &#x22;JavaScript&#x22;, &#x22;Python&#x22;, &#x22;PHP&#x22;, &#x22;C#&#x22;]">
  <Tab value="curl">
    ```bash
    # 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\"}"
    ```
  </Tab>

  <Tab value="JavaScript">
    ```javascript
    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);
    ```
  </Tab>

  <Tab value="Python">
    ```python
    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"])
    ```
  </Tab>

  <Tab value="PHP">
    ```php
    $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();
    ```
  </Tab>

  <Tab value="C#">
    ```csharp
    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();
    ```
  </Tab>
</Tabs>

## ## 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

```json
{
  "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](/docs/guias/cte-xml-lote) 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](https://www.confaz.fazenda.gov.br/legislacao/ajustes/2007/AJ_009_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](https://www.confaz.fazenda.gov.br/legislacao/ajustes/2007/AJ_009_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](https://www.confaz.fazenda.gov.br/legislacao/ajustes/2019/AJ036_19)) ou de GTV-e (modelo 64, a guia de transporte de valores, pelo [Ajuste SINIEF 03/20](https://www.confaz.fazenda.gov.br/legislacao/ajustes/2020/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.
