# Consulta CT-e por Chave de Acesso - XML e DACTE PDF (`brasildados/api-consulta-cte-por-chave`) Actor
Consulte o Conhecimento de Transporte Eletrônico (CT-e) pela chave de acesso e receba o XML completo do documento e o DACTE em PDF. Modelo 57, em lote ou API REST. Exporte em JSON, CSV ou Excel, rode via API e agende. | CT-e lookup by 44-digit access key: full CT-e XML and DACTE PDF.
- **URL**: https://apify.com/brasildados/api-consulta-cte-por-chave.md
- **Developed by:** [BrasilDados.org](https://apify.com/brasildados) (community)
- **Categories:** E-commerce, Integrations, Developer tools
- **Stats:** 1 total users, 1 monthly users, 0.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet
## Pricing
from $25.00 / 1,000 por cte válida encontrada / per cte file founds
This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.
Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event
## What's an Apify Actor?
Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".
## How to integrate an Actor?
If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.
In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):
```bash
npm install apify-client
```
In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):
```bash
pip install apify-client
```
In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):
````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash
In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).
If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).
For usage examples, see the [API](#api) section below.
For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).
# README
### Consulta CT-e por Chave de Acesso
**Consulta CT-e por Chave de Acesso** é uma API para consultar o **Conhecimento de Transporte Eletrônico (CT-e, modelo 57)** no Brasil a partir da **chave de acesso de 44 dígitos**, **sem necessidade de certificado digital**. Informe a chave e receba o conhecimento **já quebrado em campos** (campo `dados`): emitente, remetente, destinatário, **origem e destino**, **valor do frete** e seus componentes, **ICMS**, **carga** e as **chaves das NF-es transportadas**, além do **protocolo de autorização**. Junto vem o **XML completo** (layout `cteProc`) e **links de download** prontos para o **XML** e o **DACTE em PDF**. Cada chave gera um registro estruturado com a situação da consulta, pronto para **gestão e auditoria de fretes**, conciliação de transporte, controle de documentos fiscais de carga e integração com **ERP/TMS**. Processe **até 50 chaves** por execução e exporte em **JSON, CSV, Excel ou XML**, rode via **API**, agende e monitore execuções, use **webhooks** ou consulte em tempo real pela **API REST Standby** (`POST /check`). Chave com dígito verificador inválido falha localmente, **sem cobrança**.
> 🎯 **O diferencial:** a maioria das consultas de CT-e devolve só o XML cru e deixa o trabalho pesado com você. Aqui você cola a chave e recebe o conhecimento **pronto para usar** - cada campo já extraído (rota, partes, valor do frete, ICMS, carga e as **NF-es que a carga transporta**), sem escrever uma linha de parser. O XML completo e o DACTE em PDF vêm junto, para quando você precisar do arquivo original.
### Casos de uso
- **Gestão de fretes:** conferir valor, rota e tomador do serviço em campos prontos, sem abrir o XML
- **Auditoria de transporte:** validar o valor da prestação e a situação do documento direto da origem
- **Conciliação de fretes:** cruzar CT-e com pedidos, notas e faturas de transportadoras
- **Rastrear a carga:** ligar cada CT-e às **NF-es transportadas** pelas chaves retornadas em `dados`
- **Importação para TMS/ERP:** mapear os campos do objeto `dados` direto para o seu sistema, ou usar o XML
- **Download com um clique:** baixar o XML e o DACTE em PDF de cada CT-e pelos links retornados
### O que este Actor retorna?
| | |
|---|---|
| 📊 **Dados estruturados** | `dados` com identificação, rota, partes, prestação/frete, ICMS, carga, **NF-es transportadas** e protocolo |
| 📦 **XML completo** | `xml.data` com o `cteProc` inteiro, sem alterações |
| 📥 **Download do XML** | `xmlUrl`: link público para baixar o XML com um clique |
| 📄 **Download do DACTE** | `dacteUrl`: link público para baixar o DACTE em PDF |
| 🔑 **Identificação** | `chave`, `encontrado`, `consultadoEm`, `referenciaConsulta` |
| ⚠️ **Erros** | `erro` claro para chave inválida ou CT-e não localizado |
### Por que usar este Actor?
- 📊 **Conhecimento já estruturado:** cada campo extraído no objeto `dados` (rota, partes, frete, ICMS, carga, protocolo) - sem precisar escrever parser de XML
- 🚚 **Só a chave:** a chave de acesso de 44 dígitos é tudo o que você precisa informar
- 🔗 **NF-es da carga:** as chaves das notas fiscais transportadas pelo CT-e, prontas para rastrear
- 📥 **XML + DACTE juntos:** o `cteProc` completo (`xml`) e links de download para o **XML** (`xmlUrl`) e o **DACTE em PDF** (`dacteUrl`), em todo CT-e encontrado
- 📤 **Lote:** até **50 chaves** por execução, com exportação em JSON, CSV, Excel ou XML
- ⚡ **API Standby:** `POST /check` para TMS, ERP e automações de transporte em tempo real
- 💰 **Cobrança justa:** só CT-e com `encontrado: true`; chave inválida não é cobrada
### Como consultar CT-e em lote
1. Abra o actor no [Console Apify](https://console.apify.com/) na aba **Input**.
2. Cole as chaves na lista **`chaves`** (uma por linha, 44 dígitos cada).
3. Clique em **Start** e exporte o Dataset em **JSON**, **CSV** ou **XLSX**.
**Exemplo de entrada:**
```json
{
"chaves": ["35121268252816000146570010000016161002008470"]
}
````
### Exemplo de saída
```json
{
"chave": "35121268252816000146570010000016161002008470",
"encontrado": true,
"consultadoEm": "2026-06-03T11:00:00.000Z",
"referenciaConsulta": "bd-af03c0f94e82",
"dados": {
"identificacao": {
"chave": "35121268252816000146570010000016161002008470",
"modelo": "57",
"serie": "1",
"numero": "1616",
"cfop": "5353",
"naturezaOperacao": "PREST. DE SERV. TRANSPORTE",
"dataEmissao": "2026-04-15T15:01:00-03:00",
"tipoCte": "normal",
"tipoServico": "normal",
"modal": "rodoviário",
"tomador": "remetente",
"ambiente": "produção"
},
"origem": { "municipio": "Conchal", "uf": "SP" },
"destino": { "municipio": "Jacareí", "uf": "SP" },
"emitente": {
"cnpjCpf": "68252816000146",
"razaoSocial": "Transportadora Exemplo LTDA",
"inscricaoEstadual": "392242719111",
"endereco": { "municipio": "Jacareí", "uf": "SP" }
},
"remetente": { "cnpjCpf": "85782878000855", "razaoSocial": "Indústria Remetente S.A." },
"destinatario": { "cnpjCpf": "68252816000146", "razaoSocial": "Comércio Destinatário LTDA" },
"prestacao": {
"valorTotal": 1118.35,
"valorReceber": 1118.35,
"componentes": [{ "nome": "COLETA", "valor": 1118.35 }]
},
"impostos": {
"icms": { "cst": "00", "baseCalculo": 1118.35, "aliquota": 12.0, "valor": 134.2 },
"valorTributosAproximado": null
},
"carga": {
"valorCarga": 50000.0,
"produtoPredominante": "Alimentos congelados",
"quantidades": [{ "unidade": "01", "tipoMedida": "PESO BRUTO", "quantidade": 7018.435 }]
},
"modal": { "tipo": "rodoviário", "rntrc": "44501745" },
"documentos": {
"notasFiscais": [
"35121185782878000855550010000002211151664026",
"35121185782878000855550010000002641607831237"
]
},
"protocolo": {
"numero": "135120069193967",
"dataAutorizacao": "2026-04-15T15:07:36-03:00",
"status": "100",
"motivo": "Autorizado o uso do CT-e",
"situacao": "autorizado"
}
},
"xml": {
"name": "CTE-35121268252816000146570010000016161002008470.xml",
"type": "CTE",
"format": "XML",
"data": "..."
},
"xmlUrl": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/xml-35121268252816000146570010000016161002008470?signature=...",
"dacteUrl": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/dacte-35121268252816000146570010000016161002008470?signature=...",
"erro": null
}
```
### API Standby (consulta em tempo real)
Mantenha o actor em **Standby** e consulte o CT-e por uma requisição REST:
```bash
curl -X POST "https://brasildados--api-consulta-cte-por-chave.apify.actor/check?token=SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"chaves":["35121268252816000146570010000016161002008470"]}'
```
Retorna um array com um registro por chave, ideal para integrar em TMS, sistemas de gestão de transporte e fluxos de auditoria de fretes.
### Perguntas frequentes
**Preciso informar mais alguma coisa além da chave?**
Não. A chave de acesso de 44 dígitos é o único dado obrigatório.
**O actor parseia os campos do XML?**
Sim. O conhecimento vem quebrado em campos no objeto `dados` (identificação, origem/destino, emitente, remetente, destinatário, valor da prestação e componentes do frete, ICMS, carga, chaves das NF-es transportadas e protocolo), pronto para TMS, ERP e planilha. O XML completo (`xml.data`) continua disponível, então você usa os campos prontos ou parseia o XML como preferir.
**Consigo saber quais NF-es a carga transporta?**
Sim. O campo `dados.documentos.notasFiscais` traz as chaves de acesso das NF-es vinculadas ao CT-e, úteis para rastrear a carga e conciliar com a consulta de NF-e por chave.
**Como baixo o XML e o DACTE?**
Todo CT-e encontrado já vem com `xmlUrl` (download do XML) e `dacteUrl` (download do DACTE em PDF). São links públicos clicáveis, sem precisar de token. A validade segue o período de retenção do run, então baixe dentro desse prazo se precisar arquivar.
**Qual a diferença entre CT-e e NF-e?**
A NF-e (modelo 55) documenta a venda de mercadorias; o CT-e (modelo 57) documenta a **prestação do serviço de transporte** dessa carga. Para consultar notas fiscais por chave, use o actor de NF-e.
**Funciona com qualquer CT-e?**
A consulta é feita pela chave de acesso. CT-e não localizados na origem retornam `encontrado: false`, sem cobrança.
**Quando há cobrança?**
Apenas quando o CT-e é encontrado (`encontrado: true`). Chave inválida ou não localizada não é cobrada.
***
### 🇬🇧 English
#### Brazilian CT-e Lookup by Access Key
Look up a Brazilian electronic transport document (**CT-e, model 57**) by its **44-digit access key** and get the document **already parsed into fields** (the `dados` object): issuer, sender, recipient, **origin and destination**, **freight value** and its components, **ICMS**, **cargo** and the **keys of the carried NF-e invoices**, plus the **authorization protocol**. The **full CT-e XML** (`cteProc` layout) is included too, plus ready-to-use **download links** for the **XML** (`xmlUrl`) and the **DACTE PDF** (`dacteUrl`). Each key returns one structured record with the lookup status, ready for **freight management and auditing**, transport reconciliation, cargo document control and **ERP/TMS integration**. Process **up to 50 keys** per run and export to **JSON, CSV, Excel or XML**, run via **API**, schedule and monitor runs, use **webhooks**, or query in real time through the **Standby REST API** (`POST /check`). An invalid check digit fails locally, with no charge.
> 🎯 **What sets it apart:** most CT-e lookups return only the raw XML and leave the heavy lifting to you. Here you paste the key and get the document **ready to use** - every field already extracted (route, parties, freight value, ICMS, cargo and the **NF-e invoices the cargo carries**), with no parser to write. The full XML and DACTE PDF come along for when you need the original file.
**Use cases**
- Check freight value, route and freight payer (tomador) as ready-to-use fields, without opening the XML
- Audit the transport service value and document status straight from the source
- Reconcile CT-e against orders, invoices and carrier billing
- Trace the cargo by linking each CT-e to its carried **NF-e keys** returned in `dados`
- Map the `dados` fields straight into your TMS/ERP, or use the complete XML
- Download the XML and DACTE PDF of each CT-e with a single click
The document comes parsed into fields (the `dados` object) with route, parties, freight, ICMS, cargo and carried NF-e keys, ready for TMS and ERP, and the complete XML is delivered as well so your system can parse exactly what it needs. Billing only applies when the CT-e is found (`encontrado: true`).
***
📧 **contato@brasildados.org** · 🌐 **[brasildados.org](https://brasildados.org)**
# Actor input Schema
## `chaves` (type: `array`):
Chaves de acesso do **CT-e** (44 dígitos, modelo 57). Pontuação e espaços são ignorados. Inválidas: erro local sem cobrança. Máx. 50. | CT-e access keys (44 digits, model 57). Punctuation ignored. Max 50.
## Actor input object example
```json
{
"chaves": [
"35121268252816000146570010000016161002008470"
]
}
```
# Actor output Schema
## `resultados` (type: `string`):
URL da API Apify para baixar os itens do dataset.
# API
You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.
## JavaScript example
```javascript
import { ApifyClient } from 'apify-client';
// Initialize the ApifyClient with your Apify API token
// Replace the '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {
"chaves": [
"35121268252816000146570010000016161002008470"
]
};
// Run the Actor and wait for it to finish
const run = await client.actor("brasildados/api-consulta-cte-por-chave").call(input);
// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
console.dir(item);
});
// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs
```
## Python example
```python
from apify_client import ApifyClient
# Initialize the ApifyClient with your Apify API token
# Replace '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = { "chaves": ["35121268252816000146570010000016161002008470"] }
# Run the Actor and wait for it to finish
run = client.actor("brasildados/api-consulta-cte-por-chave").call(run_input=run_input)
# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
print(item)
# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start
```
## CLI example
```bash
echo '{
"chaves": [
"35121268252816000146570010000016161002008470"
]
}' |
apify call brasildados/api-consulta-cte-por-chave --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=brasildados/api-consulta-cte-por-chave",
"--header",
"Authorization: Bearer "
]
}
}
}
```
## OpenAPI specification
```json
{
"openapi": "3.0.1",
"info": {
"title": "Consulta CT-e por Chave de Acesso - XML e DACTE PDF",
"description": "Consulte o Conhecimento de Transporte Eletrônico (CT-e) pela chave de acesso e receba o XML completo do documento e o DACTE em PDF. Modelo 57, em lote ou API REST. Exporte em JSON, CSV ou Excel, rode via API e agende. | CT-e lookup by 44-digit access key: full CT-e XML and DACTE PDF.",
"version": "1.1",
"x-build-id": "ZGqdeFcGHaewdcth0"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/brasildados~api-consulta-cte-por-chave/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-brasildados-api-consulta-cte-por-chave",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/acts/brasildados~api-consulta-cte-por-chave/runs": {
"post": {
"operationId": "runs-sync-brasildados-api-consulta-cte-por-chave",
"x-openai-isConsequential": false,
"summary": "Executes an Actor and returns information about the initiated run in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/runsResponseSchema"
}
}
}
}
}
}
},
"/acts/brasildados~api-consulta-cte-por-chave/run-sync": {
"post": {
"operationId": "run-sync-brasildados-api-consulta-cte-por-chave",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
}
},
"components": {
"schemas": {
"inputSchema": {
"type": "object",
"required": [
"chaves"
],
"properties": {
"chaves": {
"title": "Chaves de acesso / Access keys",
"minItems": 1,
"maxItems": 50,
"type": "array",
"description": "Chaves de acesso do **CT-e** (44 dígitos, modelo 57). Pontuação e espaços são ignorados. Inválidas: erro local sem cobrança. Máx. 50. | CT-e access keys (44 digits, model 57). Punctuation ignored. Max 50.",
"items": {
"type": "string"
}
}
}
},
"runsResponseSchema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"actId": {
"type": "string"
},
"userId": {
"type": "string"
},
"startedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"finishedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"status": {
"type": "string",
"example": "READY"
},
"meta": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"example": "API"
},
"userAgent": {
"type": "string"
}
}
},
"stats": {
"type": "object",
"properties": {
"inputBodyLen": {
"type": "integer",
"example": 2000
},
"rebootCount": {
"type": "integer",
"example": 0
},
"restartCount": {
"type": "integer",
"example": 0
},
"resurrectCount": {
"type": "integer",
"example": 0
},
"computeUnits": {
"type": "integer",
"example": 0
}
}
},
"options": {
"type": "object",
"properties": {
"build": {
"type": "string",
"example": "latest"
},
"timeoutSecs": {
"type": "integer",
"example": 300
},
"memoryMbytes": {
"type": "integer",
"example": 1024
},
"diskMbytes": {
"type": "integer",
"example": 2048
}
}
},
"buildId": {
"type": "string"
},
"defaultKeyValueStoreId": {
"type": "string"
},
"defaultDatasetId": {
"type": "string"
},
"defaultRequestQueueId": {
"type": "string"
},
"buildNumber": {
"type": "string",
"example": "1.0.0"
},
"containerUrl": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "integer",
"example": 1
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
},
"usageTotalUsd": {
"type": "number",
"example": 0.00005
},
"usageUsd": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "number",
"example": 0.00005
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
}
}
}
}
}
}
}
}
```