O que a API de CT-e faz
O CT-e documenta a prestação de transporte de carga; o CT-e OS cobre transporte de pessoas, de valores e de excesso de bagagem. Os contratos de CT-e e CT-e OS são separados; consulte o OpenAPI versionado e as capacidades do emitente.
| Operação | O que acontece | Retorno |
|---|---|---|
| Emitir CT-e | Monta o XML 4.00 do modelo 57, assina e transmite. | HTTP 202, operação; após autorização, XML e DACTE |
| Consultar | Consulta a situação pela chave de acesso. | Situação atual e protocolos |
| Cancelar | Registra o cancelamento, conferidos prazo e impedimentos. | Protocolo do evento |
| Corrigir | Registra a carta de correção nos campos que a admitem. | Protocolo do evento |
| Baixar arquivos | Entrega o XML autorizado e o DACTE. | XML e PDF |
Como funciona a emissão de CT-e por API
-
Prestação em JSON
Tomador, remetente, destinatário e, quando houver, expedidor e recebedor; valor da prestação e componentes; ICMS do transporte; modal.
toma3 -
Documentos transportados
As chaves das NF-e da carga ou os dados dos outros documentos que acompanham o transporte.
infNFe -
XML e chave
A API monta o XML no leiaute 4.00 e calcula a chave de acesso de 44 dígitos.
infCte -
Assinatura e autorização
O XML é assinado com o A1 do emitente e transmitido à SEFAZ que atende a UF.
CTeRecepcaoSincV4 -
DACTE
Autorizado o CT-e, o DACTE pode acompanhar a carga; sua aplicação entrega o XML ao tomador. A API não envia e-mail nem mensagem automaticamente.
O passo a passo do preenchimento está no guia como emitir CT-e; para identificar quem paga o frete, veja tomador do CT-e.
Exemplo de emissão de CT-e
POST https://erp.fideflow.com.br/api/flow-fiscal/v1/homologacao/emitentes/{emitente}/documentos/cte
Authorization: Bearer {credencial_de_homologacao}
Content-Type: application/json
Idempotency-Key: exemplo-cte-001
{
"referencia_externa": "exemplo-cte-001",
"dados": {
"cabecalho": {
"natureza_id": 1,
"municipio_envio": 1,
"municipio_inicio": 1,
"municipio_fim": 1,
"valor_transporte": "10.00",
"valor_receber": "10.00",
"cst": "90",
"perc_icms": "0.00",
"cfop": "5352",
"veiculo_id": 1,
"remetente_id": 1,
"destinatario_id": 1,
"tomador": 0,
"produto_predominante": "Mercadoria",
"valor_carga": "10.00"
},
"componentes": [
{
"nome": "Frete",
"valor": "10.00"
}
],
"medidas": [
{
"cod_unidade": "01",
"tipo_medida": "PESO BRUTO",
"quantidade": "1.00"
}
],
"referencias": [
{
"chave": "35261011222333000181550010000000011000000012"
}
]
}
}Exemplo de homologação extraído do OpenAPI v1. IDs e valores são fictícios e precisam corresponder aos cadastros e à operação do emitente; HTTP 202 ainda não é autorização fiscal.
Pontos de atenção no CT-e
- Inutilização: o serviço foi extinto em 2023 (NT 2023.001) e não existe no leiaute 4.00. Número pulado não precisa mais ser comunicado ao Fisco.
- Cancelamento: a referência técnica é de 168 horas após a autorização, e o prazo não é o único requisito. Veja cancelamento de CT-e.
- Carta de correção: não corrige valores da prestação nem partes do documento. Veja carta de correção do CT-e.
- Valor a mais: o acréscimo vai em CT-e complementar, que referencia o original.
- MDF-e: o manifesto acompanha a carga em boa parte das operações. Entenda a diferença em CT-e vs MDF-e.
Perguntas frequentes sobre a API de CT-e
Ainda preciso inutilizar numeração de CT-e?
Não. O serviço de inutilização do CT-e foi extinto com a NT 2023.001, em 2023, e não existe no leiaute 4.00. A quebra de sequência deixou de ser comunicada ao Fisco.
Qual a diferença entre CT-e e CT-e OS?
O CT-e (modelo 57) documenta o transporte de cargas. O CT-e OS (modelo 67) documenta outros serviços: transporte de pessoas, de valores e de excesso de bagagem.
Qual é o prazo para cancelar um CT-e?
A referência técnica para os modelos 57 e 67 é de 168 horas após a autorização. O prazo não é o único requisito: o cancelamento é recusado, por exemplo, quando há eventos ou documentos vinculados que o impedem.
O tomador pode registrar desacordo pela API?
O contrato de emissão de CT-e desta API não oferece o evento de prestação em desacordo. Esse evento pertence ao tomador do serviço; entenda prazo e efeito no guia desacordo do CT-e.
Fontes oficiais
No teste grátis do Flow Fiscal, a API de emissão vem completa, sem contratar; depois do teste, requer plano Flow Fiscal ativo e o opcional de emissão contratado. Exige certificado A1 válido e vínculo autorizado de cada CNPJ. CT-e, CT-e OS e MDF-e atendem o modal rodoviário; NFS-e segue o padrão nacional e os requisitos do município. Consulte as capacidades do emitente antes de transmitir.