Spec de Módulo — CIOT

Sistema: Simplifique (ERP) · Módulo: CIOT · Slug: ciot
Stack real: Frontend Angular (erp-web) + Backend Spring Boot (erp) + MongoDB (documento ciot) + canonical-schema REST
Fonte: Repositório (erp-web e erp)
Disponibilidade: Plano Completo · Perfis: Todos os perfis de usuário (sem restrição de acesso)
Data de geração: 2026-06-02
Última atualização: 2026-06-15 — retificação FRACIONADO: restrições de edição no formulário, validação de prazo e histórico de alterações.

1. Visão Geral

O módulo CIOT (Código Identificador da Operação de Transporte) transforma a obrigação legal do CIOT — exigida para todo transporte rodoviário remunerado de cargas, obrigatória desde 24/05/2026 pela Portaria SUROC nº 6/2026 (com risco de autuação ANTT) — num fluxo automático dentro do ERP.

O módulo resolve quatro dores principais:

1. Obrigação legal com risco de autuação — emissão centralizada e rastreável dentro do ERP.

2. Processo manual/fragmentado e propenso a erro — antes o usuário saía do ERP para o portal externo (IPEF/NDD), redigitava CNPJ do contratante/contratado, RNTRC, placa, origem/destino, valor do frete, NCM, e copiava o número do CIOT de volta ao MDF-e. Agora os dados fluem automaticamente.

3. Ausência de rastreabilidade centralizada de status — o ERP mantém o ciclo de vida (Digitado / Autorizado / Encerrado / Cancelado / Rejeitado / Em Processamento).

4. Desconexão entre CIOT e MDF-e — os dados fluem automaticamente do MDF-e para o CIOT e o vínculo é bidirecional (Ciot.mdfeId ↔ MDFe.rodoviario.ciot.ciots[]).

O CIOT não é um CRUD simples — é um fluxo/processo com máquina de estados, integração externa assíncrona (via provedor de integração abstraído) e regras de negócio ANTT (códigos B1–B122).

Abstração do provedor de integração

Nenhuma mensagem ao usuário cita NDD ou Extratta. O sistema usa sempre o termo "provedor de integração". Internamente existem três providers que implementam a mesma interface CiotIntegracaoProvider:

• NDD Cargo (IPEF) — provider principal (REST + OAuth2): emitir, encerrar, cancelar, alterar, consultar status, roteirizador, comprovante PDF.

• Extratta — provider alternativo (mesma interface).

• Simulado — para dev/testes; executa todo o fluxo localmente sem API externa.

Personas

• Operador logístico / Despachante — preenche MDF-e e CIOT no dia a dia.

• Contratante / Embarcador — empresa que contrata o transporte e responde pela obrigação perante a ANTT.

• ETC (Empresa de Transporte de Cargas) — transportadora contratada.

• TAC (Transportador Autônomo de Cargas) — motorista autônomo, depende do contratante para emitir.

• CTC (Cooperativa de Transporte de Cargas) — regime coletivo.

• Gestor / Financeiro — visibilidade centralizada e gerenciamento de pagamento de frete.

2. Métricas de Sucesso

Métrica mais crítica a curto prazo: % de MDF-e com CIOT vinculado (conformidade com a Portaria SUROC nº 6/2026).

Observações Adicionais

Pontos transversais que orientam o objetivo do módulo e impactam diretamente as métricas acima (cada item indica onde é detalhado no corpo da spec):

1. Três tipos de CIOT com regras distintas — CONVENCIONAL/Lotação (não retificável após emissão; exige cancelar e emitir novo), FRACIONADO (transportador fixo ETC — combo desabilitado; Contratante Principal via radio "Minha empresa"/"Outro"; lista "Demais Contratantes" obrigatória — contratantesFracionado → ContratantesCargaFrac[].cpfCnpj, cada item ≠ CNPJ emissor (B119), sem duplicados e ≠ Contratante Principal; retificação FRACIONADO: apenas valorFrete, ncm e quantidadeCarga são editáveis; veículos, condutores, contratantes e distância bloqueados; prazo limitado à dataFim) e AGREGADO/TAC-Agregado (exige OrigemDestino com distância no encerramento; prazo máx. 30 dias vs. 90 dos demais). [ver Seções 5.1, 6.2 e 7.2]

2. Quatro tipos de transportador com validações cruzadas — TAC (não pode gerPgtoFin=5 Outros, B100), ETC (cpfResponsavel obrigatório), CTC (igual ETC) e EQUIPARADO (identidade no payload usa IE). [ver Seção 7.3]

3. Gerenciamento de pagamento (gerPgtoFin) — apenas PIX e Outros na UI; TED removido desde 24/05/2026; PIX omite os campos bancários do payload. [ver Seção 5.5]

