> 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/collateral-allocation-management/retrieve-collateral-allocations/main.md). # Retrieve Collateral Allocations | Campo | Valor | | ------------------ | ------------------------------------------------------------------------------------------------------------------ | | **Service Domain** | Collateral Allocation Management | | **BIAN Version** | 14.0.0 | | **Operation** | Retrieve Collateral Allocation | | **Method** | GET | | **API Name** | Collateral Allocation Management API | | **Versão** | v1.0.0 | | **Endpoint** | `GET /v1/collateral-allocation-management/collateral-allocations/{collateralAllocationCustomerReference}/retrieve` | | **Autenticação** | Bearer Token (OAuth 2.0 / OIDC - realm nexus) | *** ## 1. Descrição da Operação A operação "Consulta de Garantias" permite recuperar a lista de todas as contas de garantias associadas a um cliente (Collateral Allocation Management) a partir da sua referência (número do cliente). A operação: * Devolve todas as contas garantias associadas ao cliente, com os respectivos montantes, datas de vencimento e estados; * Apresenta a identificação do cliente (nome) associada à referência fornecida; * Suporta filtragem por tipo de conta de garantia (`accountIdentificationType`) e paginação cursor via `accountIdentificationValue`; * Suporta consulta por número de cliente (`collateralAllocationCustomerReference`). *** ## 2. Cabeçalhos HTTP | Header | Obrigatório | Descrição | | ------------------------------- | ----------- | --------------------------------------------------------------- | | `Authorization: Bearer {token}` | Sim | OAuth2 / JWT - client\_credentials para M2M | | `Accept: application/json` | Sim | | | `x-request-id` | Recomendado | UUID v4 - identificador único do pedido para correlação em logs | | `x-channel` | Recomendado | Canal de origem (SOP, MOBILE, BACKOFFICE, …) | *** ## 3. Path Parameters | Parâmetro | Tipo | Obrigatório | Descrição | | --------------------------------------- | ------ | ----------- | ----------------------------------------------------------------- | | `collateralAllocationCustomerReference` | string | Sim | Identificador único do cliente. Corresponde ao número de cliente. | *** ## 4. Query Parameters | Parâmetro | Tipo | Obrigatório | Default | Descrição | | ---------------------------- | ------- | ----------- | ------- | ----------------------------------------------------------------------------------------------------- | | `accountIdentificationValue` | string | Não | — | Valor do identificador da conta de garantia (ex.: número da conta GARR). Usado para paginação cursor. | | `accountIdentificationType` | string | Não | GARR | Tipo de conta de garantia. Valores possíveis: `GARR` \| `GARP`. | | `size` | integer | Não | 20 | Número de registos de garantia a retornar por página. Máximo: 20. | *** ## 5. Payload de Resposta (Response — 200 OK) ```json { "collateralAllocationManagement": { "collateralAllocationCustomerReference": "123456", "collateralAllocationPartyIdentification": { "partyName": { "name": "NOME DO CLIENTE EXEMPLO" } }, "collateralAllocations": [ { "collateralAccountIdentification": { "accountIdentificationType": "GARR", "accountDescription": "Garantias Recebidas", "identifierValue": { "value": "12345601" } }, "collateralAllocationAmount": { "amountValue": 500000.00, "amountCurrency": { "currencyCode": "AKZ" } }, "collateralAllocationDueDate": { "dateContent": "2026-06-30", "dateType": "CollateralDueDate" }, "collateralStatus": "Active" } ] }, "_links": { "self": { "href": "/v1/collateral-allocation-management/collateral-allocations/123456/retrieve?size=2&accountIdentificationType=GARR&accountIdentificationValue=" }, "next": { "href": "/v1/collateral-allocation-management/collateral-allocations/123456/retrieve?size=2&accountIdentificationType=GARR&accountIdentificationValue=12345602" } } } ``` ### 5.1 Campos de Topo | Campo | Tipo | Obrigatório | Descrição | | --------------------------------------------------------------------------------------- | ------ | ----------- | ------------------------------------------------------------- | | `collateralAllocationManagement` | object | Sim | Objecto raiz com os dados do cliente e as garantias alocadas. | | `collateralAllocationManagement.collateralAllocationCustomerReference` | string | Sim | Referência do cliente no sistema Banka. | | `collateralAllocationManagement.collateralAllocationPartyIdentification` | object | Sim | Identificação da parte (cliente). | | `collateralAllocationManagement.collateralAllocationPartyIdentification.partyName.name` | string | Sim | Nome completo do cliente. | | `collateralAllocationManagement.collateralAllocations[]` | array | Sim | Lista de garantias alocadas. Ver secção 5.2. | | `_links` | object | Sim | Links de navegação para paginação (self, next). | ### 5.2 Objecto: `collateralAllocations[]` Array de contas de garantias associadas ao cliente. Cada entrada representa uma linha de conta de garantia. | Campo | Tipo | Obrigatório | Descrição | | ----------------------------------------------------------- | ----------------- | ----------- | -------------------------------------------------------------------------------------------- | | `collateralAccountIdentification.accountIdentificationType` | string | Sim | Tipo de conta de garantia (ex.: `GARR` - Garantias Recebidas; `GARP` - Garantias Prestadas). | | `collateralAccountIdentification.accountDescription` | string | Sim | Descrição do tipo de conta de garantia. | | `collateralAccountIdentification.identifierValue.value` | string | Sim | Número da conta de garantia. | | `collateralAllocationAmount.amountValue` | decimal | Sim | Valor da garantia. Máximo 2 casas decimais. | | `collateralAllocationAmount.amountCurrency.currencyCode` | string (ISO 4217) | Sim | Moeda da garantia (ex.: AKZ, EUR, USD). | | `collateralAllocationDueDate.dateContent` | string (ISO 8601) | Sim | Data de vencimento da garantia. Formato: `YYYY-MM-DD`. | | `collateralAllocationDueDate.dateType` | string | Sim | Tipo de data. Valor fixo: `CollateralDueDate`. | | `collateralStatus` | string | Sim | Estado da garantia. Ver secção 5.3. | ### 5.3 Valores do Campo `collateralStatus` | Valor | Descrição | Observações | | ----- | --------------- | ----------------------- | | N | Normal | Aplicada em GARR e GARP | | E | Encerrada | Aplicada em GARR e GARP | | X | Relevado Extrap | Aplicada em GARP | ### 5.4 Objecto: `_links` | Campo | Tipo | Obrigatório | Descrição | | ------------------ | ------ | ----------- | ----------------------------------------------------------------- | | `_links.self.href` | string | Sim | URL da página actual da consulta. | | `_links.next.href` | string | Não | URL para obter a próxima página de resultados (paginação cursor). | *** ## 6. Códigos HTTP de Resposta | Código | Estado | Descrição | | ------ | --------------------- | ---------------------------------------------------------------------------------- | | 200 | OK | Consulta concluída com sucesso. Dados de garantia devolvidos no corpo da resposta. | | 401 | Unauthorized | Token ausente, expirado ou inválido. | | 403 | Forbidden | Cliente autenticado mas sem scope para `collateral-allocation-management:read`. | | 404 | Not Found | `collateralAllocationCustomerReference` inexistente ou rota não encontrada. | | 500 | Internal Server Error | Erro inesperado no NEXUS ou no Backbone. | | 502 | Bad Gateway | Resposta inválida ou indisponibilidade do core Banka. | | 504 | Gateway Timeout | Timeout na chamada ao AS/400. | *** ## 7. Envelope Padrão de Erro ```json { "status": 404, "reason": "RESOURCE_NOT_FOUND", "message": "Cliente 123456 não encontrado no Banka.", "path": "/v1/collateral-allocation-management/123456/retrieve", "errordetail": [ { "code": "CAM-404-001", "reason": "CUSTOMER_NOT_FOUND", "message": "Nenhum registo encontrado para collateralAllocationCustomerReference: 123456." } ] } ``` ### 7.1 Estrutura do Envelope de Erro | Campo | Tipo | Obrigatório | Descrição | | ----------------------------- | ------- | ----------- | ----------------------------------------------------------------------- | | `error.status` | integer | Sim | Código HTTP do erro. | | `error.reason` | string | Sim | Código textual de alto nível que identifica a categoria do erro. | | `error.message` | string | Sim | Mensagem legível que descreve o problema ocorrido. | | `error.path` | string | Sim | Método HTTP e caminho do endpoint que originou o erro. | | `error.errordetail[]` | array | Não | Lista de erros detalhados. Pode estar ausente em erros genéricos (500). | | `error.errordetail[].code` | string | Não | Código específico do domínio (ex.: CAM-404-001). | | `error.errordetail[].reason` | string | Não | Identificador textual da causa específica do erro. | | `error.errordetail[].message` | string | Não | Mensagem detalhada sobre a causa específica. | *** ## 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. Pedidos sem token ou com token inválido retornam 401. | | **Logging Estruturado** | Todos os logs devem incluir o campo `x-request-id` para correlação de pedidos. | --- # 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/collateral-allocation-management/retrieve-collateral-allocations/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.