4.10. Adicionar item¶

🔗 Endpoint¶

Método	URL
	`/public/api/v1.1/cartao/agendas/{idAgenda}/carrinho/itens`

🧾 Descrição¶

Cria um item no carrinho da agenda. O item é a unidade de montagem do contrato: ele declara a natureza (tipoContrato), a estratégia de seleção das URs (estrategia) e os parâmetros comerciais do contrato que será gerado depois em 5.1. Criar contratos.

O corpo é exatamente o mesmo de 4.9. Prévia do item. O fluxo recomendado é calcular a prévia, conferir a composição e repetir o mesmo corpo aqui.

Um carrinho pode ter vários itens. Cada item consome parte do valorDisponivel das URs que usa, de modo que a soma alocada da mesma UR entre os itens do carrinho nunca ultrapasse o valor que ela tem disponível.

⚠️ Não existe reserva de UR. Adicionar um item ao carrinho não garante exclusividade sobre as URs escolhidas. Não há trava que reserve a UR para o financiador antes do registro do contrato na registradora — até esse momento, outro financiador pode contratar a mesma UR. O valorDisponivel controla apenas a consistência dentro deste carrinho.

⚠️ 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. É esta taxa que vale para o contrato, não a informada na solicitação da agenda.
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 o item de garantia não devolve valor nominal, desconto nem aquisição.
O objeto fumaca implica seleção apenas de URs performadas.
A soma alocada da mesma UR entre os itens do carrinho não pode exceder o valorDisponivel dela — do contrário, a criação é recusada com 409 Conflict.
Qualquer violação das regras acima resulta em HTTP 400 com a lista de erros.

🧪 Exemplo de cURL¶

▶ Item 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 \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -H "Idempotency-Key: 1c9a44d2-3b7e-4a58-9f01-6d2c8e5b3a11" \
  -H "Content-Type: application/json" \
  -d '{
    "tipoContrato": 1,
    "estrategia": 1,
    "contratoErp": "CTR-2025-0001",
    "contratoValor": 25000.00,
    "taxa": 1.9900,
    "idContaCorrente": "B21F0B0E-6F5B-4C6A-9D34-2A1D0E4E77C1",
    "tags": ["PA_01"],
    "selecao": {
      "idsUrs": [
        "D7438CFA-9C4B-4117-A13F-C1EDD2B987D7",
        "154EAC0D-5A76-4997-B7FB-A5FBA916C895"
      ]
    }
  }'

▶ Item 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 \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -H "Idempotency-Key: 7d61f0aa-92c4-4f0b-8a3e-b0f5c1d24e88" \
  -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
    }
  }'

▶ Item 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 \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -H "Idempotency-Key: 4f8c2e10-55b7-4d93-8a6f-1e07b9c4d2a5" \
  -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¶

✅ 201 Created — `tipoContrato` = `1` (Troca de titularidade)¶

Location: /public/api/v1.1/cartao/agendas/534D8AAE-61E4-4264-9D15-715B9E1F1D51/carrinho/itens/7C2C4D03-80BB-43E9-885C-F6A1C2660A68

{
  "idItem": "7C2C4D03-80BB-43E9-885C-F6A1C2660A68",
  "idAgenda": "534D8AAE-61E4-4264-9D15-715B9E1F1D51",
  "tipoContrato": 1,
  "totais": {
    "quantidadeUrs": 2,
    "valorNominal": 24800.00,
    "valorDesconto": 493.52,
    "valorAquisicao": 24306.48,
    "prazoMedio": 37
  },
  "dataValidadeAgenda": "2025-08-11T18:00:00",
  "mensagem": "Item adicionado ao carrinho com sucesso!"
}

✅ 201 Created — `tipoContrato` = `2` (Garantia)¶

Location: /public/api/v1.1/cartao/agendas/534D8AAE-61E4-4264-9D15-715B9E1F1D51/carrinho/itens/A6B1E4C7-2F0D-4B88-9E51-3C7A2D9F6B04