4. Validações ANTT pré-emissão — B30, B69, B100, B115, B119 e B109–B111. [ver Seção 8]

5. Roteirizador de distância (NDD) — botão na aba CIOT do MDF-e + recálculo automático (debounce 1s); eixos derivados do tipo de veículo (cavalo + reboques); preenche distanciaKm. [ver Seção 8]

6. Ciclo de vida com estados assíncronos — EM_PROCESSAMENTO ("Consultar status") e EM_PROCESSAMENTO_CANCELAR ("Consultar cancelamento"); MDF-e associado bloqueado em EM_PROCESSAMENTO_CIOT. [ver Seção 6]

7. Provider SIMULADO para dev/testes — executa o fluxo localmente, sem API externa. [ver Seções 1 e 9]

8. Comprovante PDF — GET /v1/ciots/{id}/comprovante (base64 → application/pdf inline; ação "Baixar comprovante"). [ver Seções 3.2 e 7.4]

9. Abstração do provedor — nenhuma mensagem ao usuário cita NDD/Extratta; usa-se sempre "provedor de integração". [ver Seção 1]

10. Novo layout ANTT/NDD 24/05/2026 — payload plano (era loteOT[]), TED removido, novos obrigatórios (CodigoTipoCarga, eixos por veículo, ContratantesCargaFrac), retencoes movido para o nível valores e correção distanciaPecorrida → distanciaPercorrida. [ver Seção 11]

11. Dados de volume — maiores emissores ~360 MDF-e/mês; cauda longa de dezenas de empresas com 10–100/mês (referência de escala). [ver Seção 11]

3. Escopo de Funcionalidades

3.1 Dentro do escopo

3.2 Fora do escopo (não existe no código)

3.3 O que o CIOT NÃO gera

O CIOT é um documento de operação de transporte e não dispara nenhum dos efeitos abaixo:

• Lançamento financeiro (não gera conta a pagar/receber).

• Documento fiscal (NF-e / CT-e).

• Atualização de estoque.

• Linha contábil.

• Envio direto ao SEFAZ (o SEFAZ é coisa do MDF-e; o CIOT vai à ANTT via provedor de integração).

4. Navegação e Acesso

4.1 Rotas (CIOT standalone)

Caminho: transportes/ciot

Breadcrumb: Transportes › CIOT › {Novo / Editar / Copiar / Visualizar}.
As rotas de formulário (novo/editar/copiar) usam ExitPageGuard (confirmação ao sair com alterações não salvas).

4.2 Acesso dentro do MDF-e

Transportes › MDF-e › formulário › Aba CIOT (última aba do formulário, após "Produto predominante" e "Totalizadores").

• Configura tipo de CIOT, gerarAutomaticamente, dados bancários, distância e vincula CIOTs.

• Emissão automática ocorre no "Salvar e Transmitir" do MDF-e.

• Nota: a partir desta versão o CIOT é uma aba própria no final do MDF-e — não fica mais como uma seção dentro da aba "Rodoviário".

4.3 Configuração (pré-requisito)

• Configurações › Transportes › MDF-e › Dados Gerais — define o provedorCiot. (Atualização 09/06/2026: os campos bancários — agência/conta/dígito — foram removidos desta tela; os dados bancários do contratante passaram a ser preenchidos automaticamente pelo backend ao cadastrar o contratante no provedor.)

• Cadastro da Empresa (pré-requisito do provedor de integração) — para emitir/configurar o CIOT com o provedor de integração, o cadastro da empresa deve ter: (1) CPF do responsável preenchido (aba "Dados dos responsáveis") — usado como documentNumber do usuário no cadastro do contratante; (2) um e-mail com o processo MDF-e marcado (aba "Contato") — usado como contato. Ao salvar a Configuração de MDF-e com o provedor ativo, o sistema verifica em tempo real se a empresa já possui esses dados. Se estiverem completos, o salvamento é silencioso (apenas toast de sucesso). Se faltar algum dado, um modal de aviso é exibido orientando o preenchimento — o salvamento ocorre normalmente em ambos os casos. (Atualização 17/06/2026: verificação condicional via getSelfNoImage(); o modal só aparece quando os dados estão de fato ausentes.)

• Cadastros › Clientes/Fornecedores — campo cpfResponsavel (obrigatório para PJ contratada) e rntrc.

4.4 Perfis e restrições

• Perfis de acesso: todos os perfis de usuário.

• Restrições de acesso: nenhuma.

5. Modelo de Dados

Entidade MongoDB: Ciot (@Document("ciot")) — estende AbstractAuditablePersistable<String>, multi-tenant por contmaticId, com auditoria (createdBy / ipCreatedBy / dataCriacao / updatedBy / dataAtualizacao) e delete lógico (DeleteLogicEntity).
Resource REST: CiotResource.

5.1 Campos principais (CIOT)