4.5. Adicionar simulação¶

🔗 Endpoint¶

Método	URL
	`/api/v1.1/cartao/agenda/{identificador}/simulacoes`

🧾 Descrição¶

Cria (efetiva) uma nova simulação no contexto de uma agenda já obtida. Diferente do endpoint de apenas calcular/validar, este recurso persiste a simulação no sistema (adicionando-a à lista de simulações atreladas à agenda) e reserva os títulos/URs selecionados no carrinho associado à simulação.

A simulação pode ser criada a partir de URs selecionadas, por split automático a partir de um valor desejado ou por troca/substituição de valor desejado. Parâmetros de performance podem ser personalizados quando aplicável.

📤 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,
  "somenteUrPerformada": true,
  "idTitulos": []
}

🧾 Detalhamento dos Campos¶

Campo	Tipo	Obrigatório	Descrição
acao	integer	Sim	Tipo de criação da simulação: `1` = URs selecionadas `2` = SPLIT valor desejado `3` = Troca 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`. Também obrigatório quando `acao` = `3` e `somenteUrPerformada` = false. Formato `YYYY-MM-DD`.
dataFinal	string	Condicional	Obrigatório quando `acao` = `2`. Também obrigatório quando `acao` = `3` e `somenteUrPerformada` = false. Formato `YYYY-MM-DD`.
ordem	string	Condicional	Obrigatório quando `acao` = `3`. Valores: `ASC` ou `DESC`. Define a ordenação para seleção das URs performadas.
personalizaPerformance	boolean	Condicional	Obrigatório quando `acao` = `2`. Ignorado quando `acao` for `1` ou `3`. Quando `true`, ativa os campos `tipoPerformance` e `valorUR`.
tipoPerformance	integer	Condicional	Obrigatório quando `personalizaPerformance` = `true`. `1` = Valor fixo por UR; `2` = Percentual por UR (0–100).
valorUR	number	Condicional	Obrigatório quando `personalizaPerformance` = `true`. Valor ≥ 0. Interpretação conforme `tipoPerformance`.
somenteUrPerformada	boolean	Não	Indica que a operação de troca (acao = `3`) deve atuar apenas sobre URs que já estão performadas; quando `false`, a troca considera pool de URs por período (`dataInicial`/`dataFinal`).
idTitulos	string[]	Condicional	Obrigatório quando `acao` = `1`. IDs (GUID) dos títulos/URs a serem reservados na simulação.

Regras gerais de validação

Datas no formato YYYY-MM-DD.
valorDesejado e valorUR devem ser >= 0; valorUR's percentual (quando tipoPerformance = 2) deve estar entre 0 e 100.
ordem aceita apenas ASC ou DESC (case-insensitive).
idTitulos quando informado deve conter IDs válidos presentes na agenda e com valorLivre suficiente.
Qualquer violação das regras retorna HTTP 400 com listagem de erros.

🧪 Exemplo de cURL¶

▶ Criar simulação a partir de URs selecionadas (ação = 1)¶

curl -X POST https://api.veflow.com/api/v1.1/cartao/agenda/534D8AAE-61E4-4264-9D15-715B9E1F1D51/simulacoes \
  -H "Authorization: Bearer {seu_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "acao": 1,
    "idTitulos": ["D7438CFA-9C4B-4117-A13F-C1EDD2B987D7", "154EAC0D-5A76-4997-B7FB-A5FBA916C895"]
  }'

▶ Criar simulação por split de valor desejado (ação = 2) com performance personalizada¶

curl -X POST https://api.veflow.com/api/v1.1/cartao/agenda/534D8AAE-61E4-4264-9D15-715B9E1F1D51/simulacoes \
  -H "Authorization: Bearer {seu_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "acao": 2,
    "valorDesejado": 25000.00,
    "dataInicial": "2025-09-01",
    "dataFinal": "2025-09-30",
    "personalizaPerformance": true,
    "tipoPerformance": 2,
    "valorUR": 5.5
  }'

▶ Criar simulação por troca de valor desejado (ação = 3) atuando sobre pool (somenteUrPerformada = false)¶

curl -X POST https://api.veflow.com/api/v1.1/cartao/agenda/534D8AAE-61E4-4264-9D15-715B9E1F1D51/simulacoes \
  -H "Authorization: Bearer {seu_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "acao": 3,
    "valorDesejado": 15000.00,
    "dataInicial": "2025-09-01",
    "dataFinal": "2025-09-15",
    "ordem": "DESC",
    "somenteUrPerformada": false
  }'

📥 Responses¶

✅ 201 Created¶

{
  "idSimulacao": "7C2C4D03-80BB-43E9-885C-F6A1C2660A68",
  "identificadorAgenda": "534D8AAE-61E4-4264-9D15-715B9E1F1D51",
  "mensagem": "Simulação criada com sucesso e adicionada à agenda."
}

Indica que a simulação foi validada, persistida e os títulos/recursos foram reservados no carrinho da simulação.

❌ 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 for {2,3}.",
    "Campo 'idTitulos' é obrigatório quando acao = 1.",
    "Campo 'tipoPerformance' é obrigatório quando personalizaPerformance = true."
  ]
}

❌ 409 Conflict (exemplo — recursos já reservados)¶

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Conflito",
  "status": 409,
  "erros": [
    "Algumas URs informadas já estão reservadas em outra simulação. IDs em conflito: ['34BBF492-69CD-4C77-938F-1FBA792CD6ED']."
  ]
}

🕒 Observações¶

A criação da simulação persiste o carrinho e reserva as URs selecionadas — passo necessário antes da geração do contrato.
Reservas são temporárias e têm expiração; se a simulação não for convertida em contrato, os títulos retornam a valorLivre após 1h da criação da agenda.
Autenticação obrigatória via Authorization: Bearer {token}.