> 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/term-deposit/main-2.md). # Initialize withdrawal transaction | Campo | Valor | | -------------- | ------------------------------- | | Service Domain | Term Deposit | | BIAN Version | 14.0.0 | | Operation | Initiate Withdrawal Transaction | | Method | POST | | 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 Mobilização (Withdrawal) permite iniciar o levantamento/mobilização de fundos de uma conta de depósito a prazo, total ou parcial, com crédito do valor numa conta de destino indicada no pedido. A operação recebe a data da mobilização, o montante, a conta de destino e a descrição, criando um novo registo de transacção de mobilizaçã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 | POST /v1/term-deposit/{termDepositId}/debitand-credit/initiate | | 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 mobilizar. | ## 4. Payload de Requisição (Request Body) ### 4.1 Exemplo ```json { "withdrawalTransactionDate": { "dateContent": "2026-09-16", "dateType": "ValueDate" }, "withdrawalTransactionAmount": { "amountValue": 1000000.00, "amountCurrency": { "currencyCode": "AOA" }, "amountType": "Principal" }, "withdrawalTransaction": { "financialTransactionTargetAccount": { "accountIdentification": { "accountIdentificationType": "BBAN", "accountIdentification": { "identifierValue": "000123456789" } }, "accountType": "CurrentAccount" } }, "withdrawalTransactionDescription": "Mobilização total do depósito a prazo" } ``` ### 4.2 Campos da Requisição | Campo | Tipo | Obrigatório | Descrição | | ------------------------------------------------------------------------------------------------------------------- | ----------------- | ----------- | ------------------------------------------------------------------------------- | | withdrawalTransactionDate | object | Sim | Data em que a mobilização deve ser efectuada. | | withdrawalTransactionDate.dateContent | string (ISO 8601) | Sim | Data da mobilização. | | withdrawalTransactionDate.dateType | string | Sim | Tipo de data (`ValueDate`). | | withdrawalTransactionAmount | object | Sim | Montante a mobilizar/levantar do depósito a prazo. | | withdrawalTransactionAmount.amountValue | number | Sim | Valor do montante a mobilizar. | | withdrawalTransactionAmount.amountCurrency.currencyCode | string | Sim | Código da moeda do montante (ISO 4217, ex: `AOA`). | | withdrawalTransactionAmount.amountType | string | Sim | Tipo de montante (`Principal`). | | withdrawalTransaction | object | Sim | Objecto com os dados da conta de destino da mobilização. | | withdrawalTransaction.financialTransactionTargetAccount | object | Sim | Conta de destino (DO) para onde é transferido o valor da mobilização. | | withdrawalTransaction.financialTransactionTargetAccount.accountIdentification.accountIdentificationType | string | Sim | Tipo de identificação da conta de destino (ex: `BBAN`). | | withdrawalTransaction.financialTransactionTargetAccount.accountIdentification.accountIdentification.identifierValue | string | Sim | Número da conta de destino onde o valor da mobilização será creditado. | | withdrawalTransaction.financialTransactionTargetAccount.accountType | string | Sim | Tipo da conta de destino (ex: `CurrentAccount`). | | withdrawalTransactionDescription | string | Não | Descrição/observações livres associadas à mobilização (ex: motivo, referência). | ## 5. Payload de Resposta (Response - 200 OK) ### 5.1 Exemplo — pedido processado de imediato (`Confirmed`) ```json { "withdrawalTransactionReference": "TSX-00123", "withdrawalTransactionIdentification": null, "withdrawalTransactionStatus": { "statusReason": "Confirmed" } } ``` ### 5.2 Exemplo — pedido sujeito a diferimento (`Initiated`) ```json { "withdrawalTransactionReference": "TSX-00123", "withdrawalTransactionIdentification": { "identifierValue": "P00132" }, "withdrawalTransactionStatus": { "statusReason": "Initiated" } } ``` ### 5.3 Campos da Resposta | Campo | Tipo | Descrição | | --------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | withdrawalTransactionReference | string | Referência única atribuída à transacção de mobilização criada. | | withdrawalTransactionIdentification | object \| null | String de diferimento. Só é devolvida (não-nula) quando `withdrawalTransactionStatus.statusReason = "Initiated"`. Quando o pedido é confirmado de imediato (`Confirmed`), este campo é devolvido como `null`. | | withdrawalTransactionIdentification.identifierValue | string | Identificador da string de diferimento (apenas presente quando aplicável). | | withdrawalTransactionStatus.statusReason | string | Estado do pedido de mobilização. `Confirmed` quando a mobilização é processada 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 mobilização iniciada com sucesso. | | 400 | Bad Request | Parâmetros inválidos ou em falta (ex: montante não indicado, conta de destino inválida), ou montante superior ao saldo disponível na conta de depósito a prazo. | | 401 | Unauthorized | Token ausente, expirado ou inválido. | | 404 | Not Found | Rota não encontrada. | | 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": "O montante da mobilização excede o saldo disponível na conta de depósito a prazo.", "path": "/v1/term-deposit/901966920/debitand-credit/initiate", "errors": [ { "code": "TD-400-001", "reason": "INSUFFICIENT_BALANCE", "message": "Saldo insuficiente na conta '901966920' 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-001). | | 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 Válida | O termDepositId deve corresponder a uma conta de depósito a prazo activa e existente no sistema. | | 2 | Conta de Destino | `withdrawalTransaction.financialTransactionTargetAccount` identifica a conta para onde é creditado o valor da mobilização; deve ser uma conta válida e activa. | | 3 | Saldo Suficiente | `withdrawalTransactionAmount.amountValue` não pode exceder o saldo/montante disponível na conta de depósito a prazo a mobilizar. | | 4 | Mobilização Total ou Parcial | O montante indicado pode corresponder à totalidade ou a uma parte do valor depositado, consoante o suportado pelas condições do produto. | | 5 | Diferimento | O pedido de mobilização pode ser processado de imediato (`Confirmed`) ou ficar sujeito a diferimento (`Initiated`), consoante as regras do sistema; `withdrawalTransactionIdentification` 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 — scope term-deposit:withdrawal:initiate. Pedidos sem token ou com token inválido retornam 401. | | Auditoria | Registo persistente obrigatório de todas as operações de mobilização (log estruturado). | --- # 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/term-deposit/main-2.md?ask=&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.