> 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/customer-position/retrieve-customer-financial-position/main.md).

# Retrieve Customer Financial Position

| Campo              | Valor                                 |
| ------------------ | ------------------------------------- |
| **Service Domain** | Customer Position                     |
| **BIAN Version**   | 14.0.0                                |
| **Operation**      | Customer Financial Position Retrieval |
| **Method**         | GET                                   |
| **API Name**       | Customer Position API                 |
| **Versão**         | Não especificado na página fonte      |
| **Endpoint**       | Não especificado na página fonte      |
| **Autenticação**   | Bearer Token (OAuth 2.0 / OIDC)       |

***

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

O serviço permite consultar a posição financeira consolidada de um cliente, agregando os diferentes produtos e saldos detidos junto do banco numa única resposta.

A posição é organizada em três tipos de carteira (`CustomerPosition[]`):

* **AssetPortfolio** — produtos de ativo do cliente (ex.: Depósito à Ordem, Depósito à Prazo);
* **LiabilityPortfolio** — produtos de passivo/crédito do cliente (ex.: Contas de Crédito Financiamento, Crédito aprovado C/CR);
* **OtherPortfolio** — outros produtos/operações (ex.: Ordens de Financiamento, Operações com o Estrangeiro).

Cada carteira apresenta os saldos por produto (`ProductHoldings`) e o total agregado por moeda (`TotalValues`). A resposta inclui ainda o património líquido do cliente (`NetWorth`), agregado por moeda.

***

## 2. Payload de Resposta (Response)

```json
{
  "CustomerReference": "9012345",
  "CustomerPositionStateType": "Individual",
  "CustomerPositionStateRecord": {
    "PositionDate": "2025-11-20T11:24:00Z",
    "PositionType": "Consolidated",
    "CustomerPosition": [
      {
        "AssetPortfolio": {
          "ProductHoldings": [
            {
              "ProductDescription": "Deposito à Ordem",
              "ProductType": "DO",
              "Values": [
                {
                  "Currency": "AKZ",
                  "Amount": 1958500.25
                },
                {
                  "Currency": "EUR",
                  "Amount": 1958500.25
                }
              ]
            },
            {
              "ProductDescription": "Deposito à Prazo",
              "ProductType": "DP",
              "Values": [
                {
                  "Currency": "AKZ",
                  "Amount": 1958500.25
                },
                {
                  "Currency": "EUR",
                  "Amount": 1958500.25
                }
              ]
            }
          ],
          "TotalValues": [
            {
              "Currency": "AKZ",
              "Amount": 1958500.25
            },
            {
              "Currency": "EUR",
              "Amount": 1958500.25
            }
          ]
        }
      },
      {
        "LiabilityPortfolio": {
          "ProductHoldings": [
            {
              "ProductDescription": "Contas de Crédito Financiamento",
              "ProductType": "CRF",
              "Values": [
                {
                  "Currency": "AKZ",
                  "Amount": -58500.25
                },
                {
                  "Currency": "EUR",
                  "Amount": -1958500.25
                }
              ]
            },
            {
              "ProductDescription": "Crédito aprovado C/CR",
              "ProductType": "CRR",
              "Values": [
                {
                  "Currency": "AKZ",
                  "Amount": -500.25
                },
                {
                  "Currency": "EUR",
                  "Amount": -50025
                }
              ]
            }
          ],
          "TotalValues": [
            {
              "Currency": "AKZ",
              "Amount": -58500.25
            },
            {
              "Currency": "EUR",
              "Amount": -41958525
            }
          ]
        }
      },
      {
        "OtherPortfolio": {
          "ProductHoldings": [
            {
              "ProductDescription": "Ordens de Financiamento",
              "ProductType": "ORD",
              "Values": [
                {
                  "Currency": "AKZ",
                  "Amount": 1958500.25
                },
                {
                  "Currency": "EUR",
                  "Amount": 1958500.25
                }
              ]
            },
            {
              "ProductDescription": "Opr. Estrangeiro",
              "ProductType": "EXT",
              "Values": [
                {
                  "Currency": "AKZ",
                  "Amount": 1958500.25
                },
                {
                  "Currency": "EUR",
                  "Amount": 1958500.25
                }
              ]
            }
          ],
          "TotalValues": [
            {
              "Currency": "AKZ",
              "Amount": 1958500.25
            },
            {
              "Currency": "EUR",
              "Amount": 95850
            }
          ]
        }
      }
    ],
    "NetWorth": [
      {
        "Currency": "AKZ",
        "Amount": 1958500.25
      },
      {
        "Currency": "EUR",
        "Amount": -500.25
      }
    ]
  }
}
```

