> 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/documentation/term-deposit/operations/main-4.md). # Process Term Deposit Account Constitution | Campo | Valor | | ------------------ | --------------------------------- | | **Service Domain** | Term Deposit | | **BIAN Version** | 14.0.0 | | **Operation** | Initiate | | **Method** | POST | | **API Name** | Term Deposit API | | **Versão** | v1.0.0 | | **Endpoint** | `POST /v1/term-deposits/initiate` | | **Autenticação** | Bearer Token (OAuth 2.0 / OIDC) | *** ## 1. Descrição da Operação A API **Term Deposit Initiate** permite efectuar a constituição de um novo Depósito a Prazo, debitando o montante do capital numa conta de origem indicada no payload e criando um novo contrato de D/P associado ao cliente. A operação: * Regista a criação de um novo Term Deposit para o cliente identificado por `customerReference`. * Debita o valor a constituir da conta de origem (conta DO) e cria o contrato de D/P com o capital, prazo e taxa de juros indicados. * Devolve o identificador do contrato criado (`termDepositAccount`), a data de vencimento calculada e a referência da operação processada. *** ## 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. Payload de Pedido (Request) ```json { "customerReference": "27113247", "termDepositProduct": { "productCode": "DEP_PRAZO", "componentCode": "DP_BCI" }, "principalAmount": { "amountValue": 100000, "amountCurrency": { "currencycode": "AKZ" }, "amountType": "Principal" }, "interestRate": { "rateValue": 10.0, "rateType": "Nominal" }, "termDepositPeriod": { "numberOfDays": 91 }, "valueDate": "2026-09-09", "sourceAccount": { "accountIdentification": "2711324710001", "accountType": "DebitAccount" }, "interestSettlementAccount": { "accountIdentification": "2711324710001", "accountType": "CreditAccount" }, "transactionDescription": "Constituição D/P-Tx: 10,00000% dias:91" } ``` ### 3.1 Objecto Raiz | Campo | Tipo | Obrigatório | Descrição | | --------------------------- | ----------------- | ----------- | ------------------------------------------------------------ | | `customerReference` | string | Sim | Número do cliente titular do Depósito a Prazo a constituir. | | `termDepositProduct` | object | Sim | Identificação do produto/componente do D/P (ver secção 3.2). | | `principalAmount` | object | Sim | Montante de capital a constituir (ver secção 3.3). | | `interestRate` | object | Sim | Taxa de juros aplicável ao contrato (ver secção 3.4). | | `termDepositPeriod` | object | Sim | Prazo do Depósito a Prazo (ver secção 3.5). | | `valueDate` | string (ISO 8601) | Sim | Data valor da constituição. Formato: `YYYY-MM-DD`. | | `sourceAccount` | object | Sim | Conta de origem do débito do capital (ver secção 3.6). | | `interestSettlementAccount` | object | Sim | Conta de liquidação dos juros do contrato (ver secção 3.6). | | `transactionDescription` | string | Não | Descrição do movimento a registar no core bancário. | ### 3.2 Objecto: `termDepositProduct` | Campo | Tipo | Obrigatório | Descrição | | --------------- | ------ | ----------- | ------------------------------------------------------- | | `productCode` | string | Sim | Código do produto de Depósito a Prazo no core bancário. | | `componentCode` | string | Sim | Código do componente do produto associado ao contrato. | ### 3.3 Objecto: `principalAmount` | Campo | Tipo | Obrigatório | Descrição | | ----------------------------- | ----------------- | ----------- | ----------------------------------------------------- | | `amountValue` | decimal (> 0) | Sim | Montante de capital a constituir no Depósito a Prazo. | | `amountCurrency.currencycode` | string (ISO 4217) | Sim | Código de moeda. Exemplos: `AKZ`, `USD`, `EUR`. | | `amountType` | enum | Sim | Tipo do montante. Valor: `Principal`. | ### 3.4 Objecto: `interestRate` | Campo | Tipo | Obrigatório | Descrição | | ----------- | ------- | ----------- | -------------------------------------------------- | | `rateValue` | decimal | Sim | Valor da taxa de juros anual aplicada ao contrato. | | `rateType` | enum | Sim | Tipo de taxa. Valor: `Nominal`. | ### 3.5 Objecto: `termDepositPeriod` | Campo | Tipo | Obrigatório | Descrição | | -------------- | ----------------- | ----------- | ----------------------------------------- | | `numberOfDays` | integer (> 0) | Sim\* | Número de dias do prazo do contrato. | | `maturityDate` | string (ISO 8601) | Não\* | Data de vencimento explícita do contrato. | \* Deve ser indicado `numberOfDays` ou `maturityDate`; quando ambos são omitidos o pedido é rejeitado. Quando `numberOfDays` é fornecido, `maturityDate` é calculada pelo core bancário e devolvida na resposta. ### 3.6 Objecto: `sourceAccount` / `interestSettlementAccount` | Campo | Tipo | Obrigatório | Descrição | | ----------------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------ | | `accountIdentification` | string | Sim | Número da conta. Em `sourceAccount`, a conta a debitar o capital; em `interestSettlementAccount`, a conta a creditar os juros. | | `accountType` | enum | Sim | Papel da conta na operação. Valores: `DebitAccount` (origem) ou `CreditAccount` (liquidação de juros). | *** ## 4. Payload de Resposta (Response — 200 OK) ```json { "termDepositAccount": "2711324720001", "customerReference": "27113247", "termDepositProduct": { "productCode": "DEP_PRAZO", "componentCode": "DP_BCI" }, "principalAmount": { "amountValue": 100000, "amountCurrency": { "currencycode": "AKZ" } }, "termDepositPeriod": { "numberOfDays": 91, "maturityDate": "2026-12-09" }, "valueDate": "2026-09-09", "sourceAccount": { "accountIdentification": "2711324710001", "valueDate": "2026-09-09" }, "interestSettlementAccount": { "accountIdentification": "2711324710001" }, "transactionDescription": "Constituição D/P-Tx: 10,00000% dias:91", "operationReference": "13325200" } ``` ### 4.1 Objecto Raiz | Campo | Tipo | Descrição | | ------------------------------------------------- | ----------------- | ---------------------------------------------------- | | `termDepositAccount` | string | Número do contrato de Depósito a Prazo criado. | | `customerReference` | string | Número do cliente titular do contrato. | | `termDepositProduct.productCode` | string | Código do produto associado ao contrato criado. | | `termDepositProduct.componentCode` | string | Código do componente associado ao contrato criado. | | `principalAmount.amountValue` | decimal | Montante de capital constituído. | | `principalAmount.amountCurrency.currencycode` | string (ISO 4217) | Código de moeda do contrato. | | `termDepositPeriod.numberOfDays` | integer | Número de dias do prazo contratado. | | `termDepositPeriod.maturityDate` | string (ISO 8601) | Data de vencimento calculada pelo core bancário. | | `valueDate` | string (ISO 8601) | Data valor da constituição. | | `sourceAccount.accountIdentification` | string | Número da conta de origem que foi debitada. | | `sourceAccount.valueDate` | string (ISO 8601) | Data valor do débito na conta de origem. | | `interestSettlementAccount.accountIdentification` | string | Número da conta de liquidação dos juros do contrato. | | `transactionDescription` | string | Descrição do movimento registado no core bancário. | | `operationReference` | string | Referência da operação processada no core bancário. | *** ## 5. Códigos HTTP de Resposta | Código | Estado | Descrição | | ------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | 200 | OK | Depósito a Prazo constituído com sucesso. | | 202 | Accepted | Pedido aceite; execução assíncrona pendente de confirmação do core bancário. | | 400 | Bad Request | Payload inválido: montante ≤ 0, moeda inválida, prazo em falta, conta de origem em falta ou campos obrigatórios omitidos. | | 401 | Unauthorized | Token ausente, expirado ou inválido. | | 403 | Forbidden | Cliente autenticado mas sem scope para `termDeposit:initiate`. | | 404 | Not Found | `customerReference` ou conta de origem não encontrados. | | 409 | Conflict | Operação duplicada detectada (mesmo `correlationId`/pedido). | | 422 | Unprocessable Entity | Regra de negócio violada: saldo insuficiente na conta de origem, moeda divergente, cliente bloqueado, produto/componente inválido, etc. | | 500 | Internal Server Error | Erro inesperado no sistema. | | 502 | Bad Gateway | Resposta inválida ou indisponibilidade do core bancário. | | 504 | Gateway Timeout | Timeout na chamada ao core bancário. | *** ## 6. Envelope Padrão de Erro ```json { "status": 422, "reason": "BUSINESS_RULE_VIOLATION", "message": "Saldo insuficiente na conta de origem para efectuar a constituição solicitada.", "path": "/v1/term-deposits/initiate", "errordetail": [ { "code": "TD-422-002", "reason": "INSUFFICIENT_FUNDS_SOURCE_ACCOUNT", "message": "Conta 2711324710001: saldo 50000.00 AKZ < montante solicitado 100000.00 AKZ." } ] } ``` ### 6.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. | | `errordetail[]` | array | Lista de erros detalhados. Pode estar ausente em erros genéricos (500). | | `errordetail[].code` | string | Código específico do domínio (ex.: `TD-422-002`). | | `errordetail[].reason` | string | Identificador textual da causa específica do erro. | | `errordetail[].message` | string | Mensagem detalhada com valores concretos quando aplicável. | *** ## 7. Regras de Negócio | # | Regra | Detalhe | | - | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Cliente Válido | O `customerReference` deve corresponder a um cliente existente e não bloqueado. | | 2 | Produto/Componente Válido | A combinação `productCode`/`componentCode` deve existir e estar activa no core bancário. | | 3 | Conta de Origem Obrigatória | Deve ser fornecida exactamente uma conta de origem (`sourceAccount`), activa e pertencente ao cliente. | | 4 | Consistência de Moeda | A moeda da conta de origem deve coincidir com `principalAmount.amountCurrency.currencycode`. | | 5 | Montante Válido | `principalAmount.amountValue` deve ser maior que zero e a conta de origem deve ter saldo suficiente para cobrir o montante solicitado. | | 6 | Prazo Válido | Deve ser fornecido `numberOfDays` ou `maturityDate`; o core bancário calcula o campo em falta e devolve-o na resposta. | | 7 | Data de Constituição | A `valueDate` da constituição é determinada pelo pedido, mas validada contra o calendário de dias úteis do core bancário. | | 8 | Protecção contra Dupla Execução | O serviço verifica idempotência via correlação do pedido. Pedidos duplicados com a mesma referência são rejeitados com 409. | *** ## 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 — scope `termDeposit:initiate`. Pedidos sem token ou com token inválido retornam 401. | | Auditoria | Registo persistente obrigatório de todas as execuções (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 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/documentation/term-deposit/operations/main-4.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 `automate deployments from our CI pipeline` 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.