--- title: 4.17. Remover URs 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.17.%20Remover%20URs%20do%20item/ --- # 4.17. Remover URs do item ## 🔗 Endpoint Há duas formas de remover URs de um item de carrinho: a **forma canônica**, uma UR por chamada, e a **forma em lote**, várias URs na mesma chamada. | Método | URL | | -------------------------------------------------- | ----------------------------------------------------------------------------------- | | ![DELETE](https://img.shields.io/badge/DELETE-red) | `/public/api/v1.1/cartao/agendas/{idAgenda}/carrinho/itens/{idItem}/urs/{idUr}` | | ![DELETE](https://img.shields.io/badge/DELETE-red) | `/public/api/v1.1/cartao/agendas/{idAgenda}/carrinho/itens/{idItem}/urs` | --- ## 🧾 Descrição Desfaz o vínculo de uma ou mais URs com um **item de carrinho**, sem remover o item. Ao remover, o valor que estava em `valorGarantido` naquele item deixa de onerar a UR e **volta a compor o `valorLivre` e o `valorDisponivel`** da UR, ficando pronto para ser alocado em outro item. A operação é **idempotente**: remover uma UR que já não está no item devolve `200 OK` com `removidas` igual a `0`. Repetir a mesma chamada é seguro e não gera erro. Só é possível remover URs enquanto o item **ainda não virou contrato**. Depois disso, a composição está fechada e a operação é recusada com `409 Conflict`. ### 📋 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**. | | idUr | string | Sim¹ | GUID da UR a remover. ¹Usado apenas na forma canônica, uma UR por chamada. | --- ## 📤 Requisição ### 🔹 Forma canônica — uma UR por chamada `DELETE /public/api/v1.1/cartao/agendas/{idAgenda}/carrinho/itens/{idItem}/urs/{idUr}` **Não tem corpo.** A UR a remover é identificada pelo próprio path. É a forma recomendada: cada chamada trata de um único recurso e pode ser repetida sem efeito colateral. ### 🔹 Forma em lote — várias URs por chamada `DELETE /public/api/v1.1/cartao/agendas/{idAgenda}/carrinho/itens/{idItem}/urs` Usa corpo com a lista de URs a remover. Indicada para desfazer de uma vez a composição de um item grande. #### 📋 Payload (JSON) ```json { "idsUrs": [] } ``` #### 🧾 Detalhamento dos Campos | Campo | Tipo | Obrigatório | Descrição | | ------ | -------- | ----------- | ---------------------------------------------------------------------------- | | idsUrs | string[] | Sim | GUIDs das URs a remover do item. Deve conter ao menos um elemento. | **Regras de validação** * `idsUrs` não pode ser vazio e todos os elementos devem ser GUIDs válidos. * IDs que não estão vinculados ao item são **simplesmente ignorados** e não entram na contagem de `removidas`. Não geram erro. * A remoção em lote é aplicada em uma única transação: ou todas as URs vinculadas informadas são removidas, ou nenhuma é. --- ## 🧪 Exemplos de cURL ### Forma canônica ```bash curl -X DELETE https://api.veflow.com/public/api/v1.1/cartao/agendas/534D8AAE-61E4-4264-9D15-715B9E1F1D51/carrinho/itens/AEB4EA8C-BEF4-4E4E-A009-0A94AF172EAB/urs/7D121577-3C5A-494D-B052-291D9E100D0D \ -H "Authorization: Bearer {seu_token}" \ -H "GrupoEconomico: {seu_grupo_economico}" \ -H "Idempotency-Key: 5b1d84fa-6c07-4f2e-9b73-a0c48e1d2266" \ -H "Content-Type: application/json" ``` ### Forma em lote ```bash curl -X DELETE 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: 8ac3f512-90de-4b61-8f4a-3d7e6019c5b2" \ -H "Content-Type: application/json" \ -d '{ "idsUrs": [ "7D121577-3C5A-494D-B052-291D9E100D0D", "A1B2C3D4-5E6F-7890-1234-56789ABCDEF0" ] }' ``` --- ## 📥 Responses As duas formas devolvem o mesmo corpo. ### ✅ 200 OK ```json { "removidas": 2, "totais": { "quantidadeUrs": 10, "valorGarantido": 45050.00, "valorLiberado": 3200.00 } } ``` ### 🧾 Detalhamento dos Campos | Campo | Tipo | Descrição | | --------- | ------- | -------------------------------------------------------------------- | | removidas | integer | Quantidade de URs efetivamente desvinculadas nesta chamada. | | totais | object | Consolidado do item **depois** da operação. | #### 🔹 totais | Campo | Tipo | Descrição | | -------------- | ------- | ------------------------------------------------------------------------------------------------------ | | quantidadeUrs | integer | Quantidade de URs que continuam vinculadas ao item após a remoção. | | valorGarantido | number | Soma do `valorGarantido` que continua alocada no item após a remoção. | | valorLiberado | number | Soma dos valores liberados nesta chamada, que voltaram a compor o `valorLivre` e o `valorDisponivel` das URs. | --- ### ✅ 200 OK — nada a remover Quando nenhuma das URs informadas está vinculada ao item, a resposta é `200 OK` com `removidas` igual a `0` e `valorLiberado` igual a `0`. Esse é o comportamento **idempotente** do endpoint: repetir uma remoção já aplicada não é um erro. ```json { "removidas": 0, "totais": { "quantidadeUrs": 10, "valorGarantido": 45050.00, "valorLiberado": 0.00 } } ``` --- ### ❌ 400 Bad Request ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1", "titulo": "Atenção", "status": 400, "erros": [ "O array 'idsUrs' deve conter ao menos um elemento.", "Parâmetro 'idUr' inválido. Formato esperado: GUID." ] } ``` --- ### ❌ 404 Not Found Retornado quando a agenda ou o item informados não existem no grupo econômico. Note que uma UR **não vinculada** ao item não gera `404`: gera `200` com `removidas` igual a `0`. ```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 o item **já virou contrato** e por isso não aceita mais alteração de composição. ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.10", "titulo": "Atenção", "status": 409, "erros": [ "O item já gerou contrato e sua composição não pode mais ser alterada." ] } ``` --- ## 🔄 Mudanças nesta versão | O que mudou | Detalhe | | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | A rota `remove-ur` virou o sub-recurso `urs` | Passou a existir a forma canônica `.../urs/{idUr}`, sem corpo, além da forma em lote `.../urs` com corpo. | | `idTitulos` virou `idsUrs` | O recurso é a UR, e listas de identificadores de UR se chamam `idsUrs`. | | A idempotência ficou definida | A versão anterior dizia "400 ou simplesmente ignorado, dependendo da política". A definição é: remover UR que já não está no item devolve `200` com `removidas` igual a `0`. | | Entrou o bloco `totais` | Antes o retorno era só uma mensagem. Agora a resposta diz quanto ainda está alocado no item e quanto foi liberado nesta chamada. | --- ## 🕒 Observações * A liberação é **imediata**: o valor devolvido em `valorLiberado` já pode ser alocado em outro item do carrinho na chamada seguinte. * A remoção **não dispara nova alocação automática**. Mesmo em itens criados com `estrategia` igual a `4` (Alocação automática por parcela), a lacuna aberta pela remoção permanece até que você recomponha o item — use [4.16. Adicionar URs ao item](4.16.%20Adicionar%20URs%20ao%20item.md). * Para remover o item inteiro, e não apenas algumas URs, use [4.15. Remover item](4.15.%20Remover%20item.md). * Para conferir a composição do item depois da remoção, use [4.18. Listar URs do item](4.18.%20Listar%20URs%20do%20item.md). * Os valores liberados voltam a aparecer como livres na agenda — ver os totais em [4.3. Detalhes da agenda](4.3.%20Detalhes%20da%20agenda.md) e a UR em [4.4. Listar URs da agenda](4.4.%20Listar%20URs%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).