Endpoints CT-e (Modelo 57)

Referência completa de integração REST para emissão, consulta, cancelamento, DACTE e averbação de seguro do CT-e 4.00. Todas as rotas aceitam autenticação via header x-api-key.

1. Emissão de CT-e

Enfileira a emissão assíncrona do CT-e na SEFAZ. O worker assina o XML digitalmente com o Certificado A1 do projeto e faz a transmissão com failover automático.

POST/cte/emitir🔑 x-api-key

Recebe o payload estruturado do CT-e, valida regras tributárias e enfileira na máquina de estados. Retorna HTTP 202 com invoiceId e status 'queued'.

Parâmetros da Requisição (Nível Raiz)

Campo	Tipo	Req?	Descrição
serie	number	não	Número de série do CT-e (ex: 1). Se omitido, utiliza a série padrão configurada no projeto.
dados	object	sim	Objeto contendo todos os dados operacionais, fiscais e de rota do transporte.
seguro	object	não	Dados da apólice para averbação securitária desacoplada: { seguradora, cnpjSeguradora, apolice, apoliceRcv, cnpjSeguradoraRcv }.

Campos Amigáveis do Objeto 'dados'

Campo	Tipo	Req?	Descrição
cfop	string	sim	Código Fiscal de Operações (ex: "5352" para estadual ou "6352" para interestadual).
naturezaOperacao	string	não	Descrição clara da operação (padrão: "Prestação de serviço de transporte").
origem	object	sim	{ codigoMunicipio: 3550308, municipio: "São Paulo", uf: "SP" } — Local de início/coleta da carga.
destino	object	sim	{ codigoMunicipio: 3304557, municipio: "Rio de Janeiro", uf: "RJ" } — Local de término/entrega da carga.
tomador	string \| object	sim	"remetente" (CIF), "destinatario" (FOB), "expedidor", "recebedor" ou { tipo: "outro", dados: { cpfCnpj, razaoSocial, endereco: ... } } para terceiro pagador.
remetente	object	sim	Remetente: { cpfCnpj, inscricaoEstadual, razaoSocial, nomeFantasia, telefone, email, endereco: { logradouro, numero, complemento, bairro, codigoMunicipio, municipio, uf, cep } }.
destinatario	object	sim	Destinatário: { cpfCnpj, inscricaoEstadual, razaoSocial, endereco: { logradouro, numero, complemento, bairro, codigoMunicipio, municipio, uf, cep } }.
expedidor	object	não	Expedidor intermediário (em redespacho): dados completos com documento, razão social e endereço.
recebedor	object	não	Recebedor intermediário (em transbordo/redespacho): dados completos com documento, razão social e endereço.
valores	object	sim	{ valorTotal: 1500.00, valorReceber: 1500.00, componentes: [ { nome: "FRETE VALOR", valor: 1200.00 }, { nome: "PEDAGIO", valor: 300.00 } ] }.
impostos	object	sim	{ icms: { cst: "00", baseCalculo: 1500.00, aliquota: 12.00, valor: 180.00 } } ou { icms: { cst: "SN" } } para optantes do Simples Nacional.
carga	object	sim	{ valorTotal: 85000.00, produtoPredominante: "MÓVEIS", quantidades: [ { unidade: "KG", tipoMedida: "PESO BRUTO", quantidade: 4500.00 } ] }.
documentosOriginarios	object	sim	{ tipo: "nfe", chaves: ["35261011222333000181550010000009991556677885"] } — Lista de chaves de 44 dígitos das NF-e acobertadas.
observacoes	string	não	Informações complementares de interesse do contribuinte impressas no DACTE (até 2000 caracteres).

Exemplo Completo 1: CT-e Rodoviário Normal com ICMS (Payload Amigável)

{
  "serie": 1,
  "dados": {
    "cfop": "5352",
    "naturezaOperacao": "Prestação de serviço de transporte",
    "origem": {
      "codigoMunicipio": 3550308,
      "municipio": "São Paulo",
      "uf": "SP"
    },
    "destino": {
      "codigoMunicipio": 3304557,
      "municipio": "Rio de Janeiro",
      "uf": "RJ"
    },
    "tomador": {
      "tipo": "remetente"
    },
    "remetente": {
      "cpfCnpj": "11.222.333/0001-81",
      "inscricaoEstadual": "123456789012",
      "razaoSocial": "Fábrica de Móveis Paulista Ltda",
      "nomeFantasia": "Móveis Paulista",
      "telefone": "11987654321",
      "email": "[email protected]",
      "endereco": {
        "logradouro": "Av Industrial",
        "numero": "1500",
        "complemento": "Galpão A",
        "bairro": "Distrito Industrial",
        "codigoMunicipio": 3550308,
        "municipio": "São Paulo",
        "uf": "SP",
        "cep": "01001-000"
      }
    },
    "destinatario": {
      "cpfCnpj": "44.555.666/0001-99",
      "inscricaoEstadual": "987654321098",
      "razaoSocial": "Distribuidora Rio de Janeiro SA",
      "endereco": {
        "logradouro": "Rua do Comércio",
        "numero": "250",
        "bairro": "Centro",
        "codigoMunicipio": 3304557,
        "municipio": "Rio de Janeiro",
        "uf": "RJ",
        "cep": "20010-000"
      }
    },
    "valores": {
      "valorTotal": 1500,
      "valorReceber": 1500,
      "componentes": [
        {
          "nome": "FRETE VALOR",
          "valor": 1200
        },
        {
          "nome": "PEDAGIO",
          "valor": 200
        },
        {
          "nome": "GRIS",
          "valor": 100
        }
      ]
    },
    "impostos": {
      "icms": {
        "cst": "00",
        "baseCalculo": 1500,
        "aliquota": 12,
        "valor": 180
      }
    },
    "carga": {
      "valorTotal": 85000,
      "produtoPredominante": "MÓVEIS E ESQUADRIAS",
      "quantidades": [
        {
          "unidade": "KG",
          "tipoMedida": "PESO BRUTO",
          "quantidade": 4500
        },
        {
          "unidade": "M3",
          "tipoMedida": "METROS CÚBICOS",
          "quantidade": 22.5
        }
      ]
    },
    "documentosOriginarios": {
      "tipo": "nfe",
      "chaves": [
        "35261011222333000181550010000009991556677885"
      ]
    }
  },
  "seguro": {
    "seguradora": "PORTO SEGURO CIA DE SEGUROS",
    "apolice": "123456789",
    "apoliceRcv": "RCV-998877"
  }
}

