> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversão de moeda

> O endpoint `convert` converte montantes específicos entre moedas com taxas de câmbio em tempo real — ideal para cálculos financeiros e processamento de pagamentos.

## Primeiros passos

### URL base

```
https://exchange-rates.cleariflow.com/v1/convert
```

### Endpoint de validação

O endpoint `convert` requer a sua chave API, uma moeda base e um parâmetro target para realizar conversões de moeda.

```
https://exchange-rates.cleariflow.com/v1/convert
? api_key = YOUR_UNIQUE_API_KEY
& base = EUR
& target = USD
```

Este pedido bem-sucedido converte 1 EUR para USD utilizando a taxa de câmbio mais atual:

<ResponseExample>
  ```json theme={"system"}
  {
      "base": "EUR",
      "target": "USD",
      "base_amount": 1,
      "converted_amount": 1.160968,
      "exchange_rate": 1.160968,
      "last_updated": 1755806612
  }
  ```
</ResponseExample>

### Parâmetros de pedido

<ParamField query="api_key" type="String" required>
  A sua chave API única. Note que cada utilizador tem chaves API únicas *para cada uma das
  APIs Cleariflow* — a sua chave da API de taxas de câmbio não funcionará para a API de
  geolocalização IP, por exemplo.
</ParamField>

<ParamField query="base" type="String" required>
  A moeda base utilizada para obter a(s) taxa(s) de câmbio mais recente(s). Utiliza o padrão de moeda ISO 4217 (por exemplo, USD para dólares americanos), como todos os parâmetros de moeda nesta API.
</ParamField>

<ParamField query="target" type="String" required>
  A moeda de destino para obter a taxa de câmbio face à moeda base. Como os parâmetros base, qualquer moeda passada aqui segue o padrão ISO 4217. Note que, ao contrário dos outros endpoints, `convert` aceita apenas uma moeda de destino de cada vez.
</ParamField>

<ParamField query="date" type="String">
  A data histórica da qual pretende obter taxas, no formato AAAA-MM-DD. Se deixar este campo em branco, serão utilizadas as taxas mais recentes disponíveis.
</ParamField>

<ParamField query="base_amount" type="Float">
  O montante da moeda base que pretende converter para a moeda de destino.
</ParamField>

### Parâmetros de resposta

A resposta da API é devolvida num [formato JSON](https://www.json.org/json-en.html) universal e leve.

<ResponseField name="base" type="String">
  A moeda base utilizada para obter as taxas de câmbio.
</ResponseField>

<ResponseField name="target" type="String">
  A moeda de destino para a qual o `base_amount` foi convertido.
</ResponseField>

<ResponseField name="date" type="String">
  A data de origem das moedas, conforme o pedido bem-sucedido.
</ResponseField>

<ResponseField name="base_amount" type="Float">
  O montante da moeda base do pedido.
</ResponseField>

<ResponseField name="converted_amount" type="Float">
  O montante da moeda de destino para o qual o `base_amount` foi convertido.
</ResponseField>

<ResponseField name="exchange_rate" type="Float">
  A taxa de câmbio utilizada para converter o `base_amount` da moeda base para a moeda de destino.
</ResponseField>