> 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/update-loan-details-and-repayment-schedule/main.md).

# Update Loan Details

| Campo              | Valor                           |
| ------------------ | ------------------------------- |
| **Service Domain** | Loan                            |
| **BIAN Version**   | 14.0.0                          |
| **Operation**      | Update Loan Details             |
| **Method**         | PUT                             |
| **API Name**       | Loan                            |
| **Versão**         | v1.0.0                          |
| **Endpoint**       | `PUT /v1/loans/{loanId}/update` |
| **Autenticação**   | Bearer Token (OAuth 2.0 / OIDC) |

***

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

O serviço de Alteração de Detalhes da Conta de Crédito e Plano Financeiro permite efectuar a atualização dos elementos de uma conta de crédito e recalcular o plano de amortizações e juros.

Elementos da conta de crédito que podem ser actualizados:

* O montante do crédito concedido (capital);
* Data de vencimento do crédito;
* A periodicidade da cobrança das amortizações/juros (Mensal, Diário, Anual, etc.);
* Data de Início e Fim das Prestações;
* Motivo da alteração.

Esta API é usada principalmente por sistemas internos, parceiros integradores, portais de cliente e sistemas de reporte financeiro.

***

## 2. Cabeçalhos HTTP

| Header          | Tipo   | Obrigatório | Descrição                                                                          |
| --------------- | ------ | ----------- | ---------------------------------------------------------------------------------- |
| `Authorization` | String | Sim         | Bearer Token. Ex.: `Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...` |
| `Content-Type`  | String | Sim         | `application/json`                                                                 |
| `Accept`        | String | Sim         | `application/json`                                                                 |

Este serviço utiliza autenticação baseada em Bearer Token (OAuth2 ou JWT).

***

## 3. Path Parameters

| Parâmetro | Tipo de Dado | Obrigatório | Descrição                                |
| --------- | ------------ | ----------- | ---------------------------------------- |
| `loanId`  | String       | Sim         | Representa o Número da Conta de Crédito. |

***

## 4. Payload de Pedido (Request)

### 4.1 Exemplo

```json
{
  "loanAmount": {
    "amountValue": 500000.00,
    "amountCurrency": {
      "CurrencyCode": "AKZ"
    },
    "amountType": "LoanPrincipal"
  },
  "loanMaturityDate": {
    "dateContent": "2026-05-30"
  },
  "loanRepaymentSchedule": {
    "repaymentScheduleFrequency": "Monthly",
    "repaymentScheduleFrequencyCode": "M",
    "repaymentScheduleCount": 21,
    "repaymentSchedulePeriod": {
      "fromDate": {
        "dateContent": "2026-04-27",
        "dateType": "RepaymentStartDate"
      },
      "toDate": {
        "dateContent": "2028-11-30",
        "dateType": "RepaymentEndDate"
      }
    }
  },
  "loanChangeReason": {
    "reasonCode": "P",
    "reasonDescription": "Reescalonamento do plano de pagamento."
  }
}
```

### 4.2 Objecto: `loanAmount`

| Campo                         | Tipo   | Descrição                                             |
| ----------------------------- | ------ | ----------------------------------------------------- |
| `amountValue`                 | Number | Capital total do crédito.                             |
| `amountCurrency.CurrencyCode` | String | A moeda da conta de crédito (relacionada ao capital). |
| `amountType`                  | String | O tipo de montante (defeito: `LoanPrincipal`).        |

### 4.3 Objecto: `loanMaturityDate`

| Campo         | Tipo   | Descrição                                             |
| ------------- | ------ | ----------------------------------------------------- |
| `dateContent` | String | Nova data de vencimento do crédito a ser actualizado. |

### 4.4 Objecto: `loanRepaymentSchedule`

