4.4. Simular Contratos¶

🔗 Endpoint¶

Método	URL
	`/api/v1.1/cartao/agenda/{identificador}/simula-contrato`

🧾 Descrição¶

Realiza a simulação de contratos com base nas agendas já obtidas pela solicitação anterior. Permite definir se a simulação será feita com URs selecionadas, por valor desejado (split automático) ou substituição de valor desejado. A simulação considera parâmetros de performance e composição personalizada conforme as regras definidas abaixo.

📤 Requisição¶

📋 Payload (JSON)¶

{
  "acao": 1,
  "valorDesejado": 0.00,
  "dataInicial": "2025-09-09",
  "dataFinal": "2025-09-09",
  "ordem": "ASC|DESC",
  "personalizaPerformance": true,
  "tipoPerformance": 1,
  "valorUR": 0.00,
  "idTitulos": []
}

🧾 Detalhamento dos Campos¶

Campo	Tipo	Obrigatório	Descrição
acao	integer	Sim	Define o tipo de simulação. Valores possíveis: `1` = URs selecionadas `2` = SPLIT valor desejado `3` = Troca de titularidade por valor desejado
valorDesejado	number	Condicional	Obrigatório quando `acao` for `2` ou `3`. Valor numérico ≥ 0.
dataInicial	string	Condicional	Obrigatório quando `acao` = `2` ou (`acao` = `3` e `somenteUrPerformada` = `false`).
dataFinal	string	Condicional	Obrigatório quando `acao` = `2` ou (`acao` = `3` e `somenteUrPerformada` = `false`).
ordem	string	Condicional	Obrigatório quando `acao` = `3`. Valores permitidos: `ASC` ou `DESC`. Define a ordem de seleção das URs performadas.
personalizaPerformance	boolean	Condicional	Obrigatório quando `acao` = `2`. Quando `acao` for `1` ou `3`, poderá ser omitido com `false` ou `null`.
tipoPerformance	integer	Condicional	Obrigatório quando `personalizaPerformance` = `true`. Valores possíveis: `1` = Valor fixo por UR `2` = Percentual por UR (0–100).
valorUR	number	Condicional	Obrigatório quando `personalizaPerformance` = `true`. Valor ≥ 0.
idTitulos	string[]	Condicional	Obrigatório quando `acao` = `1`. IDs dos títulos (URs) selecionados para simulação.

Regras e Observações:

dataInicial e dataFinal devem estar no formato YYYY-MM-DD.
Qualquer violação das regras acima resultará em HTTP 400 com mensagem de erro descritiva.

🧪 Exemplo de cURL¶

curl -X POST https://api.veflow.com/api/v1.1/cartao/agenda/534D8AAE-61E4-4264-9D15-715B9E1F1D51/simula-contrato \
  -H "Authorization: Bearer {seu_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "acao": 1,
    "idTitulos": ["89A70B38-2DC5-4F74-8B10-12DBCE4D3248"]
  }'

📥 Responses¶

✅ 200 OK — Quando `acao` = `1`¶

{
  "detalhesSimulacao": {
    "quantidadeUR": 1,
    "valorAtingido": 1.00,
    "prazoMedio": 50,
    "empresa": ""
  }
}

✅ 200 OK — Quando `acao` for `2` ou `3`¶

{
  "detalhesSimulacao": {
    "quantidadeUR": 1,
    "valorAtingido": 1.00,
    "valorNaoAtingido": 0.00,
    "alertaPerformance": 1,
    "alertaResilicao": false
  }
}

❌ 400 Bad Request (exemplo)¶

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "Campo 'valorDesejado' é obrigatório quando acao ∈ {2,3}.",
    "Campo 'idTitulos' é obrigatório quando acao = 1.",
    "Campo 'tipoPerformance' é obrigatório quando personalizaPerformance = true."
  ]
}

🕒 Observações¶

Este endpoint depende de uma agenda previamente solicitada e identificada por {identificador}.
A simulação não persiste dados — é apenas para cálculo e validação dos parâmetros do contrato.
O campo alertaPerformance indica URs que ultrapassam a tolerância de performance definida.
O campo alertaResilicao indica possíveis inconsistências de composição.
Todos os cálculos seguem o contexto vigente da operação (taxas, parâmetros e limites configurados).