CIOT - Código Identificador de Operação de Transportes (CIOT Online)

1. Visão geral

A CIOT Online (ciotonline.com.br) é a quarta plataforma de emissão de CIOT integrada ao TryERP, ao lado da eFrete, da Extratta e da ANTT direta. A integração é feita por API REST com autenticação por token, somente em ambiente de produção (a plataforma não possui homologação).

Principais características:

• Emissão em uma única chamada — não há pré-cadastro de motorista, veículo ou proprietário na plataforma;
• Ciclo completo: emitir, consultar, cancelar, encerrar e retificar;
• Consultas auxiliares sem custo: validação de placa na ANTT, piso mínimo de frete e saldo de créditos;
• Cada emissão (e cada retificação) consome 1 crédito do pacote contratado pelo cliente junto à CIOT Online.

Onde aparece no TryERP: na emissão do MDF-e (botão de gerar CIOT — a opção "CIOT Online" aparece no seletor de plataformas quando a filial possui o token configurado) e na tela Consulta de CIOT (plataforma "CiotOnline" no filtro).

2. Configuração inicial

2.1 Obter o token no painel da CIOT Online

1. Acesse ciotonline.com.br/login com a conta da empresa;
2. No menu lateral, abra Desenvolvedor → Tokens;
3. Clique em Gerar token e informe um nome identificador (ex.: "TryERP Produção");
4. Copie o token imediatamente — ele é exibido uma única vez (formato ciot_XXXX...).

Segurança: o token dá acesso à emissão de CIOTs (consome créditos). Não compartilhe por e-mail/WhatsApp; se vazar, revogue no painel e gere um novo.

2.2 Configurar no TryERP

Em Configurações Adicionais → aba CIOT Online:

Campo	Descrição
Filial	Filial que utilizará a plataforma. O token é por filial.
Token	Token gerado no painel (passo 2.1). Use Testar Token para validar a conexão antes de salvar.
Endereço (URL)	URL base da API. Padrão: https://ciotonline.com.br/api/v1/ — só altere por orientação do suporte.

Após salvar o token, a opção CIOT Online passa a aparecer automaticamente no seletor de plataformas da emissão do MDF-e para essa filial.

3. Emissão do CIOT

3.1 Formas de abrir a tela

• Pela emissão do MDF-e (recomendado): os dados do MDF-e — contratado, destinatário, municípios, veículos, datas, valores e pagamento — já vêm preenchidos. Tudo permanece editável;
• Manual: na tela Consulta de CIOT, selecione a plataforma "CiotOnline" e clique em Novo. Preencha os campos e selecione os veículos.

3.2 Campos da tela

Campo	Obrigatório	Observações
Tipo de viagem	Opcional	1 - Normal (padrão) ou 3 - TAC.
Natureza da carga	Opcional	Padrão 0001. O botão ao lado abre a consulta de naturezas mapeadas.
Contratado (transportador)	Obrigatório	Parceiro do cadastro. O CPF/CNPJ é exigido pela ANTT (só o RNTRC não basta).
Contratante	Opcional	Se vazio, a CIOT Online usa a empresa vinculada ao token. Recomendado sempre selecionar.
Destinatário	Obrigatório	Parceiro do cadastro — endereço e código IBGE saem do cadastro do parceiro.
Município de origem / destino	Obrigatório	Cidade do cadastro (o código IBGE sai do cadastro da cidade). CEP é opcional.
Veículo Tração	Obrigatório	Veículo de tração do cadastro. Eixos e placa saem do cadastro do veículo.
Carretas	Opcional	Reboques que compõem a operação (a ANTT soma os eixos de todos os veículos para o piso).
Início / Fim da viagem	Obrigatório	Pré-preenchidos com a data do documento/hoje.
Distância (km)	Obrigatório	Maior que zero — é a base do piso mínimo da ANTT.
Peso da carga (kg)	Obrigatório	Maior que zero e menor que 9.999.999,99 (regra da ANTT).
Valor do frete	Obrigatório	Em reais.
Pedágio / Combustível / Tarifas	Opcional	Valores em reais (padrão 0).
Retorno vazio	Opcional	Marque quando o veículo volta sem carga — a ANTT soma a volta ao piso mínimo.
Só unidade de tração	Automático	Marcado automaticamente quando há tração sem carretas (Tabela B da ANTT). Pode ser ajustado.
Veículo de alto desempenho	Opcional	Configuração especial da ANTT; na maioria das viagens, desmarcado.
Tipo de pagamento / Banco / Agência / Conta / Titular	Opcional	Dados do pagamento ao transportador. CPF/CNPJ do titular é validado (dígitos verificadores).

