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 Acesse ciotonline.com.br/login com a conta da empresa; No menu lateral, abra Desenvolvedor → Tokens; Clique em Gerar token e informe um nome identificador (ex.: "TryERP Produção"); 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) Validações locais: campos obrigatórios, peso dentro da faixa, CPF/CNPJ do titular da conta; 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; Confirmação: aviso de que a emissão consome 1 crédito; 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.