--- title: 4.9. Prévia do item 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.9.%20Pr%C3%A9via%20do%20item/ --- # 4.9. Prévia do item ## 🔗 Endpoint | Método | URL | | ----------------------------------------------- | -------------------------------------------------------------------- | | ![POST](https://img.shields.io/badge/POST-blue) | `/public/api/v1.1/cartao/agendas/{idAgenda}/carrinho/itens/previa` | --- ## 🧾 Descrição Calcula e valida um **item de carrinho** sobre uma agenda já consultada, **sem persistir nada**. É o passo de conferência: você envia exatamente o mesmo corpo que enviaria em [4.10. Adicionar item](4.10.%20Adicionar%20item.md) e a plataforma **VeFlow** devolve quais URs seriam usadas, o valor atingido, o prazo médio e os alertas de composição. Como a prévia não escreve nada, ela pode ser chamada quantas vezes for necessário: não cria item, não altera a agenda e não muda o `valorDisponivel` de nenhuma UR. O corpo cobre as duas naturezas de contrato — `tipoContrato` = `1` (Troca de titularidade) e `tipoContrato` = `2` (Garantia) — e as quatro estratégias de seleção de URs. > ⚠️ **Fumaça não é um tipo de contrato.** É uma configuração da garantia (prazo estendido, uso somente de URs performadas e regra de retenção), enviada no objeto `fumaca` com `tipoContrato` = `2`. --- ## 📤 Requisição ### 📋 Payload (JSON) ```json { "tipoContrato": 1, "estrategia": 1, "contratoErp": "", "contratoValor": 0.00, "taxa": 0.0000, "idContaCorrente": "", "tags": [""], "selecao": { "idsUrs": [""], "valorDesejado": 0.00, "dataInicial": "0000-00-00", "dataFinal": "0000-00-00", "ordem": "ASC", "somenteUrPerformada": false }, "performance": { "personalizar": false, "tipo": 1, "valorUr": 0.00 }, "parcela": { "numero": 1, "total": 1, "valor": 0.00, "data": "0000-00-00" }, "fumaca": { "prazoEstendidoDias": 0, "tipoValor": 1, "valor": 0.00, "incluirArranjosDebito": false } } ``` ### 🧾 Detalhamento dos Campos | Campo | Tipo | Obrigatório | Descrição | | --------------- | -------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | tipoContrato | integer | Sim | Natureza do contrato que o item vai compor:
`1` = Troca de titularidade
`2` = Garantia | | estrategia | integer | Sim | Como as URs do item são escolhidas:
`1` = URs selecionadas
`2` = Split por valor desejado
`3` = Troca por valor desejado
`4` = Alocação automática por parcela | | contratoErp | string | Não | Identificador do contrato no ERP do cliente. Em garantia parcelada, é o campo que agrupa os itens de um mesmo contrato. | | contratoValor | number | Não | Valor total do contrato no ERP. Em garantia, é o valor que o contrato pretende garantir. | | taxa | number | Condicional | Deságio do item, com até 4 casas decimais. **Só se aplica a `tipoContrato` = `1`** — garantia não tem deságio. Quando omitido em uma troca de titularidade, vale a taxa vigente da operação. | | idContaCorrente | string | Não | Identificador da conta corrente que receberá a liquidação do contrato. Quando omitido, é usada a conta padrão configurada na operação. | | tags | string[] | Não | Lista de tags para rastreabilidade do item (p.ex. `["PA_01"]`). | | **selecao** | object | Condicional | Critérios de seleção das URs. Obrigatório quando `estrategia` for `1`, `2` ou `3`; opcional quando `estrategia` = `4`. | | → idsUrs | string[] | Condicional | **Obrigatório quando `estrategia` = `1`.** IDs (GUID) das URs da agenda que compõem o item. Devem existir na agenda e ter `valorDisponivel` suficiente. | | → valorDesejado | number | Condicional | **Obrigatório quando `estrategia` for `2` ou `3`.** Valor numérico ≥ 0 que a seleção deve tentar atingir. | | → dataInicial | string | Condicional | Obrigatório quando `estrategia` = `2`, ou quando `estrategia` = `3` **e** `somenteUrPerformada` = `false`. Formato `YYYY-MM-DD`. | | → dataFinal | string | Condicional | Obrigatório quando `estrategia` = `2`, ou quando `estrategia` = `3` **e** `somenteUrPerformada` = `false`. Formato `YYYY-MM-DD`. Deve ser maior ou igual a `dataInicial`. | | → ordem | string | Condicional | **Obrigatório quando `estrategia` = `3`.** Valores aceitos: `ASC` ou `DESC` (case-insensitive). Define a ordem em que as URs são varridas para compor o valor desejado. | | → somenteUrPerformada | boolean | Não | Quando `true`, considera apenas URs já performadas. Quando `false` (padrão), considera o pool de URs do período informado em `dataInicial`/`dataFinal`. | | **performance** | object | Não | Personaliza quanto de cada UR é considerado na composição. Quando omitido, vale a performance integral da UR. | | → personalizar | boolean | Não | Padrão `false`. Quando `true`, ativa `tipo` e `valorUr`. | | → tipo | integer | Condicional | **Obrigatório quando `performance.personalizar` = `true`.**
`1` = Valor fixo por UR
`2` = Percentual por UR (0 a 100) | | → valorUr | number | Condicional | **Obrigatório quando `performance.personalizar` = `true`.** Valor ≥ 0. Quando `tipo` = `2`, deve estar entre 0 e 100. | | **parcela** | object | Condicional | **Obrigatório em garantia parcelada.** Identifica qual parcela do contrato este item garante. | | → numero | integer | Condicional | Número da parcela (inteiro ≥ 1). Deve ser único dentro do mesmo `contratoErp`. | | → total | integer | Condicional | Quantidade total de parcelas do contrato (inteiro ≥ 1). | | → valor | number | Condicional | Valor da parcela (numérico > 0). | | → data | string | Condicional | Data de vencimento da parcela, no formato `YYYY-MM-DD`. | | **fumaca** | object | Condicional | **Obrigatório em garantia fumaça.** Configuração da garantia: prazo estendido, uso somente de URs performadas e regra de retenção. | | → prazoEstendidoDias | integer | Condicional | Dias de prazo estendido somados à janela de busca de URs da garantia. | | → tipoValor | integer | Condicional | Regra de retenção:
`1` = Valor fixo
`2` = Percentual | | → valor | number | Condicional | Valor retido por UR, interpretado conforme `tipoValor`. Quando `tipoValor` = `2`, deve estar entre 0 e 100. | | → incluirArranjosDebito | boolean | Não | Padrão `false`. Quando `true`, inclui arranjos de débito na composição da garantia. | **Regras e formatos** * Datas no formato `YYYY-MM-DD`. * `selecao.valorDesejado` e `performance.valorUr` devem ser ≥ 0; percentuais (`performance.tipo` = `2` e `fumaca.tipoValor` = `2`) devem estar entre 0 e 100. * `selecao.ordem` aceita apenas `ASC` ou `DESC`, em qualquer caixa. * `selecao.idsUrs` deve conter IDs de URs presentes na agenda e com `valorDisponivel` suficiente para o item. * `taxa` não se aplica a `tipoContrato` = `2`: contrato de garantia não tem deságio e por isso a prévia de garantia não devolve valor nominal, desconto nem aquisição. * O objeto `fumaca` implica seleção apenas de URs performadas. * As datas informadas em `selecao` devem estar contidas no período consultado na agenda — ver [4.1. Solicitar agenda](4.1.%20Solicitar%20agenda.md). * Qualquer violação das regras acima resulta em **HTTP 400** com a lista de erros. --- ## 🧪 Exemplo de cURL #### ▶ Prévia de troca de titularidade com URs selecionadas (`estrategia` = 1) ```bash curl -X POST https://api.veflow.com/public/api/v1.1/cartao/agendas/534D8AAE-61E4-4264-9D15-715B9E1F1D51/carrinho/itens/previa \ -H "Authorization: Bearer {seu_token}" \ -H "GrupoEconomico: {seu_grupo_economico}" \ -H "Content-Type: application/json" \ -d '{ "tipoContrato": 1, "estrategia": 1, "contratoErp": "CTR-2025-0001", "taxa": 1.9900, "idContaCorrente": "B21F0B0E-6F5B-4C6A-9D34-2A1D0E4E77C1", "tags": ["PA_01"], "selecao": { "idsUrs": [ "D7438CFA-9C4B-4117-A13F-C1EDD2B987D7", "154EAC0D-5A76-4997-B7FB-A5FBA916C895" ] } }' ``` #### ▶ Prévia por split de valor desejado (`estrategia` = 2) com performance personalizada ```bash curl -X POST https://api.veflow.com/public/api/v1.1/cartao/agendas/534D8AAE-61E4-4264-9D15-715B9E1F1D51/carrinho/itens/previa \ -H "Authorization: Bearer {seu_token}" \ -H "GrupoEconomico: {seu_grupo_economico}" \ -H "Content-Type: application/json" \ -d '{ "tipoContrato": 1, "estrategia": 2, "taxa": 1.9900, "selecao": { "valorDesejado": 25000.00, "dataInicial": "2025-09-01", "dataFinal": "2025-09-30" }, "performance": { "personalizar": true, "tipo": 2, "valorUr": 5.5 } }' ``` #### ▶ Prévia de garantia parcelada com fumaça (`tipoContrato` = 2) ```bash curl -X POST https://api.veflow.com/public/api/v1.1/cartao/agendas/534D8AAE-61E4-4264-9D15-715B9E1F1D51/carrinho/itens/previa \ -H "Authorization: Bearer {seu_token}" \ -H "GrupoEconomico: {seu_grupo_economico}" \ -H "Content-Type: application/json" \ -d '{ "tipoContrato": 2, "estrategia": 3, "contratoErp": "CTR-2025-0007", "contratoValor": 10000.00, "selecao": { "valorDesejado": 5000.00, "ordem": "ASC", "somenteUrPerformada": true }, "parcela": { "numero": 1, "total": 2, "valor": 5000.00, "data": "2025-09-30" }, "fumaca": { "prazoEstendidoDias": 30, "tipoValor": 2, "valor": 10.00, "incluirArranjosDebito": false } }' ``` --- ## 📥 Responses ### ✅ 200 OK — `tipoContrato` = `1` (Troca de titularidade) ```json { "previa": { "quantidadeUrs": 2, "valorAtingido": 24800.00, "valorNaoAtingido": 200.00, "prazoMedio": 37, "alertaPerformance": 1, "alertaResilicao": false, "urs": [ { "idUr": "D7438CFA-9C4B-4117-A13F-C1EDD2B987D7", "arranjo": "MCC", "credenciadora": "10293847560102", "dataPrevistaLiquidacao": "2025-09-12", "valorLivre": 15000.00, "valorDisponivel": 15000.00, "valorNominal": 15000.00, "valorDesconto": 298.50, "valorAquisicao": 14701.50 }, { "idUr": "154EAC0D-5A76-4997-B7FB-A5FBA916C895", "arranjo": "VCC", "credenciadora": "10293847560102", "dataPrevistaLiquidacao": "2025-09-26", "valorLivre": 9800.00, "valorDisponivel": 9800.00, "valorNominal": 9800.00, "valorDesconto": 195.02, "valorAquisicao": 9604.98 } ] }, "mensagem": "Prévia calculada com sucesso!" } ``` ### ✅ 200 OK — `tipoContrato` = `2` (Garantia) ```json { "previa": { "quantidadeUrs": 2, "valorAtingido": 5000.00, "valorNaoAtingido": 0.00, "prazoMedio": 21, "alertaPerformance": 0, "alertaResilicao": false, "urs": [ { "idUr": "89A70B38-2DC5-4F74-8B10-12DBCE4D3248", "arranjo": "MCC", "credenciadora": "10293847560102", "dataPrevistaLiquidacao": "2025-09-18", "valorLivre": 4200.00, "valorDisponivel": 4200.00, "valorGarantido": 3500.00 }, { "idUr": "34BBF492-69CD-4C77-938F-1FBA792CD6ED", "arranjo": "VCC", "credenciadora": "10293847560102", "dataPrevistaLiquidacao": "2025-09-24", "valorLivre": 1800.00, "valorDisponivel": 1800.00, "valorGarantido": 1500.00 } ] }, "mensagem": "Prévia calculada com sucesso!" } ``` Repare que a prévia de garantia **não traz** `valorNominal`, `valorDesconto`, `valorAquisicao` nem `taxa`: não houve cessão ao fundo e, portanto, não existe deságio. #### Campos de `previa` | Campo | Tipo | Descrição | | ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------- | | quantidadeUrs | number | Quantidade de URs que o item usaria. | | valorAtingido | number | Valor que a estratégia conseguiu compor com as URs encontradas. | | valorNaoAtingido | number | Diferença entre `selecao.valorDesejado` e `valorAtingido`. Vem `0.00` quando o valor desejado foi atendido por completo. | | prazoMedio | number | Prazo médio, em dias, das URs da composição, ponderado pelo valor. | | alertaPerformance | number | Quantidade de URs da composição que ultrapassam a tolerância de performance configurada na operação. | | alertaResilicao | boolean | `true` quando a composição apresenta inconsistência que pode levar à resilição do contrato. | | urs | array | URs que comporiam o item, com os valores calculados para cada uma. | #### Campos de `previa.urs` | Campo | Tipo | Descrição | | ---------------------- | ------ | -------------------------------------------------------------------------------------------- | | idUr | string | GUID da UR na agenda. | | arranjo | string | Sigla do arranjo de pagamento (ex.: `"MCC"`, `"VCC"`). | | credenciadora | string | CNPJ da credenciadora da UR (somente dígitos). | | dataPrevistaLiquidacao | string | Data prevista de liquidação da UR. | | valorLivre | number | Valor da UR sem ônus registrado. | | valorDisponivel | number | Valor da UR ainda alocável, já descontado o que outros itens deste carrinho consumiram. | | valorGarantido | number | Valor que esta UR garantiria no item. Presente somente quando `tipoContrato` = `2`. | | valorNominal | number | Valor da UR que seria cedido. Presente somente quando `tipoContrato` = `1`. | | valorDesconto | number | Deságio calculado sobre o valor nominal com a `taxa` do item. Presente somente quando `tipoContrato` = `1`. | | valorAquisicao | number | Valor de aquisição (`valorNominal` − `valorDesconto`). Presente somente quando `tipoContrato` = `1`. | --- ### ❌ 400 Bad Request ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1", "titulo": "Atenção", "status": 400, "erros": [ "Campo 'estrategia' é obrigatório e deve estar entre 1 e 4.", "Campo 'selecao.idsUrs' é obrigatório quando estrategia = 1.", "Campo 'selecao.valorDesejado' é obrigatório quando estrategia for 2 ou 3.", "Campo 'performance.tipo' é obrigatório quando performance.personalizar = true.", "Campo 'taxa' não se aplica a tipoContrato = 2." ] } ``` --- ### ❌ 404 Not Found ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.5", "titulo": "Não encontrado", "status": 404, "erros": [ "Agenda '534D8AAE-61E4-4264-9D15-715B9E1F1D51' não encontrada." ] } ``` Também é o retorno quando algum `idsUrs` informado não pertence à agenda. --- ## 🔄 Mudanças nesta versão * A rota `simula-contrato` passou a ser `carrinho/itens/previa`. O endpoint antigo **não criava simulação alguma** — era cálculo e validação. O nome prometia persistência que nunca existiu. * O campo `acao` passou a se chamar `estrategia`. A troca não é só de nome: os valores `1` e `2` tinham significado invertido em relação ao `tipoVinculo` da v1, o que quebrava silenciosamente quem migrava. * `tipoContrato` passou a existir no item. Antes, a natureza do contrato (troca de titularidade ou garantia) não era declarada na montagem. * `idTitulos` virou `selecao.idsUrs`. O recurso se chama **UR**, não título. * Os campos `personalizaPerformance`, `tipoPerformance` e `valorUR` foram agrupados no objeto `performance`; os parâmetros de fumaça, no objeto `fumaca`. * `contratoErp`, `contratoValor`, `taxa` e `idContaCorrente` passaram a ter **entrada documentada**. Antes apareciam somente no retorno da lista, sem que houvesse onde informá-los. --- ## 🕒 Observações * Este endpoint **não persiste nada**: é cálculo e validação. Nenhum item é criado, a agenda não é alterada e o `valorDisponivel` das URs não muda. * Por não escrever, a prévia **não exige** o header `Idempotency-Key`. Ele é obrigatório apenas nas chamadas de escrita, como [4.10. Adicionar item](4.10.%20Adicionar%20item.md). * O corpo aceito aqui é **idêntico** ao de [4.10. Adicionar item](4.10.%20Adicionar%20item.md). O fluxo esperado é: calcular a prévia, conferir o resultado e repetir o mesmo corpo no `POST` de criação. * A prévia depende de uma agenda concluída — ver [4.1. Solicitar agenda](4.1.%20Solicitar%20agenda.md) e [4.3. Detalhes da agenda](4.3.%20Detalhes%20da%20agenda.md). As URs elegíveis são as devolvidas em [4.4. Listar URs da agenda](4.4.%20Listar%20URs%20da%20agenda.md). * A agenda tem prazo de validade. Depois de vencida, a prévia deixa de refletir a realidade e é necessário refazer a consulta — ver [4.7. Refazer consulta](4.7.%20Refazer%20consulta.md). * Todos os cálculos seguem o contexto vigente da operação: taxas, tolerância de performance, parâmetros e limites configurados. * Headers obrigatórios e convenções gerais estão descritos em **1.2. Convenções da API**.