> 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/credit-facility/retrieve-repayment-schedules.md).

# Retrieve Repayment Schedules

| Campo              | Valor                                                                     |
| ------------------ | ------------------------------------------------------------------------- |
| **Service Domain** | Credit Facility                                                           |
| **BIAN Version**   | 14.0.0                                                                    |
| **Operation**      | Repayment Schedules Retrieval                                             |
| **Method**         | GET                                                                       |
| **API Name**       | Credit Facility API                                                       |
| **Versão**         | v1.0.0                                                                    |
| **Endpoint**       | `GET /v1/credit-facility/{creditFacilityId}/repayment-schedules/retrieve` |
| **Autenticação**   | Bearer Token (OAuth 2.0 / OIDC)                                           |

***

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

A API de Consulta do Plano Financeiro de Conta de Crédito permite consultar o cronograma de amortização e detalhes financeiros de uma operação de crédito.

Inclui:

* Resumo da operação (capital, juros, duração);
* Detalhes de cada parcela (vencimento, amortização, juros, saldo);
* Parâmetros de taxa (índice, spread, periodicidade);
* Resumos anuais (totais por ano fiscal);
* Links de paginação cursor-based (`self` / `next`).

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`                                                                 |

A API utiliza autenticação baseada em Bearer Token (OAuth2 ou JWT).

***

## 3. Path Parameters

| Parâmetro          | Tipo   | Obrigatório | Descrição                                                                                              |
| ------------------ | ------ | ----------- | ------------------------------------------------------------------------------------------------------ |
| `creditFacilityId` | string | Sim         | Identificador único da operação de crédito. Formato obrigatório: `^[0-9]{13}$` (13 dígitos numéricos). |

***

## 4. Query Parameters

> A paginação desta API é cursor-based, não page-offset. Use o link `next` retornado na resposta para navegar para a próxima página.

| Parâmetro   | Tipo                               | Default                  | Máximo | Descrição                                                                             |
| ----------- | ---------------------------------- | ------------------------ | ------ | ------------------------------------------------------------------------------------- |
| `size`      | integer                            | 50                       | 50     | Número de parcelas por página.                                                        |
| `startDate` | LocalDate (ISO-8601: `AAAA-MM-DD`) | Data do primeiro período | —      | Cursor de posicionamento: retorna parcelas a partir do dia seguinte à data fornecida. |

***

## 5. Payload de Resposta (Response — 200 OK)

A resposta retorna os dados organizados em 4 blocos principais: `creditFacilityArrangement` (Operação de Crédito), `creditFacilityRepayment` (Detalhes Financeiros — incluindo `disbursementInstallments` e `repaymentInstallments`) e `_links` (Controle de Paginação).

```json
{
    "creditFacilityArrangement": {
        "creditFacilityArrangementInstanceReference": "2901473810001",
        "creditFacilityArrangementStatus": "Vencida",
        "creditFacilityPrincipalAmount": -38500000,
        "creditFacilityCurrencyCode": "AKZ",
        "creditFacilityCustomerReference": "ELSA MARIA AZULAY SEQUEIRA B. AUGUSTO",
        "creditFacilityOriginationDate": "2015-01-23",
        "creditFacilityMaturityDate": "2030-01-30",
        "creditFacilityTerm": 180
    },
    "creditFacilityRepayment": {
        "repaymentInstanceReference": "RENDAS",
        "repaymentScheduleSummary": {
            "totalGrossInterest": -307004.4,
            "totalNetInterest": -307004.4,
            "totalTaxes": 0.0,
            "totalOperationAmount": -38807004.4,
            "totalPaidCapital": -38500000,
            "remainingBalance": -23161207.95
        },
        "repaymentRateDetails": {
            "referenceIndex": "RENDAS",
            "spread": 0,
            "nominalRate": 10,
            "dayCountBasis": "Nominal",
            "interestType": "Postecipados",
            "interestFrequency": "Mensal",
            "rateReviewFrequency": "Mensal"
        },
        "disbursementInstallments": [
            {
                "installmentSequence": 1,
                "installmentDueDate": "2026-01-27",
                "principalAmount": 500000,
                "status": "Utilizada"
            }
        ],
        "repaymentInstallments": [
            {
                "installmentSequence": 1,
                "installmentDueDate": "2015-02-24",
                "principalAmount": -96625.6,
                "interestAmount": -307004.4,
                "totalAmount": -403630,
                "remainingBalance": 0,
                "status": "Liquidado",
                "paymentDate": "2015-02-25"
            }
        ],
        "annualSummaries": [
            {
                "year": 2015,
                "totalPrincipal": -96625.6,
                "totalInterest": -307004.4,
                "totalAmount": -403630
            }
        ]
    },
    "_links": {
        "self": {
            "href": "/v1/credit-facility/2901473871001/repayment-schedules/retrieve?size=2"
        },
        "next": {
            "href": "/v1/credit-facility/2901473871001/repayment-schedules/retrieve?size=2&startDate=2015-02-24"
        }
    }
}
```

### 5.1 Objecto: `creditFacilityArrangement`

| Campo                                        | Tipo              | Descrição                                                        |
| -------------------------------------------- | ----------------- | ---------------------------------------------------------------- |
| `creditFacilityArrangementInstanceReference` | string            | Identificador único da operação de crédito.                      |
| `creditFacilityArrangementStatus`            | string            | Estado: `Active`, `Closed`, `Defaulted`, `Suspended`, `Vencida`. |
| `creditFacilityPrincipalAmount`              | decimal           | Capital total da operação (em moeda de origem).                  |
| `creditFacilityCurrencyCode`                 | string (ISO 4217) | Código da moeda (ex: AOA, AKZ, USD).                             |
| `creditFacilityCustomerReference`            | string            | Nome/identificador do cliente.                                   |
| `creditFacilityOriginationDate`              | string (ISO 8601) | Data de contratação.                                             |
| `creditFacilityMaturityDate`                 | string (ISO 8601) | Data de vencimento final.                                        |
| `creditFacilityTerm`                         | integer           | Duração total da operação em meses.                              |

### 5.2 Objecto: `repaymentScheduleSummary`

| Campo                  | Tipo    | Descrição                                           |
| ---------------------- | ------- | --------------------------------------------------- |
| `totalGrossInterest`   | decimal | Total de juros brutos cobrados ao longo do período. |
| `totalNetInterest`     | decimal | Juros líquidos (juros brutos menos impostos).       |
| `totalTaxes`           | decimal | Total de impostos retidos sobre juros.              |
| `totalOperationAmount` | decimal | Montante total a pagar: capital + juros brutos.     |
| `totalPaidCapital`     | decimal | Capital total amortizado.                           |
| `remainingBalance`     | decimal | Saldo devedor remanescente.                         |

### 5.3 Objecto: `repaymentRateDetails`

| Campo                 | Tipo    | Descrição                                                                  |
| --------------------- | ------- | -------------------------------------------------------------------------- |
| `referenceIndex`      | string  | Índice de referência (ex: AD\_SALARIO, Luibor6M, Euribor3M).               |
| `indexValue`          | decimal | Valor actual do índice (%).                                                |
| `spread`              | decimal | Margem cobrada pelo banco sobre o índice (%).                              |
| `nominalRate`         | decimal | Taxa nominal = índice + spread (%).                                        |
| `dayCountBasis`       | string  | Base de contagem de dias: `Actual/360`, `Actual/365`, `30/360`, `Nominal`. |
| `interestType`        | string  | Tipo de taxa: `Fixed`, `Variable`, `Postecipados`.                         |
| `interestFrequency`   | string  | Periodicidade: `Daily`, `Monthly`, `Quarterly`, `Annually`, `Mensal`.      |
| `rateReviewFrequency` | string  | Periodicidade de revisão da taxa.                                          |

### 5.4 Objecto: `disbursementInstallments[]`

| Campo                 | Tipo              | Descrição                                         |
| --------------------- | ----------------- | ------------------------------------------------- |
| `installmentSequence` | integer           | Número sequencial da utilização (1, 2, 3...).     |
| `installmentDueDate`  | string (ISO 8601) | Data de vencimento da utilização.                 |
| `principalAmount`     | decimal           | Valor de amortização de capital nesta utilização. |
| `status`              | string            | Estado da utilização.                             |

### 5.5 Objecto: `repaymentInstallments[]`

| Campo                 | Tipo              | Descrição                                                      |
| --------------------- | ----------------- | -------------------------------------------------------------- |
| `installmentSequence` | integer           | Número sequencial da parcela (1, 2, 3...).                     |
| `installmentDueDate`  | string (ISO 8601) | Data de vencimento. Usado como cursor para a paginação `next`. |
| `principalAmount`     | decimal           | Valor de amortização de capital nesta parcela.                 |
| `interestAmount`      | decimal           | Valor de juros nesta parcela.                                  |
| `totalAmount`         | decimal           | Total a pagar: capital + juros.                                |
| `remainingBalance`    | decimal           | Saldo devedor após esta parcela.                               |
| `status`              | string            | Estado: `Normal`, `Liquidado`.                                 |
| `paymentDate`         | string (ISO 8601) | Data efectiva de pagamento (quando `status = Paid`).           |

### 5.6 Objecto: `annualSummaries[]`

| Campo            | Tipo    | Descrição                            |
| ---------------- | ------- | ------------------------------------ |
| `year`           | integer | Ano fiscal.                          |
| `totalPrincipal` | decimal | Total de capital amortizado no ano.  |
| `totalInterest`  | decimal | Total de juros pagos no ano.         |
| `totalAmount`    | decimal | Total pago no ano (capital + juros). |

### 5.7 Objecto: `_links`

| Campo              | Tipo   | Descrição                                                                   |
| ------------------ | ------ | --------------------------------------------------------------------------- |
| `_links.self.href` | string | URL da página actual, reflecte os parâmetros da chamada.                    |
| `_links.next.href` | string | URL da próxima página. Ausente quando `cpfcsttr = "1"` (sem mais registos). |

> O link `next` usa a `installmentDueDate` do último elemento do array como cursor. Não é necessário calcular a próxima data manualmente — usar directamente o `href` retornado.

***

## 6. Paginação e Fluxo de Navegação

Construção dos links:

* **Self** — reflecte exactamente os parâmetros da chamada actual: `/v1/credit-facility/{creditFacilityId}/repayment-schedules/retrieve?size={size}&date={date}`
* **Next** — usa a `installmentDueDate` do último elemento do array `repaymentInstallments`: `/v1/credit-facility/{creditFacilityId}/repayment-schedules/retrieve?size={size}&date={lastDueDate}`

Fluxo:

1. Chamada inicial — sem parâmetro `date`: `GET /v1/credit-facility/2901473871001/repayment-schedules/retrieve?size=10`
2. Resposta inclui `_links.next` com o cursor do último registo.
3. Chamada seguinte — usar o `href` do `next` directamente: `GET /v1/credit-facility/2901473871001/repayment-schedules/retrieve?size=10&date=2022-12-30`
4. Repetir até `next` estar ausente na resposta.

> **Suporte a Paginação Reversa (Futuro):** por agora a API não suporta link `prev`. A forma recomendada de navegação reversa é o frontend manter um histórico (stack) das dates visitadas. Se no futuro for necessário `prev` no backend, será implementado via cursor Base64 no mesmo padrão.

***

## 7. Códigos HTTP de Resposta

| Código | Estado                | Descrição                                                                                             |
| ------ | --------------------- | ----------------------------------------------------------------------------------------------------- |
| 200    | OK                    | Consulta concluída com sucesso.                                                                       |
| 400    | Bad Request           | `size > 50` ou `creditFacilityId` em formato inválido, ou `creditFacilityId` com menos de 13 dígitos. |
| 401    | Unauthorized          | Bearer Token ausente ou inválido.                                                                     |
| 403    | Forbidden             | Utilizador sem permissão para o crédito solicitado.                                                   |
| 404    | Not Found             | `creditFacilityId` não encontrado.                                                                    |
| 500    | Internal Server Error | Erro no core banking ou falha inesperada.                                                             |

***

## 8. Regras de Negócio

| Regra                           | Detalhe                                                                       |
| ------------------------------- | ----------------------------------------------------------------------------- |
| Validação de `creditFacilityId` | Formato obrigatório: `^[0-9]{13}$` (13 dígitos numéricos).                    |
| Limite de `size`                | Máximo 50 parcelas por página. Valores superiores retornam erro 400.          |
| Filtros temporais               | `fromDate` ≤ `toDate`.                                                        |
| Cursor `date`                   | Internamente convertido: `cpfcdvnc = date + 1 dia` (`startDate.plusDays(1)`). |
| Detecção de próxima página      | `cpfcsttr` vazio/branco = tem mais registos; `"1"` = última página.           |
| Link `next`                     | Usa `installmentDueDate` do último elemento de `repaymentInstallments`.       |
| Autorização granular            | Utilizador só vê créditos que lhe pertencem.                                  |
| Integridade de dados            | Saldo remanescente monotonicamente decrescente.                               |
| Paginação obrigatória           | Máximo 1000 parcelas por página.                                              |

***

## 9. Requisitos Não-Funcionais

| Requisito    | Detalhe                                      |
| ------------ | -------------------------------------------- |
| Bearer Token | Obrigatório com scope `credit:read`.         |
| Logging      | Obrigatório — dados sensíveis nunca em logs. |


---

# 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 current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://selenium-4.gitbook.io/nexus-docs/docs/credit-facility/retrieve-repayment-schedules.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.