> For the complete documentation index, see [llms.txt](https://selenium-4.gitbook.io/nexus-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://selenium-4.gitbook.io/nexus-docs/docs/loan/initiate/main.md).

# Execute Loan Settlement (Partial / Total)

| Campo              | Valor                                     |
| ------------------ | ----------------------------------------- |
| **Service Domain** | Loan                                      |
| **BIAN Version**   | 14.0.0                                    |
| **Operation**      | Execute Loan Settlement (Partial / Total) |
| **Method**         | POST                                      |
| **API Name**       | Loan API                                  |
| **Versão**         | v1.0.0                                    |

***

## 1. Descrição da Operação

O serviço de Liquidação de Crédito permite a liquidação de um empréstimo, de forma **Parcial** ou **Total**, através de dois endpoints distintos:

* **Liquidação Parcial**: o cliente efetua um pagamento extraordinário que reduz o capital em dívida, podendo encurtar o prazo ou reduzir prestações futuras.
* **Liquidação Total**: o cliente quita integralmente o empréstimo, encerrando o contrato de crédito.

A operação:

* Suporta os tipos `PARCIAL` e `TOTAL` através do campo `settlementType` no payload.

| Campo                                          | Valor                                        |
| ---------------------------------------------- | -------------------------------------------- |
| **API Name**                                   | Loan API                                     |
| **Versão**                                     | v1.0.0                                       |
| **Endpoint para Liquidação (Parcial / Total)** | `POST /v1/loans/{loanId}/settlement/execute` |
| **Autenticação**                               | Bearer Token (OAuth 2.0 / OIDC)              |

***

## 2. Cabeçalhos HTTP

| Header                           | Obrigatório | Notas                                        |
| -------------------------------- | ----------- | -------------------------------------------- |
| `Authorization: Bearer {token}`  | Sim         | OAuth2 / JWT `client_credentials` para M2M   |
| `Content-Type: application/json` | Sim         |                                              |
| `Accept: application/json`       | Sim         |                                              |
| `x-channel`                      | Recomendado | Canal de origem (SOP, MOBILE, BACKOFFICE, …) |

***

## 3. Path Parameters

| Parâmetro | Tipo   | Obrigatório | Endpoint        | Descrição                                   |
| --------- | ------ | ----------- | --------------- | ------------------------------------------- |
| `loanId`  | string | Sim         | Parcial e Total | Identificador único do contrato de crédito. |

***

## 4. Payload de Pedido (Request)

```json
{
  "settlementType": "VALUE",
  "settlementInstallment": {
    "installmentSequence": 1
  },
  "settlementAmount": {
    "amountValue": 50000.00,
    "amountCurrency": {
      "currencyCode": "AKZ"
    }
  },
  "settlementDate": "2026-06-15",
  "accountIdentification": {
    "accountIdentificationType": "DebitAccount",
    "accountDescription": "Conta de débito para regularização",
    "identifierValue": "125818816001"
  }
}
```

### 4.3 Objecto Raiz

| Campo                                          | Tipo              | Obrigatório | Descrição                                                                                                                                                                                                                                                                                                                                              |
| ---------------------------------------------- | ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `settlementType`                               | enum              | Sim         | Tipo de liquidação. Valores: `PARTIAL` \| `TOTAL`.                                                                                                                                                                                                                                                                                                     |
| `installmentSequence`                          | integer           | Sim         | Obrigatório para Liquidação Parcial                                                                                                                                                                                                                                                                                                                    |
| `settlementAmount.amountValue`                 | decimal (>= 0)    | Sim         | O valor 0 indica que deve ser regularizado o montante total em dívida. Para liquidação TOTAL, deve corresponder ao valor total em dívida. Para liquidação PARCIAL, permite indicar um montante inferior ao valor em dívida, sendo regularizada apenas a parcela correspondente ao valor informado (ou ser informado como 0 para liquidar toda dívida). |
| `settlementAmount.amountCurrency.currencyCode` | string (ISO 4217) | Sim         | Código de moeda. Exemplos: AKZ, USD, EUR. Deve coincidir com a moeda do contrato.                                                                                                                                                                                                                                                                      |
| `settlementDate`                               | string (ISO 8601) | Sim         | Data efectiva da liquidação. Formato: `YYYY-MM-DD`.                                                                                                                                                                                                                                                                                                    |

### 4.4 Objecto: `accountIdentification`

| Campo                       | Tipo   | Obrigatório | Descrição                                     |
| --------------------------- | ------ | ----------- | --------------------------------------------- |
| `accountIdentificationType` | enum   | Não         | Papel da conta. Valores                       |
| `accountDescription`        | string | Não         | Texto descritivo. Apenas informativo.         |
| `identifierValue`           | string | Sim         | Número da conta onde será efectuado o débito. |

***

## 5. Payload de Resposta (Response 204) - NoContent

***

## 6. Códigos HTTP de Resposta

| Código | Estado                | Descrição                                                                                             |
| ------ | --------------------- | ----------------------------------------------------------------------------------------------------- |
| 200    | OK                    | Liquidação executada com sucesso.                                                                     |
| 204    | No-Content            | Parcela liquidada com sucesso. Nenhum conteúdo é retornado na resposta.                               |
| 202    | Accepted              | Pedido aceite; execução assíncrona pendente de confirmação do core bancário.                          |
| 400    | Bad Request           | Payload inválido: datas inconsistentes, montante ≤ 0, moeda inválida ou contas em falta.              |
| 401    | Unauthorized          | Token ausente, expirado ou inválido.                                                                  |
| 403    | Forbidden             | Cliente autenticado mas sem scope para `loans:settlement:execute`.                                    |
| 404    | Not Found             | `loanId` inexistente ou contas de pagamento/despesas não encontradas.                                 |
| 409    | Conflict              | Contrato já liquidado anteriormente ou em estado terminal (Cancelled, Closed).                        |
| 422    | Unprocessable Entity  | Regra de negócio violada: saldo insuficiente, moeda divergente, montante excede saldo em dívida, etc. |
| 500    | Internal Server Error | Erro inesperado no sistema.                                                                           |
| 502    | Bad Gateway           | Resposta inválida ou indisponibilidade do core bancário.                                              |
| 504    | Gateway Timeout       | Timeout na chamada ao core bancário.                                                                  |

***

## 7. Envelope Padrão de Erro

```json
{
    "status": 422,
    "reason": "BUSINESS_RULE_VIOLATION",
    "message": "Saldo insuficiente na conta de despesas para liquidar comissões.",
    "path": "/v1/loans/LN-2025-000128/settlement/execute",
    "errordetail": [
      {
        "code": "LN-422-001",
        "reason": "INSUFFICIENT_FUNDS_EXPENSE_ACCOUNT",
        "message": "Conta 125818810007: saldo 850.00 AKZ < despesa 1250.75 AKZ."
      }
    ]
}
```

### 7.1 Estrutura do Envelope de Erro

| Campo                         | Tipo    | Descrição                                                               |
| ----------------------------- | ------- | ----------------------------------------------------------------------- |
| `error.status`                | integer | Código HTTP do erro.                                                    |
| `error.reason`                | string  | Código textual de alto nível que identifica a categoria do erro.        |
| `error.message`               | string  | Mensagem legível que descreve o problema ocorrido.                      |
| `error.path`                  | string  | Método HTTP e caminho do endpoint que originou o erro.                  |
| `error.errordetail[]`         | array   | Lista de erros detalhados. Pode estar ausente em erros genéricos (500). |
| `error.errordetail[].code`    | string  | Código específico do domínio (ex.: LN-422-001).                         |
| `error.errordetail[].reason`  | string  | Identificador textual da causa específica do erro.                      |
| `error.errordetail[].message` | string  | Mensagem detalhada com valores concretos quando aplicável.              |

***

## 8. Regras de Negócio

| # | Regra                           | Detalhe                                                                                                                                                    |
| - | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | Estado do Contrato              | O contrato `loanId` deve existir e estar em estado `Approved` ou `Active`. Qualquer outro estado resulta em erro 409.                                      |
| 2 | Contas Obrigatórias             | Devem ser fornecidas exactamente uma `PaymentAccount` e uma `ExpenseAccount`, ambas activas e pertencentes ao titular do contrato.                         |
| 3 | Consistência de Moeda           | A moeda da conta de pagamento deve coincidir com `amountCurrency.currencyCode`, ou deve existir cobertura cambial pré-aprovada.                            |
| 4 | Montante Válido                 | `amountValue` deve ser maior que zero. Para `PARTIAL`, não pode exceder o saldo em dívida. Para `TOTAL`, deve corresponder exactamente ao saldo em dívida. |
| 5 | Saldo da Conta de Despesas      | A conta de despesas deve ter saldo suficiente para cobrir comissões, imposto de selo e encargos calculados no momento da execução.                         |
| 6 | Protecção contra Dupla Execução | Antes de processar, o serviço verifica o estado do contrato. Se já estiver `Executed`...                                                                   |

***

## 9. Requisitos Não-Funcionais

| Requisito    | Detalhe                                                                                               |
| ------------ | ----------------------------------------------------------------------------------------------------- |
| HTTPS / TLS  | Obrigatório TLS 1.2 ou superior em todas as comunicações.                                             |
| Bearer Token | Obrigatório — scope `loans:settlement:execute`. Pedidos sem token ou com token inválido retornam 401. |
| Auditoria    | Registo persistente obrigatório de todas as execuções (log estruturado).                              |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://selenium-4.gitbook.io/nexus-docs/docs/loan/initiate/main.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.