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

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

{
  "chaves": ["35121268252816000146570010000016161002008470"]
}

Exemplo de saída

{
  "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
}

API Standby (consulta em tempo real)

Mantenha o actor em Standby e consulte o CT-e por uma requisição REST:

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