> 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/retrieve-schedules/main.md). # Retrieve Merchandising Loan Repayment Schedules | Campo | Valor | | -------------- | ---------------------------------------------------------------------- | | Service Domain | Merchandising Loan | | BIAN Version | 14.0.0 | | Operation | Retrieve Merchandising Loan Repayment Schedules | | Method | GET | | API Name | Merchandising Loan API | | Versão | v1.0.0 | | Endpoint | `GET /v1/merchandising-loan/{merchandisingLoanId}/repayment-schedules` | | Autenticação | Bearer Token (OAuth 2.0 / OIDC — realm nexus) | *** ## 1. Descrição da Operação A operação "Consulta Plano de Pagamento" permite recuperar o plano de amortização completo de uma facilidade de crédito comercial (Merchandising Loan) a partir do seu identificador. A operação: * Devolve todas as prestações do plano de pagamento associadas à facilidade, com os respectivos montantes, datas de vencimento e estados; * Apresenta o valor total da operação (Valor da Operação) e o somatório dos pagamentos registados (Total Pagamentos); * Suporta consulta por número de conta de crédito (`merchandisingLoanId`). *** ## 2. Cabeçalhos HTTP | Cabeçalho | Obrigatório | Descrição | | ------------------------------- | ----------- | --------------------------------------------------------------------- | | `Authorization: Bearer {token}` | Sim | OAuth2 / JWT — client\_credentials para M2M | | `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 de crédito comercial. Corresponde ao número da conta de Crédito. | *** ## 4. Query Parameters | Parâmetro | Tipo | Obrigatório | Default | Descrição | | ----------------- | ------------------- | ----------- | ------- | ----------------------------------------------------------------------------------- | | `repaymentStatus` | string | Não | — | Filtra prestações por estado. Valores possíveis: `normal`, `liquidado` ou `vencido` | | `size` | integer | Não | 50 | Número máximo de prestações a retornar | | `startDate` | string (YYYY-MM-DD) | Não | — | Data de referência para paginação (cursor) | | `afterSequence` | integer | Não | — | Número da prestação a partir da qual continuar a listagem | *** ## 5. Payload de Resposta (Response — 200 OK) ```json { "merchandisingLoanFacilityStatus": "LIQUIDADO", "loanAmount": { "amountValue": 10000, "amountCurrency": { "currencyCode": "EUR" } }, "repaymentSchedules": [ { "installmentSequence": 1, "installmentAmount": { "amountValue": 100, "amountCurrency": { "currencyCode": "EUR" } }, "installmentDueDate": { "dateContent": "2026-05-12" }, "installmentStatus": "LIQUIDADO", "installmentStatusDate": { "dateContent": "2026-05-12" } } ], "totalRepaymentAmount": { "amountValue": 633, "amountCurrency": { "currencyCode": "EUR" } }, "_links": { "self": { "href": "/v1/merchandising-loan/1234567890123/repayment-schedules?size=1" }, "next": { "href": "/v1/merchandising-loan/1234567890123/repayment-schedules?size=1&startDate=2026-05-12&afterSequence=1" } } } ``` ### 5.1. Campos de Topo | Campo | Tipo | Obrigatório | Descrição | | -------------------------------------------------- | ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------ | | `merchandisingLoanFacilityStatus` | enum | Sim | Estado actual da facilidade. Valores: Approved \| Executed \| PartiallyExecuted \| Rejected \| Pending \| Cancelled \| Closed. | | `loanAmount.amountValue` | decimal | Sim | Valor total da operação de crédito aprovada. | | `loanAmount.amountCurrency.currencyCode` | string (ISO 4217) | Sim | Moeda da operação. Exemplos: USD, EUR, AOA. | | `repaymentSchedules[ ]` | array | Sim | Lista de prestações do plano de pagamento. Veja secção 5.2. | | `totalRepaymentAmount.amountValue` | decimal | Sim | Somatório dos montantes de todas as prestações registadas (Total Pagamentos). | | `totalRepaymentAmount.amountCurrency.currencyCode` | string (ISO 4217) | Sim | Moeda do total de pagamentos. | | `_links` | Object | Sim | Links de navegação (self, next) | ### 5.2. Objecto: `repaymentSchedules[ ]` Array de prestações do plano de amortização. Cada entrada representa uma linha do plano tal como apresentado no sistema Banka (AS/400). | Campo | Tipo | Obrigatório | Descrição | | ----------------------------------------------- | ----------------- | ----------- | ------------------------------------------------------------------------------------- | | `installmentSequence` | integer | Sim | Número sequencial da prestação no plano de pagamento. Começa em 1. | | `installmentAmount.amountValue` | decimal | Sim | Montante da prestação. Máximo 2 casas decimais. | | `installmentAmount.amountCurrency.currencyCode` | string (ISO 4217) | Sim | Moeda da prestação. | | `installmentDueDate.dateContent` | string (ISO 8601) | Sim | Data de vencimento da prestação. Formato: YYYY-MM-DD. | | `installmentStatus` | string (1 char) | Sim | Estado da prestação. Valores: N = Normal (por pagar) \| L = Liquidado \| V = Vencido. | | `installmentStatusDate.dateContent` | string (ISO 8601) | Sim | Data associada ao estado da prestação. Formato: YYYY-MM-DD. | ### 5.3. Valores do Campo `installmentStatus` | Valor | Descrição | Observações | | ----- | ----------------------------- | ------------------------------------------------------ | | N | Normal — prestação por pagar | Estado inicial após criação do plano. | | P | Pago — prestação liquidada | Atribuído após execução com sucesso via operação CRDE. | | V | Vencido — prestação em atraso | Data de vencimento ultrapassada sem liquidação. | ### 5.4. Valores do Campo `_links` | Campo | Tipo | Obrigatório | Descrição | | ------------------ | ------ | ----------- | ---------------------------------------------------------- | | `_links.self.href` | string | Sim | URL da própria página atual da consulta. | | `_links.next.href` | string | Não | URL para obter a próxima página de resultados (paginação). | *** ## 6. Códigos HTTP de Resposta | Código | Estado | Descrição | | ------ | --------------------- | ----------------------------------------------------------------------------------- | | 200 | OK | Consulta concluída com sucesso. Lista de prestações devolvida no corpo da resposta. | | 401 | Unauthorized | Token ausente, expirado ou inválido. | | 403 | Forbidden | Cliente autenticado mas sem scope para `merchandising-loan:read`. | | 404 | Not Found | `merchandisingLoanId` inexistente no Banka. | | 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 ```json { "error": { "status": 404, "reason": "RESOURCE_NOT_FOUND", "message": "Facilidade CRDE-2025-000128 não encontrada no Banka.", "path": "GET /v1/merchandising-loan/CRDE-2025-000128/repayment-schedules", "errordetail": [ { "code": "ML-404-001", "reason": "FACILITY_NOT_FOUND", "message": "Nenhuma facilidade encontrada para merchandisingLoanId: CRDE-2025-000128." } ] } } ``` ### 7.1. Estrutura do Envelope de Erro | Campo | Tipo | Obrigatório | Descrição | | ----------------------------- | ------- | ----------- | ----------------------------------------------------------------------- | | `error.status` | integer | Sim | Código HTTP do erro. | | `error.reason` | string | Sim | Código textual de alto nível que identifica a categoria do erro. | | `error.message` | string | Sim | Mensagem legível que descreve o problema ocorrido. | | `error.path` | string | Sim | Método HTTP e caminho do endpoint que originou o erro. | | `error.errordetail[ ]` | array | Não | Lista de erros detalhados. Pode estar ausente em erros genéricos (500). | | `error.errordetail[].code` | string | Não | Código específico do domínio (ex.: ML-404-001). | | `error.errordetail[].reason` | string | Não | Identificador textual da causa específica do erro. | | `error.errordetail[].message` | string | Não | Mensagem detalhada sobre a causa específica. | ### 7.2. Códigos de Erro do Domínio | Código | HTTP | Cenário | | ---------- | ---- | ------------------------------------------------------ | | ML-404-001 | 404 | Facilidade `merchandisingLoanId` inexistente no Banka. | | ML-502-001 | 502 | Banka devolveu return code diferente de zero. | *** ## 8. Requisitos Não-Funcionais | Requisito | Detalhe | | ------------------- | ------------------------------------------------------------------------------ | | HTTPS / TLS | Obrigatório TLS 1.2 ou superior em todas as comunicações. | | Bearer Token | Obrigatório. Pedidos sem token ou com token inválido retornam 401. | | Logging Estruturado | Todos os logs devem incluir o campo `x-request-id` para correlação de pedidos. | --- # 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/merchandising-loan/retrieve-schedules/main.md?ask=&goal= ``` `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.