> 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-4.md). # Initiate a new Term Deposit Account | Campo | Valor | | -------------- | --------------------------- | | Service Domain | Term Deposit | | BIAN Version | 14.0.0 | | Operation | Initiate | | Method | POST | | API Name | Term Deposit Management API | | Versão | v1.0.0 | ## 1. Descrição da Operação O serviço de Constituição (Initiate) permite abrir/criar uma nova conta de depósito a prazo para um cliente, com débito do depósito inicial numa conta à ordem pagadora indicada no pedido. O pedido recebe os dados do cliente titular, o produto/componente contratado, a data de valor e a data de abertura, o montante inicial, o prazo, a taxa de juro e, opcionalmente, uma conta vinculada para liquidação de juros. A criação pode ser processada de imediato ou ficar sujeita a diferimento. | Campo | Valor | | ------------ | ------------------------------- | | API Name | Term Deposit Management API | | Versão | v1.0.0 | | Endpoint | POST /v1/term-deposit/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 Este serviço não recebe Path Parameters nem Query Parameters — todos os dados são enviados no corpo da requisição (Request Body). ## 4. Payload de Requisição (Request Body) ### 4.1 Exemplo ```json { "customerReference": { "partyReference": "123456789", "involvementReference": "AccountHolder" }, "termDepositInstanceReference": { "productAgreementIdentification": { "identifierValue": "TD001", "productAgreementDescription": "productCode" }, "componentAgreementIdentification": { "identifierValue": "COM001", "componentAgreementDescription": "componentCode" }, "termDepositAgreementType": "TermDepositAgreement", "agreementDescription": "Constituição de depósito a prazo" }, "initialDepositValueDate": { "dateContent": "2021-09-21", "dateType": "ValueDate" }, "termDepositOpenDate": { "dateContent": "2026-09-21", "dateType": "OpenDate" }, "termDepositPayerAccountReference": { "accountIdentification": { "accountIdentificationType": "BBAN", "accountIdentification": { "identifierValue": "000123456789" } }, "accountType": "CurrentAccount" }, "termDepositAmount": { "amountValue": 1000000.00, "amountCurrency": { "currencyCode": "AKZ" }, "amountType": "InitialDepositAmount" }, "entitlementOptionDefinition": { "depositTerm": { "depositTermValue": 28, "depositTermValueDescription": "NumberOfDays" }, "depositInterest": { "interestRate": { "rateValue": 12.50 } } }, "linkedAccount": { "accountIdentification": { "accountIdentificationType": "BBAN", "accountIdentification": { "identifierValue": "000987654321" } }, "accountType": "CurrentAccount", "accountPurpose": "InterestSettlement" } } ``` ### 4.2 Campos da Requisição | Campo | Tipo | Obrigatório | Descrição | | -------------------------------------------------------------------------------------------- | ----------------- | ----------- | --------------------------------------------------------------------------- | | customerReference | object | Sim | Identificação do cliente titular da conta de depósito a prazo a constituir. | | customerReference.partyReference | string | Sim | Identificador único do cliente (parte), Máx: 9 dígitos. | | customerReference.involvementReference | string | Sim | Tipo de envolvimento do cliente com a conta (ex: `AccountHolder`). | | termDepositInstanceReference | object | Sim | Dados do produto/componente contratado para a conta de depósito a prazo. | | termDepositInstanceReference.productAgreementIdentification.identifierValue | string | Sim | Código do produto (ex: `TD001`). | | termDepositInstanceReference.productAgreementIdentification.productAgreementDescription | string | Não | Descrição/rótulo do produto. | | termDepositInstanceReference.componentAgreementIdentification.identifierValue | string | Sim | Código do componente do produto (ex: `COM001`). | | termDepositInstanceReference.componentAgreementIdentification.componentAgreementDescription | string | Não | Descrição/rótulo do componente. | | termDepositInstanceReference.termDepositAgreementType | string | Sim | Tipo de acordo (ex: `TermDepositAgreement`). | | termDepositInstanceReference.agreementDescription | string | Não | Descrição livre da constituição/contrato. | | initialDepositValueDate.dateContent | string (ISO 8601) | Sim | Data de valor do depósito inicial. | | initialDepositValueDate.dateType | string | Sim | Tipo de data (`ValueDate`). | | termDepositOpenDate.dateContent | string (ISO 8601) | Sim | Data de abertura da conta de depósito a prazo. | | termDepositOpenDate.dateType | string | Sim | Tipo de data (`OpenDate`). | | termDepositPayerAccountReference | object | Sim | Conta à ordem de onde é debitado o montante do depósito inicial. | | termDepositPayerAccountReference.accountIdentification.accountIdentificationType | string | Sim | Tipo de identificador de conta (ex: `BBAN`). | | termDepositPayerAccountReference.accountIdentification.accountIdentification.identifierValue | string | Sim | Número/identificador da conta pagadora. | | termDepositPayerAccountReference.accountType | string | Sim | Tipo de conta pagadora (ex: `CurrentAccount`). | | termDepositAmount.amountValue | number | Sim | Montante inicial a depositar na constituição da conta. | | termDepositAmount.amountCurrency.currencyCode | string | Sim | Código da moeda do montante inicial (ISO 4217, ex: `AKZ`). | | termDepositAmount.amountType | string | Sim | Tipo de montante (`InitialDepositAmount`). | | entitlementOptionDefinition | object | Sim | Condições financeiras da constituição (prazo e taxa). | | entitlementOptionDefinition.depositTerm.depositTermValue | number | Sim | Valor numérico do prazo do depósito. | | entitlementOptionDefinition.depositTerm.depositTermValueDescription | string | Sim | Unidade do prazo (ex: `NumberOfDays`). | | entitlementOptionDefinition.depositInterest.interestRate.rateValue | number | Sim | Taxa de juro (%) aplicada ao depósito. | | linkedAccount | object | Sim | Conta vinculada para liquidação de juros. | | linkedAccount.accountIdentification.accountIdentificationType | string | Não | Tipo de identificador de conta (ex: `BBAN`). | | linkedAccount.accountIdentification.accountIdentification.identifierValue | string | Não | Número/identificador da conta vinculada. | | linkedAccount.accountType | string | Não | Tipo de conta vinculada (ex: `CurrentAccount`). | | linkedAccount.accountPurpose | string | Não | Finalidade da conta vinculada (ex: `InterestSettlement`). | ## 5. Payload de Resposta (Response - 200 OK / 201 Created) ### 5.1 Exemplo — pedido processado de imediato (`Confirmed`) ```json { "productInstanceReference": { "termDepositAgreementIdentification": { "identifierValue": "TD-20260922-00001" }, "termDepositAgreementType": "TermDeposit" }, "termDepositMaturityDate": { "dateContent": "2026-09-21", "dateType": "MaturityDate" }, "operationStatus": { "operationReference": { "identifierValue": "OP-20260922-00001" } }, "depositTransactionIdentification": null, "depositTransactionStatus": { "statusReason": "Confirmed" } } ``` > ⚠️ Ver nota #2 (`dateType` corrigido para `MaturityDate`) e nota #3 (`depositTransactionIdentification: null` aplicado por analogia com a regra já confirmada nos outros serviços). ### 5.2 Exemplo — pedido sujeito a diferimento (`Initiated`) ```json { "productInstanceReference": { "termDepositAgreementIdentification": { "identifierValue": "TD-20260922-00001" }, "termDepositAgreementType": "TermDeposit" }, "termDepositMaturityDate": { "dateContent": "2026-09-21", "dateType": "MaturityDate" }, "operationStatus": { "operationReference": { "identifierValue": "OP-20260922-00001" } }, "depositTransactionIdentification": { "identifierValue": "TXN2026092200001" }, "depositTransactionStatus": { "statusReason": "Initiated" } } ``` ### 5.3 Campos da Resposta | Campo | Tipo | Descrição | | --------------------------------------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | productInstanceReference | object | Identificação da conta de depósito a prazo constituída. | | productInstanceReference.termDepositAgreementIdentification.identifierValue | string | Identificador único (número) da nova conta de depósito a prazo (Conta DP). | | productInstanceReference.termDepositAgreementType | string | Tipo de acordo criado (ex: `TermDeposit`). | | termDepositMaturityDate.dateContent | string (ISO 8601) | Data de vencimento/maturidade calculada para a nova conta, com base no prazo contratado. | | termDepositMaturityDate.dateType | string | Tipo de data (`MaturityDate`) — ver nota #2. | | operationStatus.operationReference.identifierValue | string | Referência única da operação de constituição executada. | | depositTransactionIdentification | object \| null | String de diferimento. Só é devolvida (não-nula) quando `depositTransactionStatus.statusReason = "Initiated"`; devolvida como `null` quando `Confirmed` — ver nota #3. | | depositTransactionIdentification.identifierValue | string | Identificador da string de diferimento (apenas presente quando aplicável). | | depositTransactionStatus.statusReason | string | Estado do pedido de constituição. `Confirmed` quando processado de imediato; `Initiated` quando o pedido fica sujeito a diferimento (aguarda processamento). | ## 6. Códigos HTTP de Resposta | Código | Estado | Descrição | | ------ | --------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | 201 | Created | Conta de depósito a prazo constituída com sucesso. | | 400 | Bad Request | Parâmetros inválidos ou em falta (ex: montante, prazo ou taxa não indicados/inválidos), ou saldo insuficiente na conta pagadora. | | 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": "Saldo insuficiente na conta pagadora para o montante do depósito inicial.", "path": "/v1/term-deposit/initiate", "errors": [ { "code": "TD-400-003", "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-003). | | 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 | Cliente Válido | O `customerReference.partyReference` deve corresponder a um cliente existente e apto a contratar depósitos a prazo. | | 2 | Produto/Componente Válido | A combinação `productAgreementIdentification` + `componentAgreementIdentification` deve corresponder a um produto de depósito a prazo activo no catálogo. | | 3 | Conta Pagadora Válida | A `termDepositPayerAccountReference` deve corresponder a uma conta à ordem activa e existente, com saldo suficiente para o montante inicial. | | 4 | Moeda | A moeda de `termDepositAmount` deve ser suportada pelo produto/componente contratado. | | 5 | Cálculo de Maturidade | `termDepositMaturityDate`, na resposta, é calculada automaticamente a partir de `termDepositOpenDate` (ou `initialDepositValueDate`) e do `depositTerm` contratado. | | 6 | Diferimento | A constituição pode ser processada de imediato (`Confirmed`) ou ficar sujeita a diferimento (`Initiated`), consoante as regras do sistema; `depositTransactionIdentification` só é devolvido com valor quando o estado é `Initiated`, vindo `null` quando `Confirmed`. | ## 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:initiate. Pedidos sem token ou com token inválido retornam 401. | | Auditoria | Registo persistente obrigatório de todas as operações de constituiçã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-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 `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.