Copiar Página

4.15. Remover item

🔗 Endpoint

Método	URL
	/public/api/v1.1/cartao/agendas/{idAgenda}/carrinho/itens/{idItem}

---

🧾 Descrição

Remove um item do carrinho da agenda, desfazendo por completo a alocação que ele mantinha.

Ao remover o item, a plataforma VeFlow libera todas as URs que estavam alocadas nele: o valor que estava em valorGarantido deixa de onerar a UR e volta a compor o valorLivre e o valorDisponivel, ficando pronto para ser usado em outro item.

A remoção só é possível enquanto o item ainda não virou contrato. Depois de o contrato ser gerado, o item deixa de ser editável e a operação é recusada com 409 Conflict — nesse ponto o caminho é o cancelamento do contrato, na seção 5.

📋 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

Esta requisição não tem corpo. O item a remover é identificado apenas pelos parâmetros de rota.

---

🧪 Exemplo de cURL

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 \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -H "Idempotency-Key: 3f7a90c1-2b48-4d6e-9a11-08cd5e2b7431" \
  -H "Content-Type: application/json"

---

📥 Responses

✅ 200 OK

{
  "mensagem": "Item removido do carrinho e URs liberadas.",
  "ursLiberadas": [
    {
      "idUr": "7D121577-3C5A-494D-B052-291D9E100D0D",
      "valorLiberado": 1500.00
    },
    {
      "idUr": "A1B2C3D4-5E6F-7890-1234-56789ABCDEF0",
      "valorLiberado": 3200.00
    }
  ]
}

🧾 Detalhamento dos Campos

Campo	Tipo	Descrição
mensagem	string	Mensagem de confirmação da remoção.
ursLiberadas	object[]	URs que estavam alocadas no item e cujos valores foram liberados.

🔹 ursLiberadas

Campo	Tipo	Descrição
idUr	string	GUID da UR liberada.
valorLiberado	number	Valor que estava em valorGarantido nesse item e voltou a compor o valorLivre e o valorDisponivel da UR.

Quando o item não tinha nenhuma UR alocada, ursLiberadas volta como um array vazio ([]) e a remoção do item é confirmada normalmente.

---

❌ 400 Bad Request

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "Parâmetro 'idItem' inválido. Formato esperado: GUID."
  ]
}

---

❌ 404 Not Found

Retornado quando a agenda ou o item informados não existem no grupo econômico.

{
  "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 pode mais ser removido do carrinho.

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "titulo": "Atenção",
  "status": 409,
  "erros": [
    "O item já gerou contrato e não pode ser removido do carrinho."
  ]
}

---

🔄 Mudanças nesta versão

O que mudou	Detalhe
A resposta de sucesso é sempre 200 OK	Saiu o 204 No Content que a versão anterior descrevia como alternativa. Não existe retorno sem corpo neste endpoint.
O retorno passou a informar ursLiberadas	Antes vinha apenas a mensagem. Agora a resposta lista UR por UR o valor devolvido ao valorLivre e ao valorDisponivel.
O recurso passou a se chamar item de carrinho	A rota antiga era simulacoes/{idSimulacao}. O item de carrinho é o mesmo objeto que, ao ser fechado, se torna contrato.
O bloqueio operativo virou uma regra explícita	O 409 Conflict acontece em um único caso: o item já gerou contrato.

---

🕒 Observações

• A liberação é imediata: assim que a resposta 200 chega, os valores já podem ser alocados em outro item do carrinho.
• Para remover apenas parte das URs e manter o item, use 4.17. Remover URs do item. Este endpoint remove o item inteiro.
• Remover o item não altera a agenda: as URs continuam listadas em 4.4. Listar URs da agenda, apenas com os valores de novo livres.
• Se a agenda passou da dataValidade, os itens montados sobre ela já foram invalidados e é preciso refazer a consulta — ver 4.3. Detalhes da agenda e 4.7. Refazer consulta.
• Headers obrigatórios e convenções gerais: 1.2. Convenções da API.