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

# Initiate Collateral Allocation

| Campo            | Valor                                                           |
| ---------------- | --------------------------------------------------------------- |
| **Operation**    | Initiate Collateral Allocation                                  |
| **Method**       | POST                                                            |
| **API Name**     | Collateral Allocation Management API                            |
| **Versão**       | v1.0.0                                                          |
| **Endpoint**     | `POST /v1/collateral-allocation-management/allocation/initiate` |
| **Autenticação** | Bearer Token (OAuth 2.0 / OIDC)                                 |

***

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

O serviço **Initiate Collateral Allocation** permite associar uma conta garantia a uma conta de crédito existente, definindo a percentagem do valor a alocar como garantia.

A operação:

* Vincula uma **conta garantia** (`collateralAccountIdentification`) a uma **conta de crédito** (`creditAccountIdentification`).
* Define a **percentagem de alocação** (`collateralAllocationRate`) que representa a fracção do valor da garantia aplicada ao contrato de crédito.
* O campo `overdraftLimitIndicator` indica se a garantia está relacionada com um limite de descoberto.

***

## 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. Payload de Pedido (Request)

### 3.1 Exemplo

```json
{
  "collateralAllocationManagement": {
      "collateralAccountIdentification": {
          "identifierValue": {
            "value": "{{Collateral-Account-Identification}}"
          }
      },
      "creditAccountIdentification": {
          "identifierValue": {
              "value": "{{Credit-Account-Identification}}"
          }
      },
      "overdraftLimitIndicator": false,           
      "collateralAllocationRate": {
          "rateValue": 11,
          "rateDescription": "PercentageToAllocate"
      }
  }
}
```

### 3.2 Objecto Raiz: `collateralAllocationManagement`

| Campo                             | Tipo    | Obrigatório | Descrição                                                       |
| --------------------------------- | ------- | ----------- | --------------------------------------------------------------- |
| `collateralAccountIdentification` | object  | Sim         | Identificador da conta garantia a associar.                     |
| `creditAccountIdentification`     | object  | Sim         | Identificador da conta de crédito que receberá a nova garantia. |
| `overdraftLimitIndicator`         | boolean | Sim         | Indica se a garantia está associada a um limite de descoberto.  |
| `collateralAllocationRate`        | object  | Sim         | Define a percentagem do valor da garantia a alocar.             |

### 3.3 Objecto: `collateralAccountIdentification`

| Campo                   | Tipo   | Obrigatório | Descrição                              |
| ----------------------- | ------ | ----------- | -------------------------------------- |
| `identifierValue.value` | string | Sim         | Identificador único da conta garantia. |

### 3.4 Objecto: `creditAccountIdentification`

| Campo                   | Tipo   | Obrigatório | Descrição                                                               |
| ----------------------- | ------ | ----------- | ----------------------------------------------------------------------- |
| `identifierValue.value` | string | Sim         | Identificador único da conta de crédito à qual a garantia será alocada. |

### 3.5 Objecto: `collateralAllocationRate`

| Campo             | Tipo    | Obrigatório | Descrição                                                                                                       |
| ----------------- | ------- | ----------- | --------------------------------------------------------------------------------------------------------------- |
| `rateValue`       | decimal | Sim         | Percentagem de alocação da garantia. Exemplo: `11` representa 11%. Deve ser maior que 0 e menor ou igual a 100. |
| `rateDescription` | string  | Não         | Descrição textual da taxa. Valor esperado: `"PercentageToAllocate"`.                                            |

***

## 4. Payload de Resposta (Response — 204 No Content)

Em caso de sucesso, o serviço não retorna corpo de dados; o retorno é vazio.

***

## 5. Códigos HTTP de Resposta

| Código | Estado                | Descrição                                                                                                                |
| ------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| 204    | No Content            | Garantia alocada com sucesso. Nenhum conteúdo é retornado no corpo da resposta.                                          |
| 400    | Bad Request           | Payload inválido: campos obrigatórios em falta, percentagem fora do intervalo válido ou contas inexistentes.             |
| 401    | Unauthorized          | Token ausente, expirado ou inválido.                                                                                     |
| 403    | Forbidden             | Cliente autenticado mas sem scope para `collateral:allocation:initiate`.                                                 |
| 404    | Not Found             | `collateralAccountIdentification` ou `creditAccountIdentification` não encontrados.                                      |
| 409    | Conflict              | Garantia já alocada anteriormente para o mesmo par conta garantia / conta de crédito.                                    |
| 422    | Unprocessable Entity  | Regra de negócio violada: percentagem excede o limite permitido, conta inactiva, ou conta garantia sem valor disponível. |
| 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": 422,
  "reason": "BUSINESS_RULE_VIOLATION",
  "message": "A percentagem de alocação excede o limite permitido para a conta garantia.",
  "path": "/v1/collateral-allocation-management/initiate",
  "errors": [
    {
      "code": "CAM-422-001",
      "reason": "ALLOCATION_RATE_EXCEEDED",
      "message": "Conta garantia 987654321001: percentagem solicitada 110% > máximo permitido 100%."
    }
  ]
}
```

### 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.: `CAM-422-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 | **Existência das Contas** | Tanto `collateralAccountIdentification` como `creditAccountIdentification` devem existir e estar activas no sistema.                     |
| 2 | **Percentagem Válida**    | `rateValue` deve ser maior que `0` e menor ou igual a `100`. Valores fora deste intervalo resultam em erro `422`.                        |
| 3 | **Unicidade da Alocação** | Não é permitida a duplicação de uma alocação para o mesmo par conta garantia / conta de crédito. Uma alocação existente resulta em erro. |

***

## 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:allocation:initiate`. Pedidos sem token ou com token inválido retornam `401`. |
| **Auditoria**    | Registo persistente obrigatório de todas as execuções (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 current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://selenium-4.gitbook.io/nexus-docs/docs/collateral-allocation-management/initiate-collateral-allocation/main.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.