3.3 Carga fracionada (mais de um embarcador)

Quando vários embarcadores participam da mesma contratação, use o grupo Carga fracionada: selecione cada parceiro embarcador e clique em Incluir embarcador (os dados saem do cadastro). Para remover, use o botão da linha ou a tecla Delete. Havendo ao menos um embarcador na lista, a operação é enviada automaticamente como fracionada. Quando o MDF-e tem múltiplos contratantes, a lista já vem pré-preenchida.

3.4 Botões auxiliares (sem custo)

Botão	O que faz
Consultar piso mínimo	Calcula o piso mínimo de frete da ANTT (tabela oficial vigente) com a distância, o tipo de carga e a soma dos eixos de todos os veículos.
Consulta Saldo de Créditos	Exibe o saldo disponível e o detalhamento dos pacotes contratados (utilizados, disponíveis, validade).

3.5 O que acontece ao clicar em Emitir (ou F5)

1. Validações locais: campos obrigatórios, peso dentro da faixa, CPF/CNPJ do titular da conta;
2. Validação dos veículos na ANTT (sem custo): o vínculo placa ↔ RNTRC de cada veículo é conferido na consulta pública da ANTT. Vínculo inválido bloqueia a emissão e exibe a mensagem da ANTT — evitando gastar crédito em uma recusa certa;
3. Confirmação: aviso de que a emissão consome 1 crédito;
4. Emissão: em caso de sucesso, o sistema mostra o número do CIOT, o saldo restante e eventuais observações/advertências da ANTT (ex.: distância inferior à calculada), grava o registro completo e preenche o CIOT no MDF-e automaticamente.

Emissão em contingência: se o retorno indicar contingência, o CIOT foi aceito pela plataforma mas ainda não confirmado pela ANTT. Use depois a opção Obter CIOT pelo ID (seção 4.5) para atualizar o número/protocolo definitivos.

4. Consulta e gestão do CIOT

Na tela Consulta de CIOT, selecione a plataforma CiotOnline e pesquise. Operações disponíveis:

4.1 Gerar PDF (Declaração)

Imprime a declaração do CIOT pelo relatório local (mesmo modelo usado pela plataforma ANTT direta).

4.2 Cancelar (sem custo)

Disponível enquanto o CIOT está ativo (antes do início da viagem, conforme regras da ANTT). Exige um motivo com no mínimo 10 caracteres. Em caso de sucesso, o protocolo e a data/hora reais do cancelamento na ANTT ficam registrados no CIOT.

4.3 Encerrar (sem custo)

Informa o fim da operação. A janela solicita: peso total da carga, quantidade e valor das tarifas e quantidade de viagens. O protocolo e a data/hora do encerramento na ANTT ficam registrados.

4.4 Retificar (consome 1 crédito)

Permite corrigir a quantidade/valor das tarifas e, opcionalmente, trocar o veículo (a placa e o RNTRC do proprietário saem do cadastro do veículo selecionado — para veículo próprio, o RNTRC usado é o da filial). O sistema impede a seleção do mesmo veículo já registrado no CIOT (evita gastar crédito sem efeito) e, após o sucesso, atualiza o veículo registrado localmente.

4.5 Obter CIOT pelo ID (menu Outras Operações)

Sincroniza o registro local com a CIOT Online. Use para:

• Confirmar emissão em contingência — atualiza número do CIOT, protocolo e verificador definitivos;
• Refletir ações feitas pelo painel da CIOT Online — se o CIOT foi cancelado/encerrado por lá, o estado, o protocolo e a data da operação são trazidos para o TryERP.

As opções Adicionar Pagamento e Adicionar Viagem do mesmo menu são exclusivas da plataforma eFrete e não se aplicam a CIOTs da CIOT Online.