### 2.1 Objecto Raiz

| Campo                         | Tipo   | Descrição                                                             |
| ----------------------------- | ------ | --------------------------------------------------------------------- |
| `CustomerReference`           | string | Identificador único do cliente.                                       |
| `CustomerPositionStateType`   | string | Tipo de posição do cliente (ex.: `Individual`).                       |
| `CustomerPositionStateRecord` | object | Registo consolidado da posição financeira do cliente. Ver secção 2.2. |

### 2.2 Objecto: `CustomerPositionStateRecord`

| Campo              | Tipo                       | Descrição                                                                                                                                                   |
| ------------------ | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PositionDate`     | string (ISO 8601 datetime) | Data e hora de referência em que a posição foi apurada.                                                                                                     |
| `PositionType`     | string                     | Tipo de posição (ex.: `Consolidated`).                                                                                                                      |
| `CustomerPosition` | array                      | Lista de carteiras (portfolios) do cliente. Cada elemento contém um dos objetos `AssetPortfolio`, `LiabilityPortfolio` ou `OtherPortfolio`. Ver secção 2.3. |
| `NetWorth`         | array                      | Património líquido do cliente, por moeda. Ver secção 2.4.                                                                                                   |

### 2.3 Objecto: `CustomerPosition[]` — `AssetPortfolio` / `LiabilityPortfolio` / `OtherPortfolio`

| Campo                | Tipo   | Descrição                                                                                                         |
| -------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
| `AssetPortfolio`     | object | Carteira de produtos de ativo do cliente (ex.: Depósito à Ordem, Depósito à Prazo).                               |
| `LiabilityPortfolio` | object | Carteira de produtos de passivo/crédito do cliente (ex.: Contas de Crédito Financiamento, Crédito aprovado C/CR). |
| `OtherPortfolio`     | object | Carteira de outros produtos/operações do cliente (ex.: Ordens de Financiamento, Operações com o Estrangeiro).     |
| `*.ProductHoldings`  | array  | Lista de produtos detidos nesta carteira. Ver secção 2.4.                                                         |
| `*.TotalValues`      | array  | Total agregado desta carteira, por moeda. Mesma estrutura de `Values[]` (secção 2.5).                             |

### 2.4 Objecto: `ProductHoldings[]`

| Campo                | Tipo   | Descrição                                                                          |
| -------------------- | ------ | ---------------------------------------------------------------------------------- |
| `ProductDescription` | string | Descrição do produto (ex.: `Deposito à Ordem`, `Contas de Crédito Financiamento`). |
| `ProductType`        | string | Código do tipo de produto (ex.: `DO`, `DP`, `CRF`, `CRR`, `ORD`, `EXT`).           |
| `Values`             | array  | Saldo do produto por moeda. Ver secção 2.5.                                        |

### 2.5 Objecto: `Values[]` / `TotalValues[]` / `NetWorth[]`

| Campo      | Tipo              | Descrição                                                                            |
| ---------- | ----------------- | ------------------------------------------------------------------------------------ |
| `Currency` | string (ISO 4217) | Código da moeda (ex.: `AKZ`, `EUR`).                                                 |
| `Amount`   | decimal           | Montante na moeda indicada. Valores negativos representam saldos de passivo/crédito. |