Emitir CIOT
O CIOT (Código Identificador da Operação de Transporte) é o registro, na ANTT, da operação de transporte rodoviário de cargas e do pagamento do frete. A API do FazNota declara a operação na ANTT, devolve o código do CIOT e permite cancelar, retificar e encerrar.
Disponível desde a versão 3.13.0.
Para quem é
A emissão é direta pela empresa de transporte:
- ETC (Empresa de Transporte Rodoviário de Cargas) com RNTRC ativo, emitindo para a própria frota;
- carga lotação (
TipoOperacao1) ou carga fracionada (TipoOperacao2).
Pré-requisitos no cadastro da empresa (FazNota)
- Certificado digital A1 da ETC. O A3 não serve, porque exige o token físico para assinar.
- CNPJ e RNTRC da ETC cadastrados. Os dois vão como contratado na declaração, e você não precisa enviá-los.
- O veículo informado precisa estar na frota da ETC no RNTRC.
- O ambiente (homologação ou produção) segue a configuração da empresa no FazNota.
Fluxo
Como toda operação da v3, o CIOT é assíncrono: você envia o pedido, recebe um recibo e
consulta o resultado.
-
Emitir
Terminal window curl -X POST $BASE/ciot/emissao \-H "Authorization: Token $TOKEN" \-H "Content-Type: application/json" \-d '{"numero-origem": "VIAGEM-2026-1021","TipoOperacao": 1,"CpfCnpjContratante": "12345678000199","CpfCnpjDestinatario": "98765432000155","ValorFrete": 1500.00,"Veiculos": [ { "Placa": "ABC1D23", "NumeroEixos": "4" } ],"OrigemDestino": [ {"Origem": { "CodigoMunicipioOrigem": 4127700 },"Destino": { "CodigoMunicipioDestino": 4104808 },"DistanciaPercorrida": 45} ],"DadosCarga": { "CodigoNaturezaCarga": 9999, "CodigoTipoCarga": 5, "PesoCarga": 1000 },"InfIndicadoresOperacionais": {"IndAltoDesempenho": false, "IndRetornoVazio": false, "ComposicaoVeicular": false},"InfPagamento": [ { "TipoPagamento": 6, "IndPagamento": 0,"ChavePix": "[email protected]","IdentificadorPix": "FRETE-2026-1021" } ]}'Resposta:
{ "status": "001", "descricao": "Operação de CIOT registrada com sucesso.","data": { "recibo": "..." } } -
Consultar o resultado
Faça polling com intervalo mínimo de 2 segundos:
Terminal window curl $BASE/ciot/{recibo} -H "Authorization: Token $TOKEN"Quando a ANTT gera o CIOT:
{"status": "004","descricao": "CIOT emitido pela ANTT.","data": {"processo": "emissao","situacao": "EMITIDO","ciot": "123456789012","codigo-verificador": "1234","protocolo": "...","tipo-operacao": 1,"ambiente": "producao","data-emissao": "2026-10-21 14:30:05","antt": { "codigo": "110", "mensagem": "Dados inseridos com sucesso", "aviso-transportador": "" }}}
Campos da emissão
Os nomes seguem o leiaute PEF da ANTT.
| Campo | Obrigatório | Regra |
|---|---|---|
numero-origem | recomendado | Identifica a operação no seu sistema. Veja Retry |
TipoOperacao | sim | 1 carga lotação, 2 carga fracionada |
CpfCnpjContratante | sim | Quem contrata o frete, sem pontuação |
CpfCnpjDestinatario | sim | Destinatário da carga |
ValorFrete | sim | Maior que zero |
DataDeclaracao | não | AAAA-MM-DDTHH:MM:SS, horário de Brasília. Se omitida, usa o momento do envio |
IndContingencia / JustificativaContingencia | não | A justificativa só vai, e então é obrigatória, quando IndContingencia é true |
Veiculos | sim | Exatamente um veículo automotor: Placa (7 caracteres, sem hífen) e NumeroEixos (mínimo 2) |
OrigemDestino | sim | Pares Origem/Destino usando o mesmo tipo de localização (município IBGE, CEP ou latitude/longitude) e DistanciaPercorrida em km |
DadosCarga | sim | CodigoNaturezaCarga, CodigoTipoCarga (1 a 12) e PesoCarga em kg |
InfIndicadoresOperacionais | na carga lotação | IndAltoDesempenho, IndRetornoVazio, ComposicaoVeicular |
InfPagamento | sim | Ao menos uma forma. Veja abaixo |
Não envie CpfCnpjContratado, RNTRCContratado nem IdOperacaoTransporte. Os dois
primeiros vêm do cadastro da empresa e o terceiro é gerado pelo FazNota. Se vierem, são
substituídos.
CodigoTipoCarga
| Código | Tipo |
|---|---|
| 1 | Granel sólido |
| 2 | Granel líquido |
| 3 | Frigorificada ou aquecida |
| 4 | Conteinerizada |
| 5 | Carga geral |
| 6 | Neogranel |
| 7 | Perigosa granel sólido |
| 8 | Perigosa granel líquido |
| 9 | Perigosa frigorificada ou aquecida |
| 10 | Perigosa conteinerizada |
| 11 | Perigosa carga geral |
| 12 | Carga granel pressurizada |
InfPagamento
TipoPagamento | Forma | Campos exigidos |
|---|---|---|
| 2 | Conta corrente | NumeroAgencia, NumeroConta |
| 3 | Conta poupança | NumeroAgencia, NumeroConta |
| 4 | Conta de pagamento | NumeroAgencia, NumeroConta |
| 5 | Outros | nenhum |
| 6 | Pix | ChavePix, IdentificadorPix |
IndPagamento: 0 à vista, 1 a prazo. A prazo exige NumeroParcela, DataVencimento e
ValorParcela; à vista não aceita esses campos. O tipo 1 (cartão de Instituição de Pagamento)
não se aplica à emissão direta por ETC.
Retry
Envie sempre um numero-origem estável por operação (por exemplo, o número da viagem). Com ele:
- reenviar a mesma operação devolve o recibo original, se ela já foi processada, foi recusada ou ainda está na fila;
- se a tentativa anterior terminou em erro técnico (
status: "999", como falha de comunicação com a ANTT), o reenvio com o mesmonumero-origemé aceito e gera um recibo novo. A ANTT recebe o mesmo identificador de operação, e não uma operação nova, o que evita um segundo CIOT para a mesma viagem.
Eventos
Nos três eventos, identifique o CIOT por ciot (o código, com ou sem o verificador) ou por
recibo (o da emissão). Cada evento devolve o seu próprio recibo, consultado em
GET /ciot/{recibo}.
Cancelar
curl -X POST $BASE/ciot/cancelamento \ -H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \ -d '{ "ciot": "123456789012", "motivo": "Viagem cancelada pelo contratante." }'O motivo é obrigatório para CIOT emitido, com até 500 caracteres. Um CIOT que a ANTT
recusou é só marcado como cancelado no FazNota, sem chamada à ANTT. A consulta do recibo
responde status: "010".
Retificar
Só para carga fracionada (TipoOperacao 2) já emitida. Carga lotação não admite
retificação: cancele e emita outro.
curl -X POST $BASE/ciot/retificacao \ -H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \ -d '{ "recibo": "...", "ValorFrete": 1650.00, "PesoCarga": 1200 }'Campos corrigíveis: ValorFrete, CodigoMunicipioOrigem e CodigoMunicipioDestino (sempre os
dois juntos, código IBGE), CodigoNaturezaCarga, PesoCarga e CodigoTipoCarga. Informe ao
menos um.
Encerrar
curl -X POST $BASE/ciot/encerramento \ -H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \ -d '{ "ciot": "123456789012" }'Status da consulta
status | Significado |
|---|---|
002 | Ainda na fila. Consulte de novo |
004 | Emitido. No recibo de um evento: retificado ou encerrado |
010 | Cancelado |
900 | Recusado pela ANTT ou pela validação do leiaute. Motivo em data.erro ou em data.antt.mensagem |
999 | Erro ao processar (por exemplo, certificado vencido ou falha de comunicação com a ANTT). Detalhe em data.erro |
500 | Recibo inexistente |
No recibo da emissão, data.situacao mostra a situação atual do CIOT: EMITIDO,
ENCERRADO, CANCELADO ou REJEITADO.
Recusado na hora (status: "400")
O pedido nem entra na fila, e o motivo vem em data.erro, quando:
TipoOperacaoé diferente de 1 e 2;- a empresa usa certificado A3, ou não tem certificado A1, CNPJ ou RNTRC da ETC cadastrado;
- no evento, o CIOT não é desta empresa, ou a situação não permite a operação (por exemplo, encerrar um CIOT que não está emitido).
As demais regras do leiaute (veículo, origem e destino, carga, pagamento) são conferidas no
processamento. Se alguma falhar, a consulta do recibo responde status: "900" com o motivo.
Rejeições comuns da ANTT
| Situação | Causa provável |
|---|---|
| ”O CPF/CNPJ do certificado digital não corresponde a nenhum transportador cadastrado no RNTRC” | O certificado não é o da ETC com RNTRC, ou o RNTRC não está ativo |
| Placa fora da frota | O veículo não está vinculado ao RNTRC da ETC |
| Transportador não é ETC ou é equiparado a TAC | A operação exige Instituição de Pagamento Eletrônico de Frete |