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
	`/public/api/v1.1/cartao/agendas/{idAgenda}/carrinho/itens/{idItem}/urs/{idUr}`
	`/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)¶

{
  "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¶

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¶

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¶

{
  "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.

{
  "removidas": 0,
  "totais": {
    "quantidadeUrs": 10,
    "valorGarantido": 45050.00,
    "valorLiberado": 0.00
  }
}

❌ 400 Bad Request¶

{
  "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.

{
  "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.

{
  "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.
Para remover o item inteiro, e não apenas algumas URs, use 4.15. Remover item.
Para conferir a composição do item depois da remoção, use 4.18. Listar URs do item.
Os valores liberados voltam a aparecer como livres na agenda — ver os totais em 4.3. Detalhes da agenda e a UR em 4.4. Listar URs da agenda.
Headers obrigatórios e convenções gerais: 1.2. Convenções da API.