> 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/service-domain/loan/operacoes/main-1.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) | | **Resposta de Sucesso** | `204 No Content` | *** ## 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 Em caso de sucesso, a resposta é `204 No Content` e não contém corpo. | Código | Estado | Descrição | | ------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 204 | No Content | Detalhes do crédito e plano de amortizações actualizados com sucesso. Nenhum conteúdo é retornado na resposta. | | 400 | Bad Request | Payload inválido (falha de validação dos campos), tipo de parâmetro inválido, ou erro devolvido pelo core bancário sem mapeamento específico (o código original do core é devolvido em `errordetail[].code`). | | 401 | Unauthorized | Token ausente, expirado ou inválido; ou o core bancário rejeitou a operação por falta de autorização (código `$PM1199`). | | 403 | Forbidden | Token válido mas sem permissão para executar esta operação. | | 404 | Not Found | Recurso/rota inexistente, ou o core bancário devolveu o código `GBM5853` (registo não encontrado). | | 409 | Conflict | O core bancário devolveu o código `BKM1063` (conflito com o estado actual do contrato). | | 500 | Internal Server Error | Erro inesperado, ou não foi possível interpretar a resposta de erro do core bancário. | *** ## 6. Envelope Padrão de Erro **Erro de validação (400)** ```json { "status": 400, "reason": "BAD_REQUEST", "message": "Validation failed", "path": "/v1/loans/533610002/update", "errordetail": [ { "code": "Size", "reason": "loanChangeReason.reasonDescription", "message": "size must be between 0 and 40" } ] } ``` **Erro devolvido pelo core bancário (400)** ```json { "status": 400, "reason": "BAD_REQUEST", "message": "Data de vencimento inválida.", "path": "/v1/loans/533610002/update", "errordetail": [ { "code": "BKM0001", "reason": "Something went wrong with the called transaction", "message": "Data de vencimento inválida." } ] } ``` **Erro interno (500)** ```json { "status": 500, "reason": "INTERNAL_SERVER_ERROR", "message": "A server error occurred", "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 | Reason phrase HTTP em maiúsculas (ex.: `BAD_REQUEST`, `UNAUTHORIZED`, `NOT_FOUND`, `CONFLICT`, `INTERNAL_SERVER_ERROR`). | | `message` | string | Mensagem legível que descreve o problema ocorrido. | | `path` | string | Caminho do endpoint que originou o erro (sem o prefixo `/api`). | | `errordetail[]` | array | Lista de erros detalhados. Pode estar vazia ou ausente (ex.: 500). | | `errordetail[].code` | string | Em erros de validação: a regra violada (ex.: `NotNull`, `Size`). Em erros do core bancário: o código original do core (ex.: `$PM1199`, `GBM5853`, `BKM1063`). | | `errordetail[].reason` | string | Em erros de validação: o campo inválido. Em erros do core bancário: descrição genérica ou reason phrase HTTP. | | `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`. |