---
title: 4.6. Adicionar UR a Simulação
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.6.%20Adicionar%20UR%20na%20simula%C3%A7%C3%A3o/
---
# 4.6. Adicionar UR a Simulação

## 🔗 Endpoint

| Método                                          | URL                                                                           |
| ----------------------------------------------- |-------------------------------------------------------------------------------|
| ![POST](https://img.shields.io/badge/POST-blue) | `/api/v1.1/cartao/agenda/{identificador}/simulacoes/{idSimulacao}/adiciona-ur` |

---

## 🧾 Descrição

Vincula manualmente (ou por lote) URs performadas a simulação já cadastradas para uma agenda específica. Esse endpoint permite ao usuário forçar a associação de uma ou mais URs a uma simulação/contrato identificado, quando a alocação automática não atende ou quando há necessidade de ajuste manual.

Validações importantes realizadas pelo servidor:

* As URs informadas em `idTitulos` devem estar presentes na agenda referenciada por `{identificador}`.
* Cada UR deve possuir `valorLivre` > 0 para ser efetivamente vinculada.

---

## 📤 Requisição

### 📋 Payload (JSON)

```json
{
  "idTitulos": []
}
```

### 🧾 Detalhamento dos Campos

| Campo       | Tipo     | Obrigatório | Descrição                                                                                                                   |
| ----------- |----------|-------------|-----------------------------------------------------------------------------------------------------------------------------|
| idTitulos   | string[] | Sim         | Lista de GUIDs das URs a serem vinculadas. Essas URs **devem** estar presentes na agenda especificada por `{identificador}`. |
| idSimulacao | string   | Sim         | GUID da simulação onde as URs serão vinculadas.                                                                     |

**Regras de validação**

* `idTitulos` deve conter pelo menos 1 GUID válido.
* Para cada `idTitulo`:

    * Verificar se pertence à agenda `{identificador}` — caso contrário, retornar erro (4xx).
    * Verificar `valorLivre` > 0 — caso contrário, retornar erro (4xx).

---

## 🧪 Exemplo de cURL

```bash
curl -X POST https://api.veflow.com/api/v1.1/cartao/agenda/534D8AAE-61E4-4264-9D15-715B9E1F1D51/vincula-ur-parcela-garantia \
  -H "Authorization: Bearer {seu_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "idTitulos": [
      "7D121577-3C5A-494D-B052-291D9E100D0D",
      "A1B2C3D4-5E6F-7890-1234-56789ABCDEF0"
    ],
    "idSimulacao": "264E71E2-827D-4EE2-A0E9-AD66EF851C5C"
  }'
```

---

## 📥 Responses

### ✅ 200 OK

```json
{
  "mensagem": "Vínculos processados."
}
```

Indica que os vínculos foram processados com sucesso. O retorno não detalha individualmente cada vínculo — para isso consulte o recurso de detalhe da simulação/agenda.

---

### ❌ 400 Bad Request — UR não pertence à agenda (exemplo)

```json
{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "UR 'A1B2C3D4-5E6F-7890-1234-56789ABCDEF0' não pertence à agenda '534D8AAE-61E4-4264-9D15-715B9E1F1D51'."
  ]
}
```

---

### ❌ 400 Bad Request — UR sem valor livre (exemplo)

```json
{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "UR '7D121577-3C5A-494D-B052-291D9E100D0D' possui valorLivre = 0 e não pode ser vinculada."
  ]
}
```

---

### ❌ 409 Conflict — conflito de vínculo (exemplo)

```json
{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Conflito",
  "status": 409,
  "erros": [
    "UR '7D121577-3C5A-494D-B052-291D9E100D0D' já está vinculada a outra parcela no contrato 'CTR-2025-0001'."
  ]
}
```

---

## 🕒 Observações

* O processamento pode ser síncrono (resposta imediata) ou assíncrono (retorno de identificador para acompanhamento) dependendo do volume — o contrato de API deve definir o comportamento.
* Após vinculação, os balances (`valorLivre`, `valorGarantido`) da UR serão atualizados.
* Autenticação obrigatória via `Authorization: Bearer {token}`.
* Para desfazer vínculos, utilize o endpoint de remoção de vínculo.