5. Créditos e custos

Operação	Custo
Emitir CIOT	1 crédito (somente em caso de sucesso)
Retificar CIOT	1 crédito
Consultar / Obter status / Listar	Grátis
Cancelar / Encerrar	Grátis
Validação de placa na ANTT	Grátis (limite de 20 consultas por placa/dia)
Piso mínimo de frete / Saldo	Grátis

Os créditos são contratados pelo cliente diretamente com a CIOT Online (pacotes com validade).

6. Mensagens de erro e soluções

Código / Mensagem	Causa	O que fazer
token_invalido (401)	Token ausente, incorreto ou revogado.	Conferir o token em Configurações Adicionais → CIOT Online; usar "Testar Token". Se revogado, gerar novo no painel.
empresa_inativa (403)	Empresa vinculada ao token desativada na CIOT Online.	Cliente deve contatar a CIOT Online para reativar.
sem_creditos (402)	Saldo de créditos zerado.	Cliente deve contratar pacote no painel da CIOT Online. O saldo pode ser conferido pelo botão "Consulta Saldo de Créditos".
campo_obrigatorio / json_invalido (400)	Payload incompleto/inválido.	Conferir os campos da tela. Se persistir, acionar o suporte interno (registro de atividade — ver seção 7).
status_invalido (422)	Operação não permitida no estado atual (ex.: cancelar um CIOT já encerrado).	Usar "Obter CIOT pelo ID" para sincronizar o estado e verificar a situação real.
emissao_falhou / retificacao_falhou / cancelamento_falhou / encerramento_falhou (422)	A ANTT recusou a operação (dado inválido) ou está indisponível.	Ler a mensagem exibida: se citar um dado (ex.: "Peso da carga deve ser maior que 0"), corrigir e reenviar. Se citar instabilidade da ANTT, aguardar alguns minutos e tentar novamente.
rate_limit (429)	Limite de requisições por minuto/dia excedido (ou 20/dia por placa na validação de veículo).	Aguardar e tentar novamente.
"Token da CIOT Online não configurado para a Filial"	Filial sem token cadastrado.	Configurar conforme a seção 2.
"A ANTT não validou o vínculo do veículo ... com o transportador"	Placa não vinculada ao RNTRC informado na base pública da ANTT.	Conferir a placa e o RNTRC do proprietário no cadastro do veículo/parceiro. A regularização do vínculo é feita junto à ANTT.
Advertência da ANTT na emissão (ex.: "distância percorrida inferior ao calculado")	O CIOT foi emitido, com ressalvas.	Apenas informativo — a mensagem fica registrada no CIOT para consulta posterior.

7. Perguntas frequentes

Pergunta	Resposta
Posso usar a CIOT Online junto com eFrete/Extratta/ANTT?	Sim. Cada filial pode ter mais de uma plataforma configurada — o seletor aparece na geração pelo MDF-e e cada CIOT fica vinculado à plataforma que o gerou.
Existe ambiente de testes/homologação?	Não. A CIOT Online opera somente em produção — emissões de teste consomem créditos reais.
A emissão falhou. Gastei crédito?	Não — o crédito só é debitado quando a emissão tem sucesso. Corrija o que a mensagem indicar e emita novamente.
Cancelei/encerrei pelo painel da CIOT Online. Como atualizar o TryERP?	Na Consulta de CIOT, use Outras Operações → Obter CIOT pelo ID — o estado, o protocolo e a data são sincronizados.
Por que a tela bloqueou a emissão dizendo que o veículo não foi validado na ANTT?	A consulta pública da ANTT não confirmou o vínculo da placa com o RNTRC do proprietário. Verifique o cadastro do veículo/proprietário; a regularização do vínculo é feita junto à ANTT.
O CIOT foi emitido com uma "advertência". Preciso fazer algo?	Não necessariamente — o CIOT está válido. A advertência (ex.: distância menor que a calculada) fica registrada no CIOT; avalie se cabe ajustar o dado nas próximas emissões.
Quantos veículos posso incluir?	Um veículo de tração e suas carretas. Os eixos de todos são somados pela ANTT para o cálculo do piso mínimo.