--- title: 4.16. Adicionar URs ao 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.16.%20Adicionar%20URs%20ao%20item/ --- # 4.16. Adicionar URs ao item ## 🔗 Endpoint | Método | URL | | ----------------------------------------------- | ------------------------------------------------------------------------ | | ![POST](https://img.shields.io/badge/POST-blue) | `/public/api/v1.1/cartao/agendas/{idAgenda}/carrinho/itens/{idItem}/urs` | --- ## 🧾 Descrição Vincula URs da agenda a um **item de carrinho** já existente, informando quanto de cada UR deve ser alocado no item. É o endpoint de ajuste manual da composição: use-o para completar um item criado com `estrategia` igual a `1` (URs selecionadas) ou para corrigir a composição de um item montado com `estrategia` igual a `4` (Alocação automática por parcela), quando a alocação automática não atendeu. O processamento é **síncrono**: a resposta já traz o resultado consolidado da alocação, com o que foi aceito, o que foi ignorado e os totais do item. Este endpoint **não** devolve `identificadorProcessamento`. Informar `valorGarantido` por UR é justamente o que habilita o **rateio parcial**: a mesma UR pode compor mais de um item do carrinho, desde que a soma alocada entre todos os itens não passe do seu `valorDisponivel`. ### 📋 Parâmetros de rota | Parâmetro | Tipo | Obrigatório | Descrição | | --------- | ------ | ----------- | -------------------------------------------------------------------- | | idAgenda | string | Sim | GUID da agenda, devolvido como `identificador` em **4.1** e **4.2**. | | idItem | string | Sim | GUID do item de carrinho, devolvido na criação do item em **4.10**. | --- ## 📤 Requisição ### 📋 Payload (JSON) ```json { "urs": [ { "idUr": "", "valorGarantido": 0.00, "tipoValor": 1 } ] } ``` ### 🧾 Detalhamento dos Campos | Campo | Tipo | Obrigatório | Descrição | | -------------------- | -------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | urs | object[] | Sim | URs a vincular ao item. Deve conter ao menos um elemento. | | urs[].idUr | string | Sim | GUID da UR a vincular. A UR **deve** pertencer à agenda informada em `{idAgenda}`. | | urs[].valorGarantido | number | Não | Quanto da UR alocar neste item. Quando omitido, aloca todo o `valorDisponivel` da UR. | | urs[].tipoValor | integer | Não | Como interpretar `valorGarantido`. Ver tabela **Tipo de valor**. Padrão: `1` (Valor absoluto). | ### 🔢 Tipo de valor | Código | Significado | Como o `valorGarantido` é interpretado | | ------ | -------------- | ------------------------------------------------------------------------------- | | 1 | Valor absoluto | Valor em reais, com até 2 casas decimais. | | 2 | Percentual | Percentual do `valorDisponivel` da UR, de `0` a `100`, com até 4 casas decimais. | **Regras de validação** * `urs` não pode ser vazio e cada elemento precisa ter `idUr`. * Cada UR informada **deve pertencer à agenda** do path. * Cada UR informada **deve ter `valorDisponivel` maior que zero** para ser alocada. * Quando `valorGarantido` é informado, precisa ser maior que zero e não pode passar do `valorDisponivel` da UR. * URs que não passam nas validações individuais **não interrompem a chamada**: elas voltam no array `ignoradas` com o motivo, e as demais são alocadas normalmente. * Se a soma alocada da **mesma UR** entre os itens do carrinho passar do `valorDisponivel`, a chamada inteira é recusada com `409 Conflict` e nenhuma alocação é aplicada. --- ## 🧪 Exemplo de cURL ```bash curl -X POST https://api.veflow.com/public/api/v1.1/cartao/agendas/534D8AAE-61E4-4264-9D15-715B9E1F1D51/carrinho/itens/AEB4EA8C-BEF4-4E4E-A009-0A94AF172EAB/urs \ -H "Authorization: Bearer {seu_token}" \ -H "GrupoEconomico: {seu_grupo_economico}" \ -H "Idempotency-Key: c48e21b0-7f35-49aa-8d02-1e6b5c93af77" \ -H "Content-Type: application/json" \ -d '{ "urs": [ { "idUr": "7D121577-3C5A-494D-B052-291D9E100D0D", "valorGarantido": 1500.00, "tipoValor": 1 }, { "idUr": "A1B2C3D4-5E6F-7890-1234-56789ABCDEF0", "valorGarantido": 50.0000, "tipoValor": 2 } ] }' ``` --- ## 📥 Responses ### ✅ 200 OK ```json { "adicionadas": 2, "ignoradas": [ { "idUr": "B7E4C0D2-9A18-4F55-83C6-2D1F7A9E4B30", "motivo": "UR não pertence à agenda informada." } ], "totais": { "quantidadeUrs": 12, "valorGarantido": 48250.00, "valorGarantidoAdicionado": 3200.00 } } ``` ### 🧾 Detalhamento dos Campos | Campo | Tipo | Descrição | | ----------- | -------- | ----------------------------------------------------------------------------- | | adicionadas | integer | Quantidade de URs efetivamente vinculadas ao item nesta chamada. | | ignoradas | object[] | URs informadas que não foram vinculadas, com o motivo de cada uma. | | totais | object | Consolidado do item **depois** da operação. | #### 🔹 ignoradas | Campo | Tipo | Descrição | | ------ | ------ | --------------------------------------------------------------- | | idUr | string | GUID da UR que não foi vinculada. | | motivo | string | Motivo da recusa. Ver tabela **Motivos de UR ignorada**. | #### 🔹 totais | Campo | Tipo | Descrição | | ------------------------ | ------- | ------------------------------------------------------------------------------------- | | quantidadeUrs | integer | Quantidade de URs vinculadas ao item após a operação. | | valorGarantido | number | Soma do `valorGarantido` alocado no item após a operação. | | valorGarantidoAdicionado | number | Soma dos valores alocados nesta chamada. | --- ### 📝 Motivos de UR ignorada | Motivo | Quando acontece | | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `UR não pertence à agenda informada.` | O `idUr` existe, mas está em outra agenda. Cada item só pode ser composto por URs da agenda em que foi criado. | | `UR sem valor disponível para alocação.` | O `valorDisponivel` da UR é zero — ela já está integralmente alocada em outros itens ou comprometida. | | `UR já vinculada a este item.` | A UR já compõe o item. Para alterar o valor alocado, remova-a em **4.17** e vincule novamente. | | `UR não performada e o item exige somente URs performadas.` | O item é de garantia com configuração de fumaça, que aceita apenas URs performadas. | --- ### ❌ 400 Bad Request ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1", "titulo": "Atenção", "status": 400, "erros": [ "O array 'urs' deve conter ao menos um elemento.", "Campo 'idUr' é obrigatório em todos os elementos de 'urs'.", "Campo 'tipoValor' inválido. Valores aceitos: 1 ou 2." ] } ``` --- ### ❌ 404 Not Found Retornado quando a agenda ou o item informados não existem no grupo econômico. ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.5", "titulo": "Atenção", "status": 404, "erros": [ "Item de carrinho não encontrado na agenda informada." ] } ``` --- ### ❌ 409 Conflict Retornado quando a soma alocada da mesma UR entre os itens do carrinho passa do `valorDisponivel` da UR. Nenhuma alocação da chamada é aplicada. ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.10", "titulo": "Atenção", "status": 409, "erros": [ "UR '7D121577-3C5A-494D-B052-291D9E100D0D' já possui 1200.00 alocados em outros itens do carrinho. A soma solicitada (2000.00) excede o valorDisponivel de 1500.00." ] } ``` --- ## 🔄 Mudanças nesta versão | O que mudou | Detalhe | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A rota `adiciona-ur` virou o sub-recurso `urs` | As URs de um item passaram a ser um sub-recurso REST: `.../carrinho/itens/{idItem}/urs`. A rota `vincula-ur-parcela-garantia`, que aparecia no cURL antigo, não existe. | | `idTitulos` virou o array `urs` com valor por UR | Antes era uma lista simples de GUIDs, que só permitia alocar a UR inteira. Agora cada elemento leva `idUr`, `valorGarantido` e `tipoValor`, o que habilita o rateio parcial. | | O campo `idSimulacao` saiu do corpo | O identificador do item já está no path, em `{idItem}`. Mandá-lo também no corpo era redundante e permitia divergência. | | O comportamento é síncrono | A versão anterior dizia que a operação poderia ser síncrona ou assíncrona. A definição é: **síncrona**, com o resultado consolidado na própria resposta. | | Entraram `ignoradas` e `totais` | Antes o retorno era só uma mensagem, sem detalhe por vínculo. Agora a resposta diz o que entrou, o que foi ignorado e como o item ficou. | --- ## 🕒 Observações * Este endpoint trata apenas de **alocação** (`valorGarantido`). Deságio não é calculado aqui: contratos de garantia não têm deságio, e em itens de troca de titularidade os valores de antecipação (`valorNominal`, `valorDesconto` e `valorAquisicao`) são apurados nas consultas de contrato, na seção 5. * O `tipoContrato` do item define o que pode ser vinculado: `1` (Troca de titularidade) ou `2` (Garantia). Quando a garantia usa a configuração de **fumaça** — prazo estendido, somente URs performadas e regra de retenção —, apenas URs performadas são aceitas. * URs com **promessa de cessão** já têm o ônus de terceiro refletido em `valorComprometido`, o que reduz o `valorLivre` e, por consequência, o `valorDisponivel`. A promessa de cessão aparece apenas em leitura, nunca é criada pela API. * Use `Idempotency-Key` para poder repetir a chamada com segurança em caso de timeout, sem alocar a mesma UR duas vezes. * Para conferir como o item ficou, use [4.18. Listar URs do item](4.18.%20Listar%20URs%20do%20item.md). Para desfazer vínculos, use [4.17. Remover URs do item](4.17.%20Remover%20URs%20do%20item.md). * Confira a `dataValidade` da agenda antes de vincular URs: passada a validade, os itens montados sobre ela são invalidados — ver [4.3. Detalhes da agenda](4.3.%20Detalhes%20da%20agenda.md). * Headers obrigatórios e convenções gerais: [1.2. Convenções da API](../../1.%20Início/1.2.%20Convenções%20da%20API.md).