> 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.md). # Retrieve Term Deposit Accounts | Campo | Valor | | -------------- | ------------------------------ | | Service Domain | Term Deposit | | BIAN Version | 14.0.0 | | Operation | Retrieve Term Deposit Accounts | | Method | GET | | API Name | Term Deposit Management API | | Versão | v1.0.0 | ## 1. Descrição da Operação O serviço de Consulta de Contas de Depósito a Prazo permite obter informação sobre as contas de depósito a prazo associadas a um cliente ou entidade. A operação retorna, para cada conta, o número da conta DP, a referência do cliente, o período de vigência do acordo (data de abertura e data de maturidade), o montante do depósito, a taxa de juro, o estado do acordo e o prazo do depósito. | Campo | Valor | | ------------ | ----------------------------------- | | API Name | Term Deposit Management API | | Versão | v1.0.0 | | Endpoint | GET /term-deposit/accounts/retrieve | | 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 *Não aplicável - esta operação não recebe parâmetros de path.* ### 3.2 Query Parameters | Parâmetro | Tipo | Obrigatório | Descrição | | ---------------------- | ------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------- | | customerReference | string | Não\* | Número do cliente titular das contas de depósito a prazo a consultar. | | entityReference | string | Não\* | Número da entidade titular das contas de depósito a prazo a consultar. | | size | integer | Não | Número máximo de registos a devolver na resposta. Default: `20`. Mínimo: `1`. Máximo: `100`. | | offset | string | Não | Cursor/identificador de paginação (conta a partir da qual continuar a listagem). | | includeSettledAccounts | boolean | Não | Indica se as contas de depósito a prazo já liquidadas/encerradas (settled) devem ser incluídas na resposta. Default: `false`. | \* `customerReference` e `entityReference` são individualmente opcionais, mas **não podem ser usados em simultâneo** no mesmo pedido (ver Regras de Negócio, item 1). **Exemplo:** `GET /term-deposit/accounts/retrieve?customerReference=12345&size=20&includeSettledAccounts=false` ## 4. Payload de Resposta (Response - 200 OK) ### 4.1 Exemplo - com página seguinte disponível ```json { "termDepositFulfillmentArrangements": [ { "termDepositAccountNumber": { "accountIdentificationType": "BBAN", "accountIdentification": { "identifierValue": "1234567890987" } }, "customerReference": { "partyReference": "12345", "involvementReference": "AccountHolder" }, "agreementValidityPeriod": { "fromDate": { "dateContent": "2026-03-01", "dateType": "OpeningDate" }, "toDate": { "dateContent": "2026-09-01", "dateType": "MaturityDate" } }, "termDepositAmount": { "amountValue": 120000.00, "currencyCode": "AKZ", "amountType": "Principal" }, "entitlementOptionDefinition": { "depositInterest": { "interestRate": { "rateValue": 10 } }, "arrangementStatus": { "statusCode": "N", "statusReason": "Normal" }, "depositTerm": { "depositTermValue": 28, "depositTermValueDescription": "NumberOfDays" } } } ], "isLastPage": false, "_links": { "self": { "href": "/term-deposit/accounts/retrieve?customerReference=12345&size=20" }, "next": { "href": "/term-deposit/accounts/retrieve?customerReference=12345&size=20&offset=eyJpZCI6MTIzfQ==" } } } ``` ### 4.2 Exemplo - última página (sem `next`) ```json { "termDepositFulfillmentArrangements": [ { "termDepositAccountNumber": { "accountIdentificationType": "BBAN", "accountIdentification": { "identifierValue": "1234567890988" } }, "customerReference": { "partyReference": "12345", "involvementReference": "AccountHolder" }, "agreementValidityPeriod": { "fromDate": { "dateContent": "2026-03-01", "dateType": "OpeningDate" }, "toDate": { "dateContent": "2026-09-01", "dateType": "MaturityDate" } }, "termDepositAmount": { "amountValue": 50000.00, "currencyCode": "AKZ", "amountType": "Principal" }, "entitlementOptionDefinition": { "depositInterest": { "interestRate": { "rateValue": 10 } }, "arrangementStatus": { "statusCode": "N", "statusReason": "Normal" }, "depositTerm": { "depositTermValue": 28, "depositTermValueDescription": "NumberOfDays" } } } ], "isLastPage": true, "_links": { "self": { "href": "/term-deposit/accounts/retrieve?customerReference=12345&size=20&offset=eyJpZCI6MTIzfQ==" }, "next": null } } ``` ### 4.3 Campos da Resposta | Campo | Tipo | Descrição | | --------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | termDepositFulfillmentArrangements\[] | array | Lista de contas de depósito a prazo associadas ao cliente/entidade. | | termDepositFulfillmentArrangements\[].termDepositAccountNumber.accountIdentificationType | string | Tipo de identificação da conta DP (ex: `BBAN`). | | termDepositFulfillmentArrangements\[].termDepositAccountNumber.accountIdentification.identifierValue | string | Número da conta de depósito a prazo (Conta DP). | | termDepositFulfillmentArrangements\[].customerReference.partyReference | string | Identificador do cliente. | | termDepositFulfillmentArrangements\[].customerReference.involvementReference | string | Papel do cliente na conta (ex: `AccountHolder`). | | termDepositFulfillmentArrangements\[].agreementValidityPeriod.fromDate.dateContent | string (ISO 8601) | Data de início/abertura do acordo. | | termDepositFulfillmentArrangements\[].agreementValidityPeriod.fromDate.dateType | string | Tipo de data (`OpeningDate`). | | termDepositFulfillmentArrangements\[].agreementValidityPeriod.toDate.dateContent | string (ISO 8601) | Data de maturidade (vencimento) do acordo. | | termDepositFulfillmentArrangements\[].agreementValidityPeriod.toDate.dateType | string | Tipo de data (`MaturityDate`). | | termDepositFulfillmentArrangements\[].termDepositAmount.amountValue | number | Montante do depósito a prazo. | | termDepositFulfillmentArrangements\[].termDepositAmount.currencyCode | string | Código da moeda do montante depositado (ISO 4217, ex: `AKZ`). | | termDepositFulfillmentArrangements\[].termDepositAmount.amountType | string | Tipo de montante (`Principal`). | | termDepositFulfillmentArrangements\[].entitlementOptionDefinition.depositInterest.interestRate.rateValue | number | Taxa de juro aplicada ao depósito (%). | | termDepositFulfillmentArrangements\[].entitlementOptionDefinition.arrangementStatus.statusCode | string | Código do estado do acordo (ex: `N`). | | termDepositFulfillmentArrangements\[].entitlementOptionDefinition.arrangementStatus.statusReason | string | Descrição do estado do acordo (ex: `Normal`). | | termDepositFulfillmentArrangements\[].entitlementOptionDefinition.depositTerm.depositTermValue | integer | Valor numérico do prazo do depósito em dias. | | termDepositFulfillmentArrangements\[].entitlementOptionDefinition.depositTerm.depositTermValueDescription | string | Unidade do prazo do depósito (ex: `NumberOfDays`). | | isLastPage | boolean | Indica se a página actual é a última página de resultados disponível. `true` quando não há mais registos a seguir; `false` quando existem mais páginas. | | \_links | object | Objecto com os links de navegação/paginação da resposta (HATEOAS). | | \_links.self.href | string | URL da página actual (o próprio pedido que gerou esta resposta). | | \_links.next | object \| null | Link para a página seguinte de resultados. Só é devolvido (não-nulo) quando `isLastPage = false`, ou seja, quando existe uma página seguinte; vem `null` na última página. | | \_links.next.href | string | URL completo da página seguinte, já com o `offset` calculado embutido. O cliente deve usar este valor tal como veio (ou extrair o `offset` da query string) para pedir a página seguinte - não deve construir o `offset` manualmente. | ## 5. Códigos HTTP de Resposta | Código | Estado | Descrição | | ------ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | 200 | OK | Consulta executada com sucesso. | | 400 | Bad Request | Parâmetros inválidos (ex: `customerReference` e `entityReference` indicados em simultâneo, ou `size` fora do intervalo permitido). | | 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. | ## 6. Envelope Padrão de Erro ```json { "status": 400, "reason": "BAD_REQUEST", "message": "customerReference e entityReference não podem ser usados em simultâneo.", "path": "/term-deposit/accounts/retrieve", "errors": [ { "code": "TDA-400-001", "reason": "MUTUALLY_EXCLUSIVE_PARAMETERS", "message": "Apenas um dos parâmetros customerReference ou entityReference pode ser indicado por pedido." } ] } ``` ### 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. | | 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: TDA-400-001). | | errors\[].reason | string | Identificador textual da causa específica do erro. | | errors\[].message | string | Mensagem detalhada com valores concretos quando aplicável. | ## 7. Regras de Negócio | # | Regra | Detalhe | | - | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Exclusividade de Referência | `customerReference` e `entityReference` não podem ser usados em simultâneo no mesmo pedido; se ambos forem indicados, o pedido é rejeitado com `400 Bad Request`. | | 2 | Referência Obrigatória (implícita) | Ainda que ambos os parâmetros sejam opcionais a nível técnico, deve existir pelo menos um (`customerReference` ou `entityReference`) para que a consulta devolva resultados relevantes. | | 3 | Contas Liquidadas | Contas de depósito a prazo já encerradas só são incluídas na resposta quando `includeSettledAccounts=true`. | | 4 | Paginação | O número de registos devolvidos respeita o valor de `size` (1–100, default 20). Para obter a página seguinte, o cliente deve enviar o parâmetro `offset` com o valor proveniente do link `_links.next.href` da resposta anterior - este link só é devolvido enquanto existir uma página seguinte; quando a página actual é a última, `_links.next` vem `null` e `isLastPage = true`, sinalizando o fim da listagem. | | 5 | Múltiplas Contas | Um mesmo cliente/entidade pode ter mais do que uma conta de depósito a prazo activa; a resposta deve listar todas as contas correspondentes aos critérios indicados. | ## 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 term-deposit:accounts:retrieve. Pedidos sem token ou com token inválido retornam 401. | | Auditoria | Registo persistente obrigatório de todas as consultas (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.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.