5.8. Remover URs do contrato¶

🔗 Endpoint¶

Método	URL	Uso
	`/public/api/v1.1/cartao/contratos/{idContrato}/urs/{idUr}`	Forma canônica — uma UR, sem corpo
	`/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.
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¶

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

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¶

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¶

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

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

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

{
  "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.
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, com dataRemocao e dataConfirmacaoRemocao.
Para repor a composição do contrato depois de uma remoção, use 5.7. Adicionar URs ao contrato.
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.