4.9. Prévia do item¶

🔗 Endpoint¶

Método	URL
	`/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 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)¶

{
  "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.
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)¶

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¶

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)¶

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)¶

{
  "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)¶

{
  "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¶

{
  "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¶

{
  "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.
O corpo aceito aqui é idêntico ao de 4.10. Adicionar item. 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 e 4.3. Detalhes da agenda. As URs elegíveis são as devolvidas em 4.4. Listar URs da agenda.
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.
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.