--- title: 4.5. Adicionar simulação url: https://docs.vehub.com.br/API/VeFlow%20-%20Cart%C3%A3o%20de%20cr%C3%A9dito/4.%20Agenda%20de%20receb%C3%ADveis/v1.1/4.5.%20Adicionar%20simula%C3%A7%C3%A3o/ --- # 4.5. Adicionar simulação ## 🔗 Endpoint | Método | URL | | ----------------------------------------------- | --------------------------------------------------- | | ![POST](https://img.shields.io/badge/POST-blue) | `/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) ```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) ```bash 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 ```bash 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) ```bash 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 ```json { "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) ```json { "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) ```json { "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}`.