---
title: 4.3. Criar Parcelas da Garantia
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.3.%20Criar%20parcelas%20da%20garantia/
---
# 4.3. Criar Parcelas da Garantia

## 🔗 Endpoint

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

---

## 🧾 Descrição

Cria as parcelas contratuais que servirão como *vínculo de garantia* para a operação. Após o cadastro, um processo assíncrono será disparado para **vincular automaticamente URs** a cada parcela, buscando as melhores URs disponíveis conforme regras de prioridade e prazo.

Não é permitido cadastrar mais de um conjunto de parcelas com o mesmo `contratoErp` para o mesmo contexto (retornará erro de conflito).

---

## 📤 Requisição

### 📋 Payload (JSON)

```json
{
  "contratoErp": "",
  "valorContrato": 0.00,
  "parcelasTotal": 1,
  "parcelas": [
    {
      "numero": 1,
      "data": "2025-01-01",
      "valor": 1.00
    }
  ]
}
```

### 🧾 Detalhamento dos Campos

| Campo         | Tipo    | Obrigatório | Descrição                                                                                                                      |
| ------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| contratoErp   | string  | Sim         | Identificador do contrato no ERP do cliente (único). Não pode haver outro cadastro com o mesmo valor para o mesmo contexto.    |
| valorContrato | number  | Sim         | Valor total do contrato (numérico ≥ 0). Esse valor é esperado ser a soma das parcelas; será replicado no contexto do contrato. |
| parcelasTotal | integer | Sim         | Quantidade total de parcelas (inteiro ≥ 1). Deve corresponder ao tamanho do array `parcelas`.                                  |
| parcelas      | array   | Sim         | Lista de objetos contendo as parcelas. Deve conter pelo menos 1 item.                                                          |
| → numero      | integer | Sim         | Número da parcela (inteiro ≥ 1). Deve ser único dentro do `contratoErp`.                                                       |
| → data        | string  | Sim         | Data alvo de liquidação da parcela, em formato ISO `YYYY-MM-DD`.                                                               |
| → valor       | number  | Sim         | Valor da parcela (numérico > 0).                                                                                               |

**Regras de validação**

* `contratoErp` é obrigatório e único: tentativas de criar outro cadastro com mesmo `contratoErp` devem retornar **409 Conflict**.
* `valorContrato` ≥ 0; preferencialmente igual à soma dos `valor` das parcelas (server pode validar e emitir warning se divergente).
* `parcelasTotal` ≥ 1 e deve ser igual a `parcelas.length`.
* Cada `numero` de parcela deve ser único dentro do mesmo `contratoErp`.
* `data` deve ser uma data válida no formato `YYYY-MM-DD`.
* `valor` deve ser maior que zero.

---

## 🧪 Exemplo de cURL

```bash
curl -X POST https://api.veflow.com/api/v1.1/cartao/agenda/534D8AAE-61E4-4264-9D15-715B9E1F1D51/parcela-garantia \
  -H "Authorization: Bearer {seu_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "contratoErp": "CTR-2025-0001",
    "valorContrato": 10000.00,
    "parcelasTotal": 2,
    "parcelas": [
      { "numero": 1, "data": "2025-09-30", "valor": 5000.00 },
      { "numero": 2, "data": "2025-10-30", "valor": 5000.00 }
    ]
  }'
```

---

## 📥 Responses

### ✅ 200 OK

```json
{
  "mensagem": "Parcelas cadastradas e vínculo automático agendado."
}
```

Indica que as parcelas foram validadas e registradas. O processo de vinculação automática de URs foi agendado e executado de forma assíncrona.

---

### ❌ 400 Bad Request

```json
{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "Campo 'contratoErp' é obrigatório.",
    "parcelasTotal deve ser igual ao número de itens em 'parcelas'.",
    "valor da parcela 2 é inválido: deve ser > 0."
  ]
}
```

---

### ❌ 409 Conflict 

```json
{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Conflito",
  "status": 409,
  "erros": [
    "Já existe um cadastro de parcelas para o contratoErp 'CTR-2025-0001'."
  ]
}
```

---

## 🕒 Observações

* Após o cadastro, a plataforma iniciará um processo que **vinculará automaticamente URs às parcelas** para compor a garantia da melhor forma possível conforme regras de prioridade (menor prazo, maior valor livre, ordenação configurada, etc.).
* Por padrão, a alocação automática de URs considerará URs com data de liquidação **a partir de 5 (cinco) dias úteis antes da data de vencimento** da parcela (ou seja, janela de busca iniciando 5 dias úteis antes da `data` informada). Ajustes nesta regra podem ser parametrizados em configurações do cliente.
* Não é permitido criar múltiplos cadastros com o mesmo `contratoErp` no mesmo contexto (o endpoint retornará `409 Conflict`).
* O sistema valida unicidade dos campos `numero` por `contratoErp` no momento do cadastro.
* A validação da consistência entre `valorContrato` e a soma das `parcelas.valor` pode **bloqueará**  o cadastro por padrão.
* Autenticação obrigatória via `Authorization: Bearer {token}`.