Consulta CT-e por Chave de Acesso - XML e DACTE PDF

O que faz o 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) no Brasil a partir da chave de acesso, sem necessidade de certificado digital. A API de origem valida a chave e informa o status da consulta. 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 e use webhooks.

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

Por que usar o Consulta CT-e por Chave de Acesso?

• 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

Benefícios para gestão fiscal e transporte

• 📊 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 é tudo o que você precisa informar; a API de origem valida o formato
• 🔗 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 em lote: uma chamada devolve todos os registros na resposta, para TMS e ERP
• 💰 Cobrança justa: só CT-e com encontrado: true; chave inválida não é cobrada

Como usar o Consulta CT-e por Chave de Acesso

1. Abra o actor no Console Apify na aba Input.
2. Cole as chaves na lista chaves (uma por linha).
3. Clique em Start e exporte o Dataset em JSON, CSV ou XLSX.

Exemplo de entrada:

{
  "chaves": ["35121268252816000146570010000016161002008470"]
}

Input

Informe uma ou mais chaves de acesso CT-e. O Actor normaliza espaços, pontuação e o prefixo CTe, elimina duplicidades e processa no máximo 50 chaves por execução. Chaves inválidas ou CT-es não localizados não geram cobrança.

{
  "chaves": [
    "CTe35121268252816000146570010000016161002008470"
  ]
}

Output

{
  "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": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><cteProc versao=\"1.04\" ...>...</cteProc>"
  },
  "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
}

Consultar pela API da Apify

Execute o actor e receba os registros do Dataset na própria resposta:

curl -X POST "https://api.apify.com/v2/acts/brasildados~api-consulta-cte-por-chave/run-sync-get-dataset-items" \
  -H "Authorization: Bearer SEU_APIFY_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. O token vai no header Authorization: Bearer, nunca na URL.

Este actor é o parceiro natural do Scraper de CT-e em lote quando você já tem as chaves e só precisa do XML e do DACTE de cada uma.

Campos retornados

O Dataset contém um registro por CT-e encontrada. Os campos principais são chave, encontrado, consultadoEm, referenciaConsulta, dados, xml, xmlUrl, dacteUrl e erro. O objeto dados contém identificação, partes, rota, prestação, impostos, carga, documentos transportados e protocolo.

Tips / Dicas

• ✅ Envie até 50 chaves por execução e divida volumes maiores em lotes.
• 🧹 Normalize suas entradas antes do envio para facilitar auditoria, embora o Actor também normalize.
• 📥 Baixe xmlUrl e dacteUrl dentro do período de retenção da execução.
• 💳 Somente registros com encontrado: true são entregues no Dataset e geram cobrança. Entradas inválidas e CT-es não encontradas não são cobradas.

FAQ, avisos e suporte

Preciso informar mais alguma coisa além da chave? Não. A chave de acesso é o único dado obrigatório; a API de origem valida a chave.

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 documenta a venda de mercadorias; o CT-e 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) by its 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 and use webhooks. The upstream API validates the key and reports the result.

🎯 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 · 🛒 Store BrasilDados