API — Simulações

POST /simulations

Executa uma simulação de preço com base em uma metodologia da sua empresa. Opcionalmente, persiste o resultado em freight_simulations para reuso e auditoria.

Corpo

• methodology_id (string, obrigatório) — UUID da metodologia.
• inputs (object, obrigatório) — pares chave/valor conforme os inputs da metodologia.
• save (boolean, opcional) — se true, persiste a simulação.
• notes (string, opcional) — anotação livre quando save=true.
• tax_context (object, opcional) — contexto para cálculo de impostos: { origin_state, destination_state, tac_autonomo }. Quando ausente, são usados os defaults da empresa (UF e regime configurados). Veja Impostos.

Exemplo (curl)

curl -X POST https://freteflow.fr.com.br/api/public/v1/simulations \
  -H "X-API-Key: ff_live_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "methodology_id": "9f1c...e2",
    "inputs": { "distance_km": 420, "weight_kg": 12000 },
    "tax_context": { "origin_state": "SP", "destination_state": "RJ", "tac_autonomo": false },
    "save": true,
    "notes": "Cotação cliente ACME"
  }'

Resposta

{
  "id": "a3e5...c1",            // presente apenas se save=true
  "methodology_id": "9f1c...e2",
  "methodology_version": 4,
  "subtotal": 3187.5,
  "total": 3863.34,
  "currency": "BRL",
  "breakdown": [
    { "key": "base", "label": "Base", "value": 1500 },
    { "key": "km", "label": "Distância", "value": 1260 },
    { "key": "peso", "label": "Peso", "value": 427.5 }
  ],
  "tax_breakdown": [
    { "kind": "icms",   "rate": 0.12,   "value": 382.50, "mode": "by_outside" },
    { "kind": "pis",    "rate": 0.0165, "value":  52.59, "mode": "by_outside" },
    { "kind": "cofins", "rate": 0.076,  "value": 242.25, "mode": "by_outside" }
  ],
  "effective_tax_rate": 0.2120
}

Erros comuns

• 401 — API key ausente ou inválida.
• 403 — metodologia não pertence à empresa da chave.
• 422 — inputs não casa com a definição da metodologia.
• 429 — rate limit excedido (consulte Rate limits).

Webhooks de simulação

Toda simulação salva emite eventos no event_outbox, despachados para os webhooks configurados em /integrations.

• simulation.created — emitido ao salvar uma simulação. Payload inclui id, methodology_id, methodology_version, total, currency, status, inputs, freight_id, created_by.
• simulation.converted — emitido quando a simulação é vinculada a um frete (campo simulation_id em freights). Payload: id, methodology_id, total, currency, freight_id.

Requer a feature integrations.webhooks habilitada no plano da empresa.