Exemplo 2: CT-e para Transportadora Simples Nacional

{
  "impostos": {
    "icms": {
      "cst": "SN"
    }
  }
}

Este trecho substitui o objeto impostos do exemplo completo. Para outros regimes, envie o CST e os valores de base, alíquota e ICMS conforme a apuração fiscal da operação; a API valida e transmite os valores informados, mas não determina o enquadramento tributário nem calcula o imposto.

Tomador terceiro e operações com mais de uma transportadora

Para um pagador que não seja remetente, expedidor, recebedor ou destinatário, use tomador: { tipo: "outro", dados: ... } com documento, razão social e endereço completos. Os campos expedidor e recebedor identificam participantes quando aplicável. O contrato atual não oferece um seletor explícito do tipo de serviço (redespacho, redespacho intermediário ou subcontratação); confirme o enquadramento e a compatibilidade antes de usar esses participantes nesses fluxos.

2. Consulta de Status, XML e DACTE

Acompanhe o estado de processamento, obtenha o XML distribuído com protocolo de autorização e gere o DACTE oficial em PDF.

GET/cte/invoices/{id}/status🔑 x-api-key

Retorna o status em tempo real do CT-e, protocolo SEFAZ, chave de 44 dígitos, data de autorização e situação da averbação securitária.

{
  "id": "8c9735d4-482a-4a25-a18c-36b04874b711",
  "status": "issued",
  "numero": 1420,
  "serie": 1,
  "chaveAcesso": "35261011222333000181570010000014201000014209",
  "protocoloAutorizacao": "135260000000001",
  "dataAutorizacao": "2026-10-01T21:40:05.000Z",
  "cStat": 100,
  "xMotivo": "Autorizado o uso do CT-e",
  "averbacao": {
    "status": "approved",
    "protocolo": "ATM-2026-991823",
    "mensagem": "Averbação homologada na seguradora"
  }
}

GET/cte/invoices/{id}/xml🔑 x-api-key

Retorna o XML oficial do documento (cteProc com protCTe assinado). Disponível para CT-e com status 'issued' ou 'cancelled'.

GET/cte/invoices/{id}/dacte🔑 x-api-key

Gera e retorna o PDF do DACTE pronto para impressão ou visualização inline no navegador.

Exemplo de Visualização e Download do DACTE

O endpoint retorna o arquivo com Content-Disposition: inline para abertura imediata. Você também pode testar a renderização visual em nossos links públicos:

Abrir Visualizador Web do DACTE →·Baixar PDF Binário (/api/examples/dacte-pdf) →

3. Cancelamento de CT-e (Evento 110111)

Permite cancelar um CT-e autorizado na SEFAZ desde que a prestação do serviço ainda não tenha sido iniciada e esteja dentro do prazo legal de 168 horas (7 dias).

POST/cte/cancelar🔑 x-api-key

Registra o Evento de Cancelamento (110111) na SEFAZ de origem. O cancelamento é gratuito e não consome créditos.

Body (JSON)

Campo	Tipo	Req?	Descrição
invoiceId	string (UUID)	sim	ID do documento gerado na emissão.
justificativa	string	sim	Motivo do cancelamento (mínimo 15 e máximo 255 caracteres).

{
  "invoiceId": "8c9735d4-482a-4a25-a18c-36b04874b711",
  "justificativa": "Cancelamento solicitado pelo cliente devido a erro de faturamento do frete"
}

4. Averbação de Seguros AT&M

Disparo manual ou reprocessamento de averbação securitária para CT-e já autorizado.

POST/cte/{id}/averbar🔑 x-api-key

Envia os dados da carga e das apólices para o gateway de averbação (AT&M / Porto / Tokio / Sompo). Processamento assíncrono com webhooks de retorno.

curl -X POST https://platform.notaas.com.br/api/v1/cte/8c9735d4-482a-4a25-a18c-36b04874b711/averbar \
  -H "x-api-key: $NOTAAS_API_KEY"

Diagnóstico e Resolução de Rejeições SEFAZ

Abaixo estão as rejeições mais comuns do CT-e e como evitá-las no seu envio:

Rejeição 204 — Duplicidade de CT-eSEFAZ

Causa: Já existe um CT-e autorizado com o mesmo número, série e CNPJ emitente.
Solução: A Notaas gerencia a numeração sequencial automaticamente, mas caso informe a série manualmente, certifique-se de não reinicializar o número.

Rejeição 220 — Prazo de Cancelamento Superior ao PrevistoSEFAZ

Causa: Tentativa de cancelamento após 168 horas da data/hora de autorização.
Solução: Utilize a emissão de CT-e de Anulação ou Substituição caso o prazo legal tenha expirado.

Rejeição 694 — Chave de Acesso de NF-e Inválida nos Documentos OrigináriosSEFAZ

Causa: O campo infDoc.infNFe[].chave contém uma chave com dígito verificador incorreto ou formato diferente de 44 dígitos.