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.
Pré-requisitos do Projeto (Emitente) e Controle de Numeração
- RNTRC (ANTT): Obrigatório para o modal rodoviário (
infModal/rodo/RNTRC, exatamente 8 dígitos numéricos). É lido diretamente do cadastro do projeto — configure no painel (Configurações → Configuração CT-e / MDF-e) ou via Org API (PATCH /api/v1/org/projects/{id}com"rntrc": "55565677"). - Inscrição Estadual e CRT: O projeto deve ter
inscricaoEstadual,crt(ouregimeTributario) e endereço completo configurados. - Reforma Tributária (IBS/CBS e
vTotDFe— NT 2025.001 / NT 2026.002 / NT 2026.004 / NT 2026.005): A tag<vTotDFe>é gerada automaticamente em todas as emissões. Para emitentes em Regime Normal (CRT = 3), o grupo<IBSCBS>é obrigatório em Homologação (desde 01/07/2026) — você pode configurar os padrõesdefault_cst_ibscbsedefault_classificacao_tributariano projeto (ex. ilustrativo para operação tributada integralmente:"000"e"000001", devendo ocClassTribcorresponder ao enquadramento fiscal real da operação) ou informardados.impostos.ibscbsno payload. Para Simples Nacional (CRT = 1ou2) e MEI (CRT = 4), o grupo<IBSCBS>é omitido automaticamente quando não enviado, e o envio deibscbsno payload para esses CRTs retorna HTTP 422 (NT 2026.005 v1.00). - Continuidade de Numeração (
nCT): Para iniciar as emissões a partir de uma numeração já existente em outro sistema (ex: último emitido =357, próximo =358), ajuste o campo Último Nº CT-e emConfigurações → Numeraçãoou chameGET/PATCH /api/v1/org/projects/{id}/numeracaocom{ "ultimoNumeroCte": 357, "serieCte": 1 }. O ajuste utiliza semânticaGREATEST(nunca retrocede o contador) e descarta números recicláveis<= 357.
/cte/emitir🔑 x-api-keyRecebe 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 (0 a 889, ex: 1). Se omitido, utiliza a série padrão do projeto (serieCte / cte_serie_padrao, padrão 1). |
| 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 | Aceita string ("remetente", "destinatario", "expedidor", "recebedor"), objeto { tipo: "remetente" | "destinatario" | "expedidor" | "recebedor" } ou { tipo: "outro", dados: { cpfCnpj, inscricaoEstadual, razaoSocial, endereco: ... } } para terceiro pagador. O indicador indIEToma é derivado automaticamente da inscricaoEstadual do papel selecionado. |
| remetente | object | sim | Remetente: { cpfCnpj (CPF 11 dígitos ou CNPJ 14 posições numérico/alfanumérico [0-9A-Z]{12}\d{2}), inscricaoEstadual, razaoSocial, nomeFantasia, telefone, email, endereco: { logradouro, numero, complemento, bairro, codigoMunicipio, municipio, uf, cep } }. |
| destinatario | object | sim | Destinatário: { cpfCnpj (CPF 11 dígitos ou CNPJ 14 posições numérico/alfanumérico [0-9A-Z]{12}\d{2}), 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 | Tributação ICMS e IBS/CBS: { icms: { cst: "00", baseCalculo: 1500.00, aliquota: 12.00, valor: 180.00 }, ibscbs?: { cst: "000", cClassTrib: "000001", baseCalculo?: number, aliquotaIbsEstadual?: number, aliquotaIbsMunicipal?: number, aliquotaCbs?: number, doacao?: boolean }, vTotTrib?: number, infAdFisco?: string } ou { icms: { cst: "SN" } } para Simples Nacional. Para CRT = 3 (Regime Normal), ibscbs é obrigatório em homologação caso o projeto não tenha default_cst_ibscbs e default_classificacao_tributaria configurados ("000"/"000001" são valores ilustrativos para tributação integral; o cClassTrib deve refletir a operação fiscal real). Para CRT = 1, 2 ou 4, não envie ibscbs (o grupo é omitido automaticamente; enviá-lo retorna HTTP 422). Tuplas CST × cClassTrib aceitas para o modal rodoviário (Tabela cClassTrib v1.71): CST "000" com "000001"; CST "200" com "200001" ou "200020" (redução de alíquota <gRed>); CST "410" com "410001", "410003", "410004", "410015", "410027", "410035" ou "410999" (imunidade/não incidência sem <gIBSCBS>). Quando vBC é omitida, a engine calcula vBC = vTPrest - vICMS. Nas emissões de 2026, quando as alíquotas são omitidas, a engine aplica automaticamente as alíquotas-teste de 2026 (pIBSUF = 0.10%, pIBSMun = 0.00%, pCBS = 0.90%). Para emissões em 2027/2028 (NT 2026.004 v1.01), as três alíquotas (pIBSUF, pIBSMun e pCBS) são obrigatórias (HTTP 422 se omitidas, mantendo-se pCBS = 0.90% enquanto não publicada a alíquota de referência de 2027). |
| carga | object | sim | { valorTotal: 85000.00, produtoPredominante: "MÓVEIS", quantidades: [ { unidade: "KG", tipoMedida: "PESO BRUTO", quantidade: 4500.00 } ] }. |
| documentosOriginarios | object | sim | { tipo: "nfe", chaves: ["35260512ABC34501DE35550010000000011123456787"] } — Lista de chaves de 44 posições das NF-e acobertadas (suporta chaves numéricas e alfanuméricas conforme NT Conjunta 2025.001, com cDV Módulo 11 ASCII-48). |
| 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
},
"ibscbs": {
"cst": "000",
"cClassTrib": "000001"
}
},
"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.
/cte/invoices/{id}/status🔑 x-api-keyRetorna o status em tempo real do CT-e, protocolo SEFAZ, chave de 44 posições (numérica ou alfanumérica conforme NT Conjunta 2025.001), data de autorização e situação da averbação securitária.
{
"invoiceId": "8c9735d4-482a-4a25-a18c-36b04874b711",
"status": "issued",
"modelo": 57,
"serie": 1,
"numero": 1420,
"chaveAcesso": "35261011222333000181570010000014201000014209",
"tpAmb": 1,
"cStat": 100,
"xMotivo": "Autorizado o uso do CT-e",
"nProt": "135260000000001",
"dhRecbto": "2026-10-01T21:40:05.000Z",
"createdAt": "2026-10-01T21:40:00.000Z",
"updatedAt": "2026-10-01T21:40:05.000Z",
"eventos": [],
"xmlUrl": "/api/v1/cte/invoices/8c9735d4-482a-4a25-a18c-36b04874b711/xml",
"pdfUrl": "/api/v1/cte/invoices/8c9735d4-482a-4a25-a18c-36b04874b711/dacte",
"averbacao": {
"status": "approved",
"numero": "ATM-2026-991823",
"erro": null
}
}/cte/invoices/{id}/xml🔑 x-api-keyRetorna o XML oficial distribuído do documento (cteProc com protCTe assinado). Disponível exclusivamente para CT-e com status 'issued' ou 'cancelled'. Caso o documento esteja em 'queued', 'processing', 'rejected' ou 'authorization_unknown' (contenção de segurança quando ocorre timeout/retorno inconclusivo da SEFAZ para proteger a numeração contra duplicidade), o endpoint retorna HTTP 409 Conflict.
/cte/invoices/{id}/dacte🔑 x-api-keyGera e retorna o PDF do DACTE pronto para impressão ou visualização inline no navegador.
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:
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).
/cte/cancelar🔑 x-api-keyRegistra 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.
/cte/{id}/averbar🔑 x-api-keyEnvia 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:
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.
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.
Causa: O campo infDoc.infNFe[].chave contém uma chave com dígito verificador incorreto ou formato diferente de 44 dígitos.