> 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/currency-exchange/retrieve-current-exchange-rates/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 |


---

# 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 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/currency-exchange/retrieve-current-exchange-rates/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 `automate deployments from our CI pipeline` 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.