CT-e

Visão geral

A API de CT-e emite documentos eletrônicos de transporte (CT-e, modelo 57, modal rodoviário) em nome de transportadoras, consulta o status, cancela e registra eventos pós-autorização (carta de correção, comprovante de entrega, insucesso na entrega, prestação em desacordo). Registro da empresa, vínculo do certificado e registro do webhook são compartilhados com a NF-e e apenas referenciados aqui.

Convenção de caminho: o segmento de recurso é a categoria do documento cte; toda operação no nível do documento fica sob /openapi/v2/empresas/{empresaId}/cte/{cteId}, onde cteId é o id enviado na emissão.

Fluxo de integração

Pré-requisitos

• A empresa precisa estar aprovada com certificado utilizável, e seu CNPJ precisa estar habilitado para CT-e na Secretaria da Fazenda estadual (IE cadastrada como prestadora de serviço de transporte e credenciamento de CT-e concluído). Sem isso a SEFAZ retorna 230 - IE do emitente não cadastrada; trata-se de uma questão de cadastro fiscal do lado da empresa que a plataforma não consegue resolver.
• A empresa precisa ter uma série de numeração de CT-e (modelo 57). Se nenhuma estiver configurada, ou várias estiverem habilitadas e a requisição não escolher uma, a API retorna 10017007.
• A fase um suporta apenas o modal rodoviário (Rodoviario); outros modais são rejeitados na aceitação (10017018).
• ambienteEmissao deve coincidir com o ambiente atual da empresa (10017010), veja Ambientes.

Autenticação

Idêntica à NF-e: cabeçalhos token / timestamp / sign, com sign = MD5(token + path + body + timestamp) em hexadecimal minúsculo; path inclui o prefixo /openapi e as variáveis de caminho e exclui a query string; GET / DELETE sem corpo usam string vazia; um DELETE com corpo (cancelamento) assina o JSON bruto sem CR/LF. Detalhes do algoritmo, implementações de referência e solução de problemas estão em Autenticação.

Endpoints

Todos os caminhos são relativos a /openapi/v2/empresas/{empresaId}/cte.

Todo evento é enviado de forma síncrona e, em caso de sucesso, devolve o objeto do evento (chaveAcesso, tipo, codigo, sequencia, status, motivo, protocolo, data, linkXml). Os campos de texto são sanitizados (acentos removidos, espaços em branco consolidados) antes da validação de comprimento; as coordenadas são registradas com seis casas decimais.

Nota: os endpoints de prestação em desacordo são os únicos endereçados pela chave de acesso de um CT-e emitido por outra empresa: esta empresa age como recebedora / tomadora daquele documento, e o evento é encaminhado ao estado daquele documento.

Carga do webhook

O registro do webhook e os cabeçalhos de assinatura são compartilhados com a NF-e, veja Webhooks. Quatro códigos de evento são emitidos para CT-e:

cte.authorized, cte.rejected, cte.canceled

Os três eventos de resultado do documento usam a carga de compatibilidade (tipo="CT-e", ordem fixa de campos), paralela aos campos nfe* da NF-e:

{ "tipo": "CT-e", "empresaId": "1934811222334455", "cteId": "CTE-ORD-1", "cteStatus": "Autorizada", "cteMotivoStatus": null,
  "cteLinkDacte": "https://.../openapi/files/dacte/3526...?token=...", "cteLinkXml": "https://.../openapi/files/xml/7?token=...", "cteNumero": "1", "cteSerie": "1",
  "cteChaveAcesso": "3526...", "cteDataEmissao": "2026-09-06T12:00:00Z", "cteDataAutorizacao": "2026-09-06T12:00:03Z",
  "cteNumeroProtocolo": "135260000000001", "cteDigestValue": "..." }

cteLinkDacte e cteLinkXml são utilizáveis assim que o callback de autorização chega (o DACTE é renderizado no primeiro download); os links não precisam de cabeçalhos de assinatura, redirecionam com 302, e sua validade e códigos de erro estão descritos em Download de arquivos.

cte.event.registered

Emitido quando qualquer evento pós-autorização que não seja cancelamento é registrado (carta de correção, comprovante de entrega, insucesso na entrega, prestação em desacordo e seus cancelamentos). Usa o envelope da plataforma (version / event_id / event_type / occurred_at / data):

{
  "version": "1.0",
  "event_id": "7312345678901234567",
  "event_type": "cte.event.registered",
  "occurred_at": "2026-09-06T13:00:00Z",
  "data": {
    "cte_id": "1001",
    "chave": "35260940673061000134570010000000011000000010",
    "external_ref": "CTE-ORD-1",
    "event_code": "110110",
    "n_seq": 1,
    "protocolo": "135260000000099"
  }
}

Modelo de erros

Mesmas formas da NF-e: erros de negócio são [{ "codigo", "mensagem" }] (HTTP 400; documento / tarefa inexistente é HTTP 404 com codigo CTe0001); erros da camada de autenticação usam o envelope da plataforma (401 / 403 / 429, veja Autenticação).

Rejeições da SEFAZ durante a emissão não são erros HTTP: aparecem como status Negada na consulta e como o webhook cte.rejected.

Escopo e limitações

• CT-e modelo 57 versão 4.00, modal rodoviário; documentos normais / complementares / substitutos; todos os cinco tipos de serviço.
• Grupos tributários ICMS 00 / 20 / 40 / 41 / 51 / 60 / 90 / OutraUF / SN + ICMSUFFim + vTotTrib; IBS/CBS na fase dois.
• Contingência: SVC (SVC-RS / SVC-SP) e EPEC são acionados pela plataforma por estado, de forma transparente para os integradores; tipoEmissao na consulta mostra isso. Eventos de documentos autorizados em contingência continuam sendo enviados ao autorizador regular do estado.
• Não suportado: outros modais, multimodal, GTV, CT-e OS (modelo 67), distribuição de documentos recebidos (DistDFe).

Checklist de integração

1. No ambiente de homologação: empresa registrada, certificado vinculado, série de numeração de CT-e configurada.
2. Emita um CT-e mínimo (o exemplo em Emitir CT-e), consulte-o como Autorizada, baixe o XML e o DACTE.
3. Reenvie o mesmo id uma vez e confirme HTTP 200 sem criação de um segundo documento.
4. Registre uma carta de correção e um comprovante de entrega, veja-os na lista de eventos, depois cancele o comprovante de entrega.
5. Cancele o documento, consulte-o como Cancelada, receba o callback cte.canceled.
6. Envie erros deliberados (modal Aereo, soma de componentes divergente) e confirme o array de erros 400.