| Campo                            | Tipo    | Descrição                                                                                                             |
| -------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `repaymentScheduleFrequency`     | String  | Descrição do tipo de periodicidade das rendas de crédito (ver tabela de [Periodicidades](#46-tabelas-de-referência)). |
| `repaymentScheduleFrequencyCode` | String  | Código do tipo de periodicidade das rendas de crédito (ver tabela de [Periodicidades](#46-tabelas-de-referência)).    |
| `repaymentScheduleCount`         | Integer | Número total das rendas (inclui amortizações e juros).                                                                |

### 4.5 Objecto: `repaymentSchedulePeriod`

| Campo                  | Tipo   | Descrição                             |
| ---------------------- | ------ | ------------------------------------- |
| `fromDate.dateContent` | String | Data de início das rendas (ISO-8601). |
| `fromDate.dateType`    | String | O tipo de data de início das rendas.  |
| `toDate.dateContent`   | String | Data de fim das rendas (ISO-8601).    |
| `toDate.dateType`      | String | O tipo de data de fim das rendas.     |

### Objecto: `loanChangeReason`

| Campo               | Tipo   | Descrição                                                                                         |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------- |
| `reasonCode`        | String | Código do motivo da actualização (ver tabela de [Códigos de Motivos](#46-tabelas-de-referência)). |
| `reasonDescription` | String | Observação da atualização do crédito (máx. 40 caracteres).                                        |

### 4.6 Tabelas de Referência

**Periodicidades**

| Nome          | Código |
| ------------- | ------ |
| Mensal        | M      |
| Quinzenal     | Q      |
| Quadrimestral | R      |
| Semestral     | S      |
| Trimestral    | T      |
| Fim de mês    | U      |
| Semanal       | W      |
| Anual         | Y      |
| Fim Trimestre | F      |
| Fim Semestre  | G      |
| Bimestral     | I      |

**Códigos de Motivos**

| Código | Descrição          |
| ------ | ------------------ |
| P      | Prorrogação        |
| V      | Alteração de prazo |

***

## 5. Códigos HTTP de Resposta

| Código | Estado                                  | Descrição                                                                                                            |
| ------ | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| 400    | Bad Request (`INVALID_VALUE`)           | Valor inválido no pedido (ex.: `Invalid Srci-Client Id`).                                                            |
| 500    | Internal Server Error (`INVALID_STATE`) | Erro interno do servidor. Tipicamente um erro (bug) do servidor; o cliente deve reportar o erro à equipa de suporte. |

***

## 6. Envelope Padrão de Erro

**Estrutura de Erro**

```json
{
    "status": 400,
    "reason": "INVALID_VALUE",
    "message": "Invalid Srci-Client Id",
    "path": "/v1/loans/533610002/update",
    "errordetail": [
      {
        "code": "123332",
        "reason": "INVALID_VALUE",
        "message": "Invalid Srci-Client Id"
      }
    ]
}
```

**Erro Internal**

```json
{
    "status": 500,
    "reason": "INVALID_STATE",
    "message": "Internal server error. Typically a server bug. The client should report this error to the Mastercard support team",
    "path": "/v1/loans/533610002/update"
}
```

### 6.1 Estrutura do Envelope de Erro

| Campo                   | Tipo    | Descrição                                                                                                |
| ----------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `status`                | integer | Código HTTP do erro.                                                                                     |
| `reason`                | string  | Código textual de alto nível que identifica a categoria do erro (ex.: `INVALID_VALUE`, `INVALID_STATE`). |
| `message`               | string  | Mensagem legível que descreve o problema ocorrido.                                                       |
| `path`                  | string  | Caminho do endpoint que originou o erro.                                                                 |
| `errordetail[]`         | array   | Lista de erros detalhados. Pode estar ausente em erros genéricos (ex.: 500).                             |
| `errordetail[].code`    | string  | Código do erro.                                                                                          |
| `errordetail[].reason`  | string  | Identificador textual da causa específica do erro.                                                       |
| `errordetail[].message` | string  | Mensagem detalhada do erro.                                                                              |

***

## 7. Regras de Negócio

| Regra                              | Detalhe                                                                                                                                                                                                                                                        |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Comprimento de `reasonDescription` | Máximo de 40 caracteres.                                                                                                                                                                                                                                       |
| Periodicidade                      | `repaymentScheduleFrequency` / `repaymentScheduleFrequencyCode` devem corresponder a um dos valores da tabela de Periodicidades (Mensal, Quinzenal, Quadrimestral, Semestral, Trimestral, Fim de mês, Semanal, Anual, Fim Trimestre, Fim Semestre, Bimestral). |
| Motivo da Alteração                | `reasonCode` deve corresponder a um dos valores da tabela de Códigos de Motivos (`P` — Prorrogação, `V` — Alteração de prazo).                                                                                                                                 |
| Tipo de Montante                   | `amountType` por defeito é `LoanPrincipal`.                                                                                                                                                                                                                    |


---

# 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/update-loan-details-and-repayment-schedule/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.