> 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/term-deposit/operacoes/main-3.md). # Initiate Term Deposit Operation | Campo | Valor | | -------------- | ---------------------------- | | Service Domain | Term Deposit | | BIAN Version | 14.0.0 | | Operation | Initiate Deposit Transaction | | Method | PUT | | API Name | Term Deposit Management API | | Versão | v1.0.0 | ## 1. Descrição da Operação O serviço de Inicialização de Transacção de Reforço (Deposit) permite reforçar o montante de uma conta de depósito a prazo, com débito do valor numa conta à ordem de origem indicada no corpo do pedido. A operação recebe a conta pagadora, a descrição e o montante do reforço, criando um novo registo de transacção associado à conta de depósito a prazo. O pedido pode ser processado de imediato ou ficar sujeito a diferimento. | Campo | Valor | | ------------ | ------------------------------------------------------------------------------ | | API Name | Term Deposit Management API | | Versão | v1.0.0 | | Endpoint | PUT /v1/term-deposit/{termDepositAccountId}/deposit/{currentAccountId}/execute | | Autenticação | Bearer Token (OAuth 2.0 / OIDC) | ## 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-channel | Recomendado | Canal de origem (SOP, MOBILE, BACKOFFICE, …) | ## 3. Parâmetros ### 3.1 Path Parameters | Parâmetro | Tipo | Obrigatório | Descrição | | ------------- | ------ | ----------- | ----------------------------------------------------------------------- | | termDepositId | string | Sim | Identificador único da conta de depósito a prazo (Conta DP) a reforçar. | ## 4. Payload de Requisição (Request Body) ### 4.1 Exemplo ```json { "termDepositPayerAccountReference": { "accountIdentification": { "accountIdentificationType": "BBAN", "accountIdentification": { "identifierValue": "000123456789" } }, "accountType": "CurrentAccount" }, "depositTransactionDescription": "Reforço do depósito a prazo 000555666777", "termDepositAmount": { "amountValue": 1000000.00, "amountCurrency": { "currencyCode": "AKZ" }, "amountType": "AdditionalDepositAmount" } } ``` ### 4.2 Campos da Requisição | Campo | Tipo | Obrigatório | Descrição | | -------------------------------------------------------------------------------------------- | ------ | ----------- | ---------------------------------------------------------------------------- | | termDepositPayerAccountReference | object | Não | Conta à ordem de onde é debitado o montante do reforço. | | termDepositPayerAccountReference.accountIdentification.accountIdentificationType | string | Não | Tipo de identificador de conta (ex: `BBAN`). | | termDepositPayerAccountReference.accountIdentification.accountIdentification.identifierValue | string | Sim | Número/identificador da conta pagadora. | | termDepositPayerAccountReference.accountType | string | Não | Tipo de conta pagadora (ex: `CurrentAccount`). | | depositTransactionDescription | string | Não | Descrição/observações livres associadas ao reforço (ex: motivo, referência). | | termDepositAmount.amountValue | number | Sim | Montante a reforçar na conta de depósito a prazo. | | termDepositAmount.amountCurrency.currencyCode | string | Sim | Código da moeda do montante (ISO 4217, ex: `AKZ`). | | termDepositAmount.amountType | string | Sim | Tipo de montante (`AdditionalDepositAmount`). | ## 5. Payload de Resposta (Response - 200 OK) ### 5.1 Exemplo — pedido processado de imediato (`Confirmed`) ```json { "depositTransactionReference": "TSX-00123", "depositTransactionIdentification": null, "depositTransactionStatus": { "statusReason": "Confirmed" } } ``` ### 5.2 Exemplo — pedido sujeito a diferimento (`Initiated`) ```json { "depositTransactionReference": "TSX-00123", "depositTransactionIdentification": { "identifierValue": "P00132" }, "depositTransactionStatus": { "statusReason": "Initiated" } } ``` ### 5.3 Campos da Resposta | Campo | Tipo | Descrição | | ------------------------------------------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | depositTransactionReference | string | Referência única atribuída à transacção de reforço criada. | | depositTransactionIdentification | object \| null | String de diferimento. Só é devolvida (não-nula) quando `depositTransactionStatus.statusReason = "Initiated"`, ou seja, quando o pedido fica sujeito a diferimento. Quando o pedido é confirmado de imediato (`Confirmed`), este campo é devolvido como `null`. | | depositTransactionIdentification.identifierValue | string | Identificador da string de diferimento (apenas presente quando aplicável). | | depositTransactionStatus.statusReason | string | Estado do pedido de reforço. `Confirmed` quando o reforço é processado de imediato; `Initiated` quando o pedido fica sujeito a diferimento (aguarda processamento). | ## 6. Códigos HTTP de Resposta | Código | Estado | Descrição | | ------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------- | | 200 | OK | Transacção de reforço iniciada com sucesso. | | 400 | Bad Request | Parâmetros inválidos ou em falta (ex: montante não indicado ou inválido), ou saldo insuficiente na conta à ordem de origem. | | 401 | Unauthorized | Token ausente, expirado ou inválido. | | 404 | Not Found | Conta de depósito a prazo ou conta pagadora não encontrada para os identificadores indicados. | | 500 | Internal Server Error | Erro inesperado no sistema. | | 502 | Bad Gateway | Resposta inválida ou indisponibilidade do serviço. | | 504 | Gateway Timeout | Timeout na chamada do serviço. | ## 7. Envelope Padrão de Erro ```json { "status": 400, "reason": "BAD_REQUEST", "message": "Saldo insuficiente na conta à ordem de origem para o montante solicitado.", "path": "/v1/term-deposit/901966920/initate", "errors": [ { "code": "TD-400-002", "reason": "INSUFFICIENT_BALANCE", "message": "Saldo insuficiente na conta '000123456789' para o montante solicitado." } ] } ``` ### 7.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. | | message | string | Mensagem legível que descreve o problema ocorrido. | | path | string | Caminho do endpoint que originou o erro. | | errors\[] | array | Lista de erros detalhados. Pode estar ausente em erros genéricos (500). | | errors\[].code | string | Código específico do domínio (ex: TD-400-002). | | errors\[].reason | string | Identificador textual da causa específica do erro. | | errors\[].message | string | Mensagem detalhada com valores concretos quando aplicável. | ## 8. Regras de Negócio | # | Regra | Detalhe | | - | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Conta DP Válida | O termDepositId deve corresponder a uma conta de depósito a prazo activa e existente no sistema. | | 2 | Conta Pagadora Válida | A `termDepositPayerAccountReference` deve corresponder a uma conta à ordem activa e existente no sistema, com saldo suficiente para o montante do reforço. | | 3 | Moeda | A moeda do `termDepositAmount` deve corresponder à moeda da conta de depósito a prazo a reforçar. | | 4 | Diferimento | O pedido de reforço pode ser processado de imediato (`Confirmed`) ou ficar sujeito a diferimento (`Initiated`), consoante as regras do sistema; `depositTransactionIdentification` só é devolvido com valor quando o estado é `Initiated`. | ## 9. 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. | | Auditoria | Registo persistente obrigatório de todas as operações de reforço (log estruturado). |