---
title: 7.3. Liquidar Parcela
url: https://docs.vehub.com.br/Emiss%C3%A3o%20de%20Ativos/API/Cr%C3%A9dito/7.%20Contratos%20e%20Parcelas/7.3.%20Liquidar%20Parcela/
---
# 7.3. Liquidar Parcela

!!! warning "Especificação — em construção"
    Os serviços descritos nesta área ainda não estão disponíveis.

## 🔗 Endpoint

| Método | URL |
|--------|-----|
| ![PATCH](https://img.shields.io/badge/PATCH-yellow) | `/credito/contratos/{idContrato}/parcelas/{idParcela}` |

---

## 🧾 Descrição

Registra o **pagamento de uma parcela**. É o serviço que mantém a carteira correta quando a cobrança é
feita fora da plataforma.

!!! important "Sempre disponível, independente da forma de cobrança"
    Diferente da [geração de cobrança](7.4.%20Cobrança.md), que depende do parâmetro
    `cobrancaExterna` da esteira, a liquidação **está sempre disponível**. Não importa se o boleto foi
    emitido pela plataforma, por você, ou se o cliente pagou por PIX, transferência ou em espécie: a
    liquidação é como você informa que a parcela foi paga.

    Isso é essencial porque **não há baixa automática por conciliação bancária**. Sem esta chamada, o
    contrato nunca é liquidado.

### 🔹 Path Parameters

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| idContrato | integer | Identificador do contrato |
| idParcela | integer | Identificador da parcela, obtido em [7.2](7.2.%20Parcelas%20e%20Saldo.md) |

### 🔹 Headers

Use **`Idempotency-Key`**. Sem ela, um *retry* pode registrar o pagamento duas vezes.

---

## 📤 Requisição

```json
{
  "dataPagamento": "2026-10-13",
  "valorPagamento": 850.00,
  "valorMulta": 0.00,
  "valorMora": 0.00,
  "valorDesconto": 0.00
}
```

### 🧾 Detalhamento dos Campos

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| dataPagamento | string | Sim | Data em que o pagamento ocorreu (`YYYY-MM-DD`). Não pode ser futura |
| valorPagamento | number | Sim | Valor efetivamente recebido |
| valorMulta | number | Não | Multa cobrada por atraso. `0` quando não houver |
| valorMora | number | Não | Juros de mora cobrados. `0` quando não houver |
| valorDesconto | number | Não | Desconto concedido. `0` quando não houver |

> Para saber quanto cobrar numa data — com encargos ou desconto — consulte antes
> `POST /credito/contratos/{idContrato}/parcelas/valores` em
> [7.2. Parcelas e Saldo](7.2.%20Parcelas%20e%20Saldo.md).

---

## 🧪 Exemplo de cURL

```bash
curl -X PATCH "https://api.vehub.com.br/credito/contratos/5001/parcelas/8801" \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -H "Idempotency-Key: f2a1c8d4-3e56-4b90-a7c2-118e5d0b6934" \
  -H "Content-Type: application/json" \
  -d '{
    "dataPagamento": "2026-10-13",
    "valorPagamento": 850.00
  }'
```

---

## 📥 Responses

### ✅ 200 OK

```json
{
  "sucesso": true,
  "mensagem": "Parcela liquidada com sucesso.",
  "dados": {
    "idParcela": 8801,
    "numero": 1,
    "status": { "id": 2, "nome": "Paga" },
    "dataPagamento": "2026-10-13",
    "valorPagamento": 850.00,
    "contratoLiquidado": false
  }
}
```

| Campo | Tipo | Descrição |
|-------|------|-----------|
| status | object | Novo status da parcela |
| contratoLiquidado | boolean | `true` quando esta era a última parcela em aberto |

### ❌ 409 Conflict — parcela já liquidada

```json
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "status": 409,
  "errors": [
    { "campo": null, "mensagem": "A parcela já está liquidada. Data do pagamento: 2026-10-13." }
  ]
}
```

### ❌ 400 Bad Request

```json
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "status": 400,
  "errors": [
    { "campo": "dataPagamento", "mensagem": "Não pode ser uma data futura." },
    { "campo": "valorPagamento", "mensagem": "Deve ser maior que zero." }
  ]
}
```

---

## 🔔 Eventos disparados

| Evento | Quando |
|---|---|
| `credito.parcela.liquidada` | Sempre, ao liquidar a parcela |
| `credito.contrato.liquidado` | Adicionalmente, quando era a última parcela em aberto |

Ver [8.5. Eventos de Parcela](../8.%20Notificações%20-%20WebHook/8.5.%20Eventos%20de%20Parcela.md).

---

## 🧭 Fluxo de conciliação

```mermaid
flowchart TD
    A[GET /credito/parcelas<br/>filtrando o período] --> B[Conciliar com os<br/>recebimentos da sua base]
    B --> C{Parcela recebida?}
    C -- Não --> D[Aguardar]
    C -- Sim --> E[POST parcelas/valores<br/>para conferir o valor na data]
    E --> F[PATCH parcelas/id<br/>informando o pagamento]
    F --> G[Webhook<br/>credito.parcela.liquidada]
```

---

## ⚠️ Observações

- A liquidação está **disponível a qualquer credencial pública**. É a operação que fecha a dívida —
  trate o acesso a ela, no seu lado, com o mesmo cuidado que trataria uma baixa financeira.
- Liquidação **parcial não é suportada**: informar `valorPagamento` menor que o devido não deixa a
  parcela parcialmente aberta. Se o cliente pagou menos, negocie e use
  [7.4. Cobrança](7.4.%20Cobrança.md) com liquidação e desconto.
- Não há operação de **estorno** por API. Uma liquidação registrada por engano precisa ser corrigida
  pelo time de operações na plataforma.