--- title: 5.8. Remover URs do contrato url: https://docs.vehub.com.br/API/VeFlow%20-%20Cart%C3%A3o%20de%20cr%C3%A9dito/5.%20Contrato%20de%20receb%C3%ADveis/v1.1/5.8.%20Remover%20URs%20do%20contrato/ --- # 5.8. Remover URs do contrato ## 🔗 Endpoint | Método | URL | Uso | | -------------------------------------------------- | ------------------------------------------------------------ | -------------------------------- | | ![DELETE](https://img.shields.io/badge/DELETE-red) | `/public/api/v1.1/cartao/contratos/{idContrato}/urs/{idUr}` | Forma canônica — uma UR, sem corpo | | ![DELETE](https://img.shields.io/badge/DELETE-red) | `/public/api/v1.1/cartao/contratos/{idContrato}/urs` | Em lote — corpo com `idsUrs` | --- ## 🧾 Descrição Solicita a remoção de uma ou mais **URs (Unidades de Recebíveis)** vinculadas a um contrato de cartão, liberando o valor comprometido daquelas URs. A rota existe em **duas formas**: * **Canônica** — `DELETE .../urs/{idUr}`: remove **uma** UR identificada na própria rota, **sem corpo** na requisição. É a forma preferencial. * **Em lote** — `DELETE .../urs`: remove **várias** URs de uma vez, com o array `idsUrs` no corpo da requisição. As duas formas respondem `202 Accepted` com `identificadorProcessamento`. A execução é **assíncrona**: o `202` indica apenas que a solicitação passou pelas validações iniciais; a efetivação da remoção é informada por webhook. --- ## ⚠ Regras de remoção * A UR **não pode estar liquidada**. * A **data de liquidação da UR** deve estar a **no mínimo D+3 dias úteis** da data atual. * A requisição é aceita **somente dentro da janela operacional: 09:00 às 18:00 em dias úteis**. * Cada UR é avaliada individualmente no lote: parte da lista pode ser removida com sucesso enquanto outra parte é recusada. O desfecho por UR chega por webhook. * Contratos cancelados (`status = 5`) e liquidados (`status = 7`) não aceitam remoção de URs. --- ## 📤 Requisição ### 🔑 Parâmetros de rota | Parâmetro | Tipo | Obrigatório | Descrição | | ---------- | ------ | --------------------- | -------------------------------------------------------------------------------- | | idContrato | string | Sim | GUID do contrato, devolvido em [5.1. Criar contratos](5.1.%20Criar%20contratos.md). | | idUr | string | Sim na forma canônica | GUID da UR a ser removida do contrato. Não se aplica à forma em lote. | ### 📋 Payload (JSON) — apenas na forma em lote ```json { "idsUrs": [ "" ] } ``` | Campo | Tipo | Obrigatório | Descrição | | ------ | -------- | ----------- | --------------------------------------------------------------------------------------------- | | idsUrs | string[] | Sim | Lista de GUIDs das URs a serem removidas do contrato. Mínimo de 1 e máximo de 500 itens. | **Regras e formatos** * A forma canônica (`.../urs/{idUr}`) **não aceita corpo**. Enviar corpo nessa rota resulta em `400 Bad Request`. * Na forma em lote, `idsUrs` não pode conter GUIDs repetidos. --- ## 🧪 Exemplo de cURL — forma canônica (uma UR) ```bash curl -X DELETE https://api.veflow.com/public/api/v1.1/cartao/contratos/5174568D-9FFE-4C10-9FC2-B0F4E7F8D1B6/urs/29E8F0CE-3391-4A65-8091-2331802CEABE \ -H "Authorization: Bearer {seu_token}" \ -H "GrupoEconomico: {seu_grupo_economico}" \ -H "Idempotency-Key: b52d9f74-6c31-4a8e-8f10-90d7c2ab4e65" ``` ## 🧪 Exemplo de cURL — em lote ```bash curl -X DELETE https://api.veflow.com/public/api/v1.1/cartao/contratos/5174568D-9FFE-4C10-9FC2-B0F4E7F8D1B6/urs \ -H "Authorization: Bearer {seu_token}" \ -H "GrupoEconomico: {seu_grupo_economico}" \ -H "Idempotency-Key: c0a41e88-7b52-4f19-b6d3-2ea8f5c71d04" \ -H "Content-Type: application/json" \ -d '{ "idsUrs": [ "29E8F0CE-3391-4A65-8091-2331802CEABE", "7D121577-3C5A-494D-B052-291D9E100D0D" ] }' ``` --- ## 📥 Responses ### ✅ 202 Accepted ```json { "identificadorProcessamento": "A1B2C3D4-1111-2222-3333-444455556666", "mensagem": "Solicitação de remoção de URs recebida com sucesso!" } ``` | Campo | Tipo | Descrição | | -------------------------- | ------ | -------------------------------------------------------- | | identificadorProcessamento | string | GUID do processamento assíncrono, para acompanhamento. | | mensagem | string | Mensagem de confirmação do recebimento. | --- ### ❌ 400 Bad Request ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1", "titulo": "Atenção", "status": 400, "erros": [ "Campo 'idsUrs' é obrigatório e deve conter ao menos um item.", "A UR já está liquidada e não pode ser removida.", "A data de liquidação da UR deve estar a no mínimo D+3 dias úteis da data atual.", "O contrato está cancelado e não permite remoção de URs." ] } ``` --- ### ❌ 403 Forbidden — fora da janela de operação ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.4", "titulo": "Atenção", "status": 403, "erros": [ "Operação permitida apenas entre 09:00 e 18:00 em dias úteis." ] } ``` --- ### ❌ 404 Not Found ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.5", "titulo": "Atenção", "status": 404, "erros": [ "Contrato não encontrado." ] } ``` Também é o retorno quando a UR informada não está vinculada ao contrato. --- ## 🔄 Mudanças em relação à v1 | Aspecto | v1 | v1.1 | | ------------------ | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | Rota | `DELETE /public/api/v1/cartao/contrato/{id}/titulos` | `DELETE /public/api/v1.1/cartao/contratos/{idContrato}/urs/{idUr}` (canônica) e `.../urs` (em lote) | | Campo da lista | `idTitulos` | `idsUrs` | | Retorno de sucesso | `200 OK` com `identificador` e `mensagem` | `202 Accepted` com `identificadorProcessamento` e `mensagem` | | Fora da janela | Objeto simples com `mensagem` | `403 Forbidden` no formato **RFC 9110** (`tipo`, `titulo`, `status`, `erros`) | --- ## 🕒 Observações * O `202 Accepted` indica apenas que a solicitação passou pelas validações iniciais. A **efetivação da remoção é informada por webhook** — ver [3.2. Atualizações do contrato](../../3.%20Notificações%20-%20WebHook/3.2.%20Atualizações%20do%20contrato.md). * A remoção libera o `valorGarantido` que aquela UR mantinha comprometido no contrato; o valor volta a ficar livre para novos contratos. * URs efetivamente removidas passam a ser listadas em [5.10. URs removidas e rejeitadas](5.10.%20URs%20removidas%20e%20rejeitadas.md), com `dataRemocao` e `dataConfirmacaoRemocao`. * Para repor a composição do contrato depois de uma remoção, use [5.7. Adicionar URs ao contrato](5.7.%20Adicionar%20URs%20ao%20contrato.md). * Envie sempre o header `Idempotency-Key`: em caso de reenvio, a mesma chave devolve o `identificadorProcessamento` original em vez de duplicar a solicitação. * Headers obrigatórios e convenções gerais: [1.1. Primeiros Passos](../../1.%20Início/1.1.%20Primeiros%20Passos.md).