{
  "idItem": "A6B1E4C7-2F0D-4B88-9E51-3C7A2D9F6B04",
  "idAgenda": "534D8AAE-61E4-4264-9D15-715B9E1F1D51",
  "tipoContrato": 2,
  "totais": {
    "quantidadeUrs": 2,
    "valorGarantido": 5000.00,
    "prazoMedio": 21
  },
  "dataValidadeAgenda": "2025-08-11T18:00:00",
  "mensagem": "Item adicionado ao carrinho com sucesso!"
}

Campo	Tipo	Descrição
idItem	string	GUID do item criado no carrinho. É o identificador usado para consultar, alterar e remover o item.
idAgenda	string	GUID da agenda a que o carrinho pertence.
tipoContrato	integer	Natureza do contrato do item: `1` = Troca de titularidade, `2` = Garantia.
totais	object	Consolidado do item. O conteúdo varia conforme `tipoContrato`.
→ quantidadeUrs	number	Quantidade de URs alocadas no item.
→ valorGarantido	number	Valor total garantido pelo item. Presente somente quando `tipoContrato` = `2`.
→ valorNominal	number	Soma dos valores nominais cedidos. Presente somente quando `tipoContrato` = `1`.
→ valorDesconto	number	Deságio total calculado com a `taxa` do item. Presente somente quando `tipoContrato` = `1`.
→ valorAquisicao	number	Valor de aquisição total (`valorNominal` − `valorDesconto`). Presente somente quando `tipoContrato` = `1`.
→ prazoMedio	number	Prazo médio, em dias, das URs do item, ponderado pelo valor.
dataValidadeAgenda	string	Data e hora em que a agenda expira. Depois desse momento, os itens montados sobre ela são invalidados.
mensagem	string	Mensagem de confirmação.

O header Location aponta para o recurso criado. Contrato de garantia não devolve valor nominal, desconto, aquisição nem taxa: não houve cessão ao fundo e, portanto, não existe deságio.

❌ 400 Bad Request¶

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "Campo 'tipoContrato' é obrigatório e deve ser 1 (Troca de titularidade) ou 2 (Garantia).",
    "Campo 'selecao.idsUrs' é obrigatório quando estrategia = 1.",
    "Campo 'selecao.ordem' é obrigatório quando estrategia = 3.",
    "Campo 'performance.valorUr' é 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.

❌ 409 Conflict — UR sem valor disponível no carrinho¶

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "titulo": "Conflito",
  "status": 409,
  "erros": [
    "A UR '34BBF492-69CD-4C77-938F-1FBA792CD6ED' já está alocada em outros itens deste carrinho: a soma alocada (4.500,00) excede o valorDisponivel (4.200,00)."
  ]
}

Retornado quando a soma alocada da mesma UR entre os itens do mesmo carrinho ultrapassa o valorDisponivel dela. É um conflito de consistência interna do carrinho — não tem relação com o que outros financiadores estejam fazendo com a mesma UR.

🔄 Mudanças nesta versão¶

A rota simula-contrato passou a ser carrinho/itens/previa e a criação do item passou a ser carrinho/itens. O endpoint antigo de simulação não criava simulação alguma — era cálculo; o de criação persistia um "carrinho de simulação" que na prática já era um item de contrato.
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.
Saiu o 409 de "URs já reservadas em outra simulação". Era inatingível: não existe reserva de UR. O único 409 deste endpoint é o de estouro do valorDisponivel dentro do próprio carrinho.

🕒 Observações¶

Adicionar um item não reserva a UR. Não há trava de exclusividade antes do registro do contrato na registradora: até lá, outro financiador pode contratar a mesma UR. Quem registra primeiro constitui o ônus.
O corpo aceito aqui é idêntico ao de 4.9. Prévia do item. Use a prévia para conferir a composição antes de criar.
O header Idempotency-Key é obrigatório: em caso de reenvio da mesma chave, a plataforma devolve o item já criado em vez de criar um segundo.
Para criar de uma vez um item por parcela de uma garantia parcelada, use 4.11. Adicionar itens em lote.
Com o carrinho montado, o contrato é gerado em 5.1. Criar contratos.
Depois de dataValidadeAgenda, os itens montados sobre a agenda são invalidados 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.