> 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-allocation-details/main.md).

# Retrieve Collateral Allocation Details

| 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/{collateralAllocationCustomerReference}/retrieve` |
| **Autenticação**   | Bearer Token (OAuth 2.0 / OIDC)                                                             |

***

## 1. Descrição da Operação

O serviço de Consulta de Detalhes de uma Conta Garantia permite obter a informação completa de uma garantia recebida associada a um cliente. A operação retorna dados como o tipo de garantia, valor de avaliação, estado, período de vigência, classificação de prazo e atributos adicionais de reporte (CIRC).

***

## 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. Path Parameters

| Parâmetro                               | Tipo   | Obrigatório | Descrição                              |
| --------------------------------------- | ------ | ----------- | -------------------------------------- |
| `collateralAllocationCustomerReference` | string | Sim         | Identificador único da conta garantia. |

***

## 4. Payload de Resposta (Response — 200 OK)

### 4.1 Exemplo

```json
{
  "collateralAllocationManagement": {
    "collateralAllocationCustomerReference": "123456",
    "collateralAllocationPartyIdentification": {
      "partyName": {
        "name": "NOME DO CLIENTE EXEMPLO"
      }
    },
    "collateralAllocationAccount": {
      "accountIdentification": {
        "accountIdentificationType": "GARR",
        "accountDescription": "Garantias Recebidas",
        "identifierValue": {
          "value": "12345601"
        }
      }
    },
    "collateralAllocationType": {
      "collateralTypeValue": "01",
      "collateralTypeDescription": "Caução-depósito junto da própria Instituição"
    },
    "collateralAllocationPercentage": {
      "percentageValue": 10.0,
      "percentageDescription": "Percentagem de Alocação"
    },
    "collateralAllocationAmount": {
      "amountValue": 500000.00,
      "amountCurrency": {
        "currencyCode": "AKZ"
      }
    },
    "collateralStatus": {
      "collateralStatusType": {
        "statusType": "Normal"
      },
      "statusDate": {
        "dateContent": "2025-12-03",
        "dateType": "CollateralStatusDate"
      }
    },
    "collateralAllocationPeriod": {
      "fromDate": {
        "dateContent": "2025-12-03",
        "dateType": "OpenDate"
      },
      "toDate": {
        "dateContent": "2026-12-03",
        "dateType": "MaturityDate"
      }
    },
    "collateralTermClassification": {
      "termClassificationCode": "26",
      "termClassificationDescription": "Superior a 10 anos"
    },
    "collateralAttributes": [
      {
        "attributeValue": "40",
        "attributeCode": "CIDFGG",
        "attributeDescription": "CIRC - Identificação Garantia"
      },
      {
        "attributeValue": "2",
        "attributeCode": "TIPAVG",
        "attributeDescription": "CIRC - Tipo de avaliação"
      },
      {
        "attributeValue": "2",
        "attributeCode": "IEXGAR",
        "attributeDescription": "CIRC - Indicador execução gar."
      }
    ]
  }
}
```

### 4.2 Campos da Resposta

| Campo                                                                         | Tipo              | Descrição                                              |
| ----------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------ |
| `collateralAllocationCustomerReference`                                       | string            | Identificador do cliente titular da garantia.          |
| `collateralAllocationPartyIdentification.partyName.name`                      | string            | Nome do cliente titular.                               |
| `collateralAllocationAccount.accountIdentification.accountIdentificationType` | string            | Tipo de identificação da conta.                        |
| `collateralAllocationAccount.accountIdentification.accountDescription`        | string            | Descrição da conta.                                    |
| `collateralAllocationAccount.accountIdentification.identifierValue.value`     | string            | Número da conta de garantia.                           |
| `collateralAllocationType.collateralTypeValue`                                | string            | Código do tipo de garantia.                            |
| `collateralAllocationType.collateralTypeDescription`                          | string            | Descrição do tipo de garantia.                         |
| `collateralAllocationPercentage.percentageValue`                              | decimal           | Percentagem de alocação da garantia.                   |
| `collateralAllocationPercentage.percentageDescription`                        | string            | Descrição da percentagem de alocação.                  |
| `collateralAllocationAmount.amountValue`                                      | decimal           | Valor monetário da garantia alocada.                   |
| `collateralAllocationAmount.amountCurrency.currencyCode`                      | string (ISO 4217) | Moeda do valor da garantia.                            |
| `collateralStatus.collateralStatusType.statusType`                            | string            | Estado actual da garantia.                             |
| `collateralStatus.statusDate.dateContent`                                     | string (ISO 8601) | Data do estado. Formato: `YYYY-MM-DD`.                 |
| `collateralStatus.statusDate.dateType`                                        | string            | Tipo de data do estado.                                |
| `collateralAllocationPeriod.fromDate.dateContent`                             | string (ISO 8601) | Data de abertura da garantia. Formato: `YYYY-MM-DD`.   |
| `collateralAllocationPeriod.fromDate.dateType`                                | string            | Tipo de data de início.                                |
| `collateralAllocationPeriod.toDate.dateContent`                               | string (ISO 8601) | Data de maturidade da garantia. Formato: `YYYY-MM-DD`. |
| `collateralAllocationPeriod.toDate.dateType`                                  | string            | Tipo de data de fim (ex: `MaturityDate`).              |
| `collateralTermClassification.termClassificationCode`                         | string            | Código de classificação do prazo.                      |
| `collateralTermClassification.termClassificationDescription`                  | string            | Descrição da classificação do prazo.                   |
| `collateralAttributes[]`                                                      | array             | Lista de atributos adicionais de reporte (CIRC).       |
| `collateralAttributes[].attributeValue`                                       | string            | Valor do atributo.                                     |
| `collateralAttributes[].attributeCode`                                        | string            | Código identificador do atributo.                      |
| `collateralAttributes[].attributeDescription`                                 | string            | Descrição do atributo.                                 |

***

## 5. Códigos HTTP de Resposta

| Código | Estado                | Descrição                                                                 |
| ------ | --------------------- | ------------------------------------------------------------------------- |
| 200    | OK                    | Consulta executada com sucesso.                                           |
| 400    | Bad Request           | Parâmetros inválidos ou em falta.                                         |
| 401    | Unauthorized          | Token ausente, expirado ou inválido.                                      |
| 403    | Forbidden             | Cliente autenticado mas sem scope para `collateral:allocations:retrieve`. |
| 404    | Not Found             | Cliente ou conta de garantia inexistente, ou endpoint não encontrado.     |
| 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": 404,
  "reason": "RESOURCE_NOT_FOUND",
  "message": "Não foi encontrada nenhuma garantia para o cliente indicado.",
  "path": "/v1/collateral-allocation-management/collateral-allocations/123456/retrieve",
  "errordetail": [
    {
      "code": "COL-404-001",
      "reason": "CUSTOMER_NOT_FOUND",
      "message": "collateralAllocationCustomerReference '123456' não encontrado ou sem garantias associadas."
    }
  ]
}
```

### 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: `COL-404-001`).                       |
| `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 `collateralAllocationCustomerReference` deve corresponder a um cliente activo e existente no sistema. |

***

## 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 `collateral:allocations: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/collateral-allocation-management/retrieve-collateral-allocation-details/main.md?ask=<question>&goal=<user_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.