Simulador de frete

Conceito

O simulador trabalha em três camadas: Metodologia (fórmula reutilizável) → Simulação (instância com inputs + resultado) → Frete (publicação no marketplace com referência à simulação de origem).

Fluxo

1. Cadastre metodologias em /simulador/metodologias (ou use as 3 globais já incluídas).
2. Em /simulador/novo, escolha a metodologia, preencha os inputs e salve.
3. Compare metodologias lado-a-lado em /simulador/comparar.
4. Publique no marketplace via botão "Publicar com esta" — o frete fica vinculado à simulação.

Auditoria

Cada metodologia é versionada automaticamente: alterações em nome, descrição ou definição geram nova entrada em pricing_methodology_versions (snapshot imutável). Cada simulação registra a versão usada, e o frete publicado guarda o simulation_id, fechando o ciclo.

Impostos

O simulador suporta um módulo opcional de tributos por metodologia. São considerados: ICMS (matriz interestadual UF→UF, com crédito configurável), PIS/COFINS (por regime: Simples / Lucro Presumido / Lucro Real), ISS, INSS+RAT sobre TAC autônomo e os tributos da Reforma Tributária (CBS e IBS, vigência a partir de 2026).

Cada metodologia escolhe um modo:

• by_outside — acréscimo: total = subtotal × (1 + Σ alíquotas).
• by_inside — gross-up: total = subtotal / (1 − Σ alíquotas).
• informative — apenas detalha, sem alterar o total.

As alíquotas vêm de uma matriz global (em /admin/taxes) com possibilidade de override por empresa. A empresa define seu regime e UF em /settings ou já no onboarding. Detalhes completos em Impostos.

API pública

Calcula uma simulação via API. Use o mesmo esquema de autenticação dos demais endpoints (HMAC + API key).

{
  "methodology_id": "uuid",
  "inputs": { "distance_km": 350, "weight_kg": 12000 },
  "save": true,
  "notes": "Cotação cliente X"
}

Resposta:

{
  "total": 4250.00,
  "breakdown": [
    { "key": "frete_peso", "label": "Frete por peso", "value": 3600 },
    { "key": "pedagio",    "label": "Pedágio",         "value": 250 },
    { "key": "margem",     "label": "Margem",          "value": 400 }
  ],
  "methodology_version": 3,
  "simulation_id": "uuid-or-null"
}

Integração com regras de negócio

O trigger when_simulation_completed está disponível e é avaliado a cada simulação. Use-o para bloquear margens fora do alvo, exigir aprovação acima de um teto ou auto-preencher observações. Configure regras em /rules e acompanhe pendências em /rules/approvals.

Facts expostas pelo resolver:

• simulation.total — valor total calculado.
• simulation.price_per_km — total dividido pela distância (quando informada).
• simulation.margin_pct — margem percentual quando cost/custo e revenue/receita estão nos inputs.
• simulation.methodology_id — UUID da metodologia usada.
• freight.cargo_type, freight.weight_kg, freight.distance_km, freight.price, freight.price_per_km, freight.origin_state, freight.destination_state, freight.vehicle_type — preenchidas quando a simulação está vinculada a um frete existente.