> 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/merchandising-loan/initiate-repayment-schedules/main.md).

# Initiate Repayment Schedule for Merchandising Loan Facility

| Campo              | Valor                                                       |
| ------------------ | ----------------------------------------------------------- |
| **Service Domain** | Merchandising Loan                                          |
| **BIAN Version**   | 14.0.0                                                      |
| **Operation**      | Initiate Repayment Schedule for Merchandising Loan Facility |
| **Method**         | POST                                                        |
| **API Name**       | Merchandising Loan                                          |
| **Versão**         | v1.0.0                                                      |

***

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

A operação interna "Criação de Plano de Pagamento" materializa a definição de uma nova prestação (parcela) associada a uma facilidade de Merchandising Loan já existente na Banka. Esta operação:

* Cria uma nova entrada na sequência de prestações (repayment schedule) da facilidade, a ser liquidada como se fosse uma parcela de um plano de pagamento;
* Define o montante e a moeda da prestação, bem como a data de vencimento e o tipo de data associado (ex.: vencimento de prestação);
* Não executa qualquer movimento financeiro (débito/crédito), apenas regista o plano de pagamento no core Banka, servindo de base para uma posterior execução (ver operação EXECUTE - Pagamento de Remessa Documentária);
* É associada à facilidade identificada por `merchandisingLoanId`, que deve já existir.

| Campo            | Valor                                                                            |
| ---------------- | -------------------------------------------------------------------------------- |
| **API Name**     | Merchandising Loan API                                                           |
| **Versão**       | v1.0.0                                                                           |
| **Endpoint**     | `POST /v1/merchandising-loan/{merchandisingLoanId}/repayment-schedules/initiate` |
| **Autenticação** | Bearer Token (OAuth 2.0 / OIDC — realm nexus)                                    |

***

## 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-request-id`                   | Recomendado | UUID v4 — identificador único do pedido para correlação em logs/Tempo |
| `x-channel`                      | Recomendado | Canal de origem (SOP, MOBILE, BACKOFFICE, …)                          |

***

## 3. Path Parameters

| Parâmetro             | Tipo   | Obrigatório | Descrição                          |
| --------------------- | ------ | ----------- | ---------------------------------- |
| `merchandisingLoanId` | string | Sim         | Identificador único da facilidade. |

***

## 4. Payload de Pedido (Request)

```json
{
  "merchandisingLoanFacilityRepaymentSchedules": {
    "loanAmount": {
      "amountValue": 800000.00,
      "amountCurrency": {
        "currencyCode": "AKZ"
      }
    },
    "loanMaturityDate": {
      "dateContent": "2026-03-03",
      "dateType": "InstallmentDueDate"
    }
  }
}
```

### 4.1 Objeto Raiz

| Campo                                         | Tipo   | Obrigatório | Descrição                                                                         |
| --------------------------------------------- | ------ | ----------- | --------------------------------------------------------------------------------- |
| `merchandisingLoanFacilityRepaymentSchedules` | object | Sim         | Objecto que agrupa os parâmetros da nova prestação a criar no plano de pagamento. |

### 4.2 Objecto: `merchandisingLoanFacilityRepaymentSchedules`

Agrupa os parâmetros financeiros e temporais da nova prestação: montante, moeda, data de vencimento, tipo de data e tipo de amortização.

| Campo                                    | Tipo              | Obrigatório | Descrição                                                                                                                              |
| ---------------------------------------- | ----------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `loanAmount.amountValue`                 | decimal (>= 0)    | Sim         | Montante da prestação a criar. Máximo 2 casas decimais.                                                                                |
| `loanAmount.amountCurrency.currencyCode` | string (ISO 4217) | Sim         | Código da moeda da prestação. Exemplos: USD, EUR, AKZ. Deve coincidir com a moeda da facilidade, salvo cobertura cambial pré-aprovada. |
| `loanMaturityDate.dateContent`           | string (ISO 8601) | Sim         | Data de vencimento da prestação. Formato: `YYYY-MM-DD`.                                                                                |
| `loanMaturityDate.dateType`              | enum              | Não         | Tipo de data associada à prestação. Valores: `InstallmentDueDate` (vencimento normal de prestação).                                    |

