---
title: 5.7. Adicionar URs ao 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.7.%20Adicionar%20URs%20ao%20contrato/
---
# 5.7. Adicionar URs ao contrato

## 🔗 Endpoint

| Método                                          | URL                                                  |
| ----------------------------------------------- | ---------------------------------------------------- |
| ![POST](https://img.shields.io/badge/POST-blue) | `/public/api/v1.1/cartao/contratos/{idContrato}/urs` |

---

## 🧾 Descrição

Adiciona uma ou mais **URs (Unidades de Recebíveis)** a um contrato já existente, reforçando a composição do contrato sem precisar cancelá-lo e recriá-lo.

O processamento é **assíncrono**: a plataforma **VeFlow** valida a requisição, responde `202 Accepted` com o `identificadorProcessamento` e segue com o vínculo junto à registradora. **O resultado de cada UR é informado por webhook** — ver [3.2. Atualizações do contrato](../../3.%20Notificações%20-%20WebHook/3.2.%20Atualizações%20do%20contrato.md).

---

## ⚠ Regras de inclusão

* A UR **não pode estar liquidada**.
* O `valorGarantido` solicitado não pode exceder o **valor livre** da UR na registradora. URs já comprometidas em outros contratos entram somente pelo saldo remanescente.
* O contrato precisa estar em status que aceite composição. Contratos cancelados (`status = 5`) e liquidados (`status = 7`) não recebem novas URs.
* A requisição é aceita **somente dentro da janela operacional: 09:00 às 18:00 em dias úteis**.
* Cada UR é processada individualmente: parte da lista pode ser vinculada com sucesso enquanto outra parte falha. O desfecho por UR chega por webhook.

---

## 📤 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). |

### 📋 Payload (JSON)

```json
{
  "urs": [
    {
      "idUr": "",
      "valorGarantido": 0.00
    }
  ]
}
```

### 🧾 Detalhamento dos Campos

| Campo                 | Tipo     | Obrigatório | Descrição                                                                                            |
| --------------------- | -------- | ----------- | ---------------------------------------------------------------------------------------------------- |
| urs                   | object[] | Sim         | Lista de URs a serem adicionadas ao contrato. Mínimo de 1 e máximo de 500 itens por requisição.       |
| urs[].idUr            | string   | Sim         | GUID da UR a ser vinculada ao contrato.                                                              |
| urs[].valorGarantido  | number   | Sim         | Valor da UR a ser comprometido no contrato, com 2 casas decimais. Deve ser maior que zero.            |

**Regras e formatos**

* `idUr` não pode se repetir dentro da mesma requisição.
* `valorGarantido` é o vocabulário da fase de contrato: representa quanto daquela UR passa a estar comprometido neste contrato.
* Em contratos de **troca de titularidade** (`tipoContrato = 1`), `valorNominal`, `valorDesconto` e `valorAquisicao` das URs adicionadas são calculados pela plataforma com a taxa do contrato. Em contratos de **garantia** (`tipoContrato = 2`) **não há deságio** e esses campos não existem.

---

## 🧪 Exemplo de cURL

```bash
curl -X POST 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: 7e1b4c92-2f55-4d0b-9a83-1c6e5d40af73" \
  -H "Content-Type: application/json" \
  -d '{
    "urs": [
      { "idUr": "29E8F0CE-3391-4A65-8091-2331802CEABE", "valorGarantido": 1500.00 },
      { "idUr": "7D121577-3C5A-494D-B052-291D9E100D0D", "valorGarantido": 820.45 }
    ]
  }'
```

---

## 📥 Responses

### ✅ 202 Accepted

```json
{
  "identificadorProcessamento": "A1B2C3D4-1111-2222-3333-444455556666",
  "mensagem": "Solicitação de inclusã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 'urs' é obrigatório e deve conter ao menos um item.",
    "Campo 'valorGarantido' deve ser maior que zero.",
    "A UR já está liquidada e não pode ser adicionada ao contrato.",
    "O valor garantido informado excede o valor livre da UR.",
    "O contrato está cancelado e não aceita novas 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."
  ]
}
```

---

## 🕒 Observações

* O `202 Accepted` indica apenas que a solicitação **passou pelas validações iniciais**. A efetivação do vínculo é informada por webhook.
* O status de cada UR no contrato (`0` = vinculada com sucesso, `1` = falha no vínculo, `2` = em processamento, `3` = pendente extensão, `999` = UR cancelada) chega em [3.2. Atualizações do contrato](../../3.%20Notificações%20-%20WebHook/3.2.%20Atualizações%20do%20contrato.md).
* URs que a registradora ou a plataforma rejeitarem ficam disponíveis para auditoria em [5.10. URs removidas e rejeitadas](5.10.%20URs%20removidas%20e%20rejeitadas.md).
* A composição atualizada do contrato pode ser conferida em [5.3. Detalhes do contrato](5.3.%20Detalhes%20do%20contrato.md).
* Envie sempre o header `Idempotency-Key`: em caso de reenvio, a mesma chave devolve o `identificadorProcessamento` original em vez de duplicar a inclusão.
* Headers obrigatórios e convenções gerais: [1.1. Primeiros Passos](../../1.%20Início/1.1.%20Primeiros%20Passos.md).