--- title: 4.10. Adicionar 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.10.%20Adicionar%20item/ --- # 4.10. Adicionar item ## 🔗 Endpoint | Método | URL | | ----------------------------------------------- | -------------------------------------------------------------- | | ![POST](https://img.shields.io/badge/POST-blue) | `/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](../../5.%20Contrato%20de%20recebíveis/v1.1/5.1.%20Criar%20contratos.md). O corpo é **exatamente o mesmo** de [4.9. Prévia do item](4.9.%20Prévia%20do%20item.md). 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) ```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) ```bash 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 ```bash 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) ```bash 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 ``` ```json { "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 ``` ```json { "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 ```json { "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 ```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. --- ### ❌ 409 Conflict — UR sem valor disponível no carrinho ```json { "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](4.9.%20Prévia%20do%20item.md). 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](4.11.%20Adicionar%20itens%20em%20lote.md). * Com o carrinho montado, o contrato é gerado em [5.1. Criar contratos](../../5.%20Contrato%20de%20recebíveis/v1.1/5.1.%20Criar%20contratos.md). * Depois de `dataValidadeAgenda`, os itens montados sobre a agenda são invalidados 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**.