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, o que a plataforma não pode 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 sem corpo usa string vazia; POST assina o JSON bruto sem CR/LF (um POST sem corpo assina a string vazia). 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; 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": "35260940673061000134570010000000011000000016",
    "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. Emita um segundo CT-e e cancele esse, consulte-o como Cancelada, receba o callback cte.canceled. Um documento com carta de correção registrada não pode mais ser cancelado, por isso este passo usa outro documento.
6. Envie erros deliberados (modal Aereo, soma de componentes divergente) e confirme o array de erros 400.