***

## 5. Payload de Resposta (Response — 201 Created)

```json
{
  "merchandisingLoanFacilityRepaymentSchedules": {
    "repaymentSchedulesSequence": 1,
    "repaymentSchedulesStatus": "NORMAL"
  }
}
```

### 5.1 Campos da Resposta

| Campo                        | Tipo    | Descrição                                                                        |
| ---------------------------- | ------- | -------------------------------------------------------------------------------- |
| `repaymentSchedulesSequence` | integer | Número sequencial da prestação no plano de pagamento da facilidade.              |
| `repaymentSchedulesStatus`   | enum    | Estado da prestação após criação. Valores: `NORMAL` \| `LIQUIDADO` \| `VENCIDO`. |

***

## 6. Códigos HTTP de Resposta

| Código | Estado                | Descrição                                                                                                                                                                                    |
| ------ | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 201    | Created               | Prestação criada com sucesso no plano de pagamento.                                                                                                                                          |
| 202    | Accepted              | Pedido aceite; criação assíncrona pendente de confirmação do Banka.                                                                                                                          |
| 400    | Bad Request           | Payload inválido: data de vencimento inconsistente, montante ≤ 0, moeda inválida ou `dateType` não reconhecido.                                                                              |
| 401    | Unauthorized          | Token ausente, expirado ou inválido.                                                                                                                                                         |
| 403    | Forbidden             | Cliente autenticado mas sem scope para `merchandising-loan:repayment-schedules:initiate`.                                                                                                    |
| 404    | Not Found             | `merchandisingLoanId` inexistente.                                                                                                                                                           |
| 409    | Conflict              | Já existe uma prestação com a mesma `loanMaturityDate.dateContent` e `dateType` para esta facilidade.                                                                                        |
| 422    | Unprocessable Entity  | Regra de negócio violada: montante da prestação excede o saldo em dívida, moeda diferente da facilidade sem cobertura cambial, data de vencimento posterior à data final da facilidade, etc. |
| 500    | Internal Server Error | Erro inesperado no NEXUS ou no Backbone.                                                                                                                                                     |
| 502    | Bad Gateway           | Resposta inválida ou indisponibilidade do core Banka.                                                                                                                                        |
| 504    | Gateway Timeout       | Timeout na chamada ao AS/400.                                                                                                                                                                |

***

## 7. Envelope Padrão de Erro

### 7.1 Exemplo

```json
{
  "status": 422,
  "reason": "BUSINESS_RULE_VIOLATION",
  "message": "Montante da prestação excede o saldo em dívida da facilidade.",
  "path": "POST /v1/merchandising-loan/1400000000000/repayment-schedules/initiate",
  "errors": [
    {
      "code": "RS-422-001",
      "reason": "AMOUNT_EXCEEDS_OUTSTANDING_BALANCE",
      "message": "Montante da prestação excede o saldo em dívida da facilidade."
    }
  ]
}
```

### 7.2 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.: `RS-422-001`).                                    |
| `error.errordetail[].reason`  | string  | Identificador textual da causa específica do erro.                                   |
| `error.errordetail[].message` | string  | Mensagem detalhada sobre a causa específica, com valores concretos quando aplicável. |

***

## 8. Regras de Negócio

| # | Regra                   | Detalhe                                                                                                                                    |
| - | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| 1 | Estado da Facilidade    | A facilidade `merchandisingLoanId` deve existir na Banka.                                                                                  |
| 2 | Sequência de Prestações | Cada nova prestação recebe um `repaymentSchedulesSequence` incremental, atribuído automaticamente pelo core.                               |
| 3 | Consistência de Moeda   | A moeda da prestação (`loanAmount.amountCurrency.currencyCode`) deve coincidir com a moeda da facilidade.                                  |
| 4 | Montante Válido         | `loanAmount.amountValue` deve ser maior que zero e a soma de todas as prestações activas não pode exceder o saldo em dívida da facilidade. |
| 5 | Estado Inicial          | Toda a prestação criada com sucesso arranca no estado `NORMAL`.                                                                            |


---

# 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/merchandising-loan/initiate-repayment-schedules/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.