> 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/service-domain/currency-exchange/operacoes/main.md).

# Retrieve Current Exchange Rates

| Campo          | Valor                           |
| -------------- | ------------------------------- |
| Service Domain | Currency Exchange               |
| BIAN Version   | 14.0.0                          |
| Operation      | Retrieve Current Exchange Rates |
| Method         | GET                             |
| API Name       | Currency Exchange               |
| Versão         | v1.0.0                          |

## 1. Descrição da API

A API Currency Exchange permite consultar as taxas de câmbio (FX Rates) atuais entre moedas, suportando operações de compra e venda.

A API fornece:

* Taxas de câmbio em tempo quase real
* Taxas de compra (`Buy Rate`)
* Taxas de venda (`Sell Rate`)
* Período de validade da cotação
* Múltiplas moedas por requisição

Esta API segue o modelo do Service Domain `Current Exchange` do BIAN.

| Campo       | Valor                            |
| ----------- | -------------------------------- |
| Endpoint    | `GET /v1/current-exchange/rates` |
| Método HTTP | GET                              |

## 2. Cabeçalhos HTTP

| Header          | Tipo   | Obrigatório | Descrição                     |
| --------------- | ------ | ----------- | ----------------------------- |
| `Authorization` | string | Sim         | Bearer Token                  |
| `Content-Type`  | string | Sim         | `application/json`            |
| `Accept`        | string | Sim         | `application/json`            |
| `x-request-id`  | string | Não         | Identificador único do pedido |

### 2.1 Autenticação

A API utiliza autenticação via Bearer Token (OAuth2 / JWT).

**Exemplo:**

```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

## 3. Parâmetros do Pedido (Request)

### 3.1 Query Parameters

| Parâmetro       | Tipo     | Obrigatório | Descrição                                      |
| --------------- | -------- | ----------- | ---------------------------------------------- |
| `baseCurrency`  | string   | Não         | Moeda base (ex: `USD`)                         |
| `quoteCurrency` | string   | Não         | Moeda destino (ex: `AOA`)                      |
| `referenceDate` | DateTime | Não         | Data de referência                             |
| `page`          | integer  | Não         | Página                                         |
| `size`          | integer  | Não         | Quantidade de elementos a retornar na resposta |

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

### 4.1 Exemplo

```json
{
    "currencyExchangeProcedure": {
        "currencyExchangeProcedureParameterType": "CurrencyExchangeFeature",
        "fxQuote": {
            "exchangeRates": [
                {
                    "currencyCode": "AED",
                    "quoteCurrencyCode": "AOA",
                    "ratePeriod": {
                        "FromDateTime": "2026-06-08T07:23:38",
                        "ToDateTime": "2026-06-08T07:24:38"
                    },
                    "BuyRate": 132.389,
                    "SellRate": 141.673
                },
                {
                    "currencyCode": "ARS",
                    "quoteCurrencyCode": "AOA",
                    "ratePeriod": {
                        "FromDateTime": "2026-06-08T07:23:38",
                        "ToDateTime": "2026-06-08T07:24:38"
                    },
                    "BuyRate": 3.425,
                    "SellRate": 3.665
                },
                {
                    "currencyCode": "BOB",
                    "quoteCurrencyCode": "AOA",
                    "ratePeriod": {
                        "FromDateTime": "2026-06-08T07:23:37",
                        "ToDateTime": "2026-06-08T07:24:37"
                    },
                    "BuyRate": 60.245,
                    "SellRate": 64.47
                },
                {
                    "currencyCode": "BRL",
                    "quoteCurrencyCode": "AOA",
                    "ratePeriod": {
                        "FromDateTime": "2026-06-08T07:23:37",
                        "ToDateTime": "2026-06-08T07:24:37"
                    },
                    "BuyRate": 77.678,
                    "SellRate": 83.125
                }
            ]
        }
    },
    "pagination": {
        "page": 0,
        "size": 10,
        "total": 23,
        "totalPages": 3
    }
}
```

### 4.2 Descrição dos Campos

| Campo                       | Tipo    | Descrição                                      |
| --------------------------- | ------- | ---------------------------------------------- |
| `currencyExchangeProcedure` | object  | Processo de câmbio                             |
| `fxQuote`                   | object  | Cotação                                        |
| `exchangeRates`             | array   | Lista de taxas                                 |
| `currencyCode`              | string  | Moeda base                                     |
| `quoteCurrencyCode`         | string  | Moeda de cotação                               |
| `buyRate`                   | decimal | Taxa de compra                                 |
| `sellRate`                  | decimal | Taxa de venda                                  |
| `ratePeriod`                | object  | Período de validade                            |
| `pagination`                | object  | Elementos de paginação                         |
| `pagination.page`           | integer | Página                                         |
| `pagination.size`           | integer | Quantidade de elementos a retornar na resposta |
| `pagination.total`          | integer | Total de elementos                             |
| `pagination.totalPages`     | integer | Total de páginas                               |

### 4.3 Tabela de Objetos e Cardinalidade

| Objeto                      | Campo                       | Tipo    | Cardinalidade | Descrição      |
| --------------------------- | --------------------------- | ------- | ------------- | -------------- |
| `currencyExchange`          | `currencyExchangeProcedure` | object  | 1..1          | Processo       |
| `currencyExchangeProcedure` | `fxQuote`                   | object  | 1..1          | Cotação        |
| `fxQuote`                   | `exchangeRates`             | array   | 1..n          | Lista de taxas |
| `exchangeRate`              | `currencyCode`              | string  | 1..1          | Moeda base     |
| `exchangeRate`              | `quoteCurrencyCode`         | string  | 1..1          | Moeda destino  |
| `exchangeRate`              | `buyRate`                   | decimal | 1..1          | Compra         |
| `exchangeRate`              | `sellRate`                  | decimal | 1..1          | Venda          |
| `exchangeRate`              | `ratePeriod`                | object  | 1..1          | Validade       |

### 4.4 Tipos de Taxa

| Tipo       | Descrição                                |
| ---------- | ---------------------------------------- |
| `BuyRate`  | Taxa usada pelo banco para comprar moeda |
| `SellRate` | Taxa usada pelo banco para vender moeda  |

## 5. Códigos HTTP de Resposta

| Código | Descrição           |
| ------ | ------------------- |
| 200    | Sucesso             |
| 400    | Pedido inválido     |
| 401    | Não autorizado      |
| 403    | Proibido            |
| 404    | Taxa não encontrada |
| 500    | Erro interno        |

## 6. Cenários de Utilização

### 6.1 Consulta de Taxas FX

* Cliente consulta taxas no mobile banking
* API retorna taxas atualizadas

### 6.2 Pagamentos Internacionais

* Sistema usa taxa antes de conversão

### 6.3 Tesouraria

* Monitoramento de taxas

## 7. Cenários de Erro Comuns

### 7.1 Token Inválido

```json
{
  "error": {
    "status": 400,
    "reason": "INVALID_VALUE",
    "message": "Invalid Srci-Client Id",
    "path": "GET /v1/currency-exchange/533610002/FXQuote/56464/retrieve",
    "errordetail": [
      {
        "code": "123332",
        "reason": "INVALID_VALUE",
        "message": "Invalid Srci-Client Id"
      }
    ]
  }
}
```

### 7.2 Erro Interno

```json
{
  "error": {
    "status": 500,
    "reason": "INVALID_STATE",
    "message": "Internal server error. Typically a server bug. The client should report this error to the Mastercard support team",
    "path": "GET /v1/currency-exchange/533610002/FXQuote/56464/retrieve"
  }
}
```

## 8. Fluxo Sequencial

1. Cliente envia request
2. API valida token
3. API valida filtros
4. API consulta core banking
5. API retorna depósitos

## 9. Regras de Negócio

* Moedas devem ser válidas (ISO 4217)
* Taxas devem ter período de validade
* Apenas taxas ativas devem ser retornadas

## 10. Validações

| Campo | Regra                                          |
| ----- | ---------------------------------------------- |
| Moeda | Código válido (ex: `USD`, `EUR`, `GBP`, `AOA`) |
| Datas | Deve estar dentro do período válido            |

## 11. Segurança

* HTTPS obrigatório
* Bearer Token obrigatório
* Logging obrigatório
* Auditoria obrigatória

## 12. Mapeamento BIAN

| BIAN                        | API           |
| --------------------------- | ------------- |
| `CurrencyExchangeProcedure` | FX Process    |
| `FXQuote`                   | FXQuote       |
| `ExchangeRate`              | ExchangeRates |