> 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-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": { "customerIdentifier": "5926762", "customerType": "CustomerNumber" }, "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.customerIdentifier | string | Sim | Número do cliente (Customer Number). | | customerReference.customerType | string | Sim | Tipo de identificador do cliente (ex: `CustomerNumber`). | | 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.customerIdentifier` 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. 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). |