Pular para conteúdo

Serviço do BACEN

Algumas APIs gratuitas de câmbio bloqueiam requisições vindas de provedores de nuvem: o serviço responde no seu notebook e falha quando roda na AWS. A PTAX do Banco Central do Brasil (BCB) é uma API pública, sem chave nem cadastro, que cota as principais moedas em reais (BRL). Esta página traz o microsserviço de câmbio inteiro, em Python com FastAPI, apoiado na PTAX: a sua parte é o contêiner e a integração dele à plataforma.

Objetivos de aprendizagem

Ao final desta página você deve ser capaz de:

  • Conteinerizar um serviço Python gerenciado pelo uv, com um arquivo de lock reprodutível.
  • Integrar um novo microsserviço à pilha do Compose e atrás do gateway.
  • Explicar como uma taxa cruzada (USD → EUR) sai de cotações que estão todas em BRL.

Opcional

Usar este serviço é uma opção do exercício API de Câmbio: você ainda pode escrever o seu próprio serviço sobre qualquer API de terceiros. Se escolher este, informe no README do seu repositório.

Como funciona

O gateway descobre quem está chamando e repassa a requisição com o header id-account. O serviço pede à PTAX a última cotação de cada moeda em BRL (os últimos 7 dias, pois fins de semana e feriados não têm cotação), guarda-a em memória por 5 minutos e divide uma pela outra. Só uma requisição por moeda atualiza o cache de cada vez: as outras esperam por ela em vez de chamarem todas juntas o BCB. Quando a PTAX falha e há uma taxa antiga em memória, o serviço responde com ela.

sequenceDiagram
    participant G as gateway
    participant E as exchange
    participant P as PTAX (BCB)
    G->>E: GET /exchange/USD/EUR + id-account
    E->>P: CotacaoMoedaPeriodo USD, últimos 7 dias
    P-->>E: compra/venda em BRL, todos os boletins
    E->>P: CotacaoMoedaPeriodo EUR, últimos 7 dias
    P-->>E: compra/venda em BRL, todos os boletins
    E->>E: taxa cruzada via BRL, cache de 5 min
    E-->>G: {"sell", "buy", "date", "id-account"}

A PTAX só cota contra o real, então USD → EUR passa pelo BRL. Com \(c\) (compra) e \(v\) (venda) as cotações da PTAX em BRL:

\[ \text{buy} = \frac{c_\text{USD}}{v_\text{EUR}} \qquad\qquad \text{sell} = \frac{v_\text{USD}}{c_\text{EUR}} \]

buy é quanto o mercado paga por 1 USD, em euros (ele compra os seus dólares e vende euros a você); sell é quanto ele cobra. O próprio BRL vale 1, então GET /exchange/USD/BRL é a cotação PTAX do dólar.

O projeto

exchange/
├── pyproject.toml
├── uv.lock          # created by uv lock: commit it
└── main.py
1
2
3
4
5
6
7
8
9
[project]
name = "exchange"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "fastapi>=0.115",
    "httpx>=0.27",
    "uvicorn[standard]>=0.30",
]
"""Exchange service: currency rates from the Central Bank of Brazil (PTAX)."""

import asyncio
import os
import time
from collections import defaultdict
from contextlib import asynccontextmanager
from datetime import date, timedelta

import httpx
from fastapi import FastAPI, Header, HTTPException, Response

PTAX_URL = os.getenv("PTAX_URL", "https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/odata")
PTAX_TIMEOUT = float(os.getenv("PTAX_TIMEOUT", "3"))  # seconds: never wait longer than the caller would
CACHE_SECONDS = float(os.getenv("CACHE_SECONDS", "300"))  # PTAX publishes a few bulletins a day
RETRY_SECONDS = float(os.getenv("RETRY_SECONDS", "30"))  # after a failed refresh, serve stale this long
# currency -> (valid until, quote, how a request served from it is labelled: "hit" or "stale")
_cache: dict[str, tuple[float, dict, str]] = {}
_locks: defaultdict[str, asyncio.Lock] = defaultdict(asyncio.Lock)


@asynccontextmanager
async def lifespan(app: FastAPI):
    async with httpx.AsyncClient(timeout=PTAX_TIMEOUT) as client:
        app.state.client = client
        yield


app = FastAPI(title="exchange", lifespan=lifespan)


async def brl_quote(currency: str) -> tuple[dict, str]:
    """Latest PTAX quote of a currency in BRL ({"buy", "sell", "date"}) and where it came from."""
    if currency == "BRL":
        return {"buy": 1.0, "sell": 1.0, "date": None}, "hit"
    cached = _cache.get(currency)
    if cached and time.monotonic() < cached[0]:
        return cached[1], cached[2]
    # one refresh per currency at a time: the requests that arrive meanwhile wait for it
    # instead of all calling PTAX together (a stampede on a provider we do not own)
    async with _locks[currency]:
        cached = _cache.get(currency)
        if cached and time.monotonic() < cached[0]:
            return cached[1], cached[2]
        return await _refresh(currency, cached)


async def _refresh(currency: str, cached: tuple[float, dict, str] | None) -> tuple[dict, str]:
    # a 7-day window always holds a business day (weekends and holidays have no PTAX)
    end = date.today()
    start = end - timedelta(days=7)
    url = (
        f"{PTAX_URL}/CotacaoMoedaPeriodo(moeda=@moeda,dataInicial=@dataInicial,dataFinalCotacao=@dataFinalCotacao)"
        f"?@moeda='{currency}'&@dataInicial='{start:%m-%d-%Y}'&@dataFinalCotacao='{end:%m-%d-%Y}'"
        "&$format=json&$select=cotacaoCompra,cotacaoVenda,dataHoraCotacao"
    )
    try:
        response = await app.state.client.get(url)
        response.raise_for_status()
        rows = response.json()["value"]
    except (httpx.HTTPError, KeyError, ValueError) as e:
        if cached:  # BCB is slow, down or blocking us: an old rate beats an error
            _cache[currency] = (time.monotonic() + RETRY_SECONDS, cached[1], "stale")
            return cached[1], "stale"
        raise HTTPException(status_code=502, detail=f"PTAX unavailable: {e!r}") from e
    if not rows:
        raise HTTPException(status_code=404, detail=f"Unknown currency: {currency}")

    last = rows[-1]  # rows come in time order: the latest bulletin is the last one
    quote = {
        "buy": last["cotacaoCompra"],
        "sell": last["cotacaoVenda"],
        "date": last["dataHoraCotacao"][:19],
    }
    _cache[currency] = (time.monotonic() + CACHE_SECONDS, quote, "hit")
    return quote, "miss"


@app.get("/exchange/{source}/{target}")
@app.get("/exchanges/{source}/{target}", include_in_schema=False)
async def exchange(
    source: str,
    target: str,
    response: Response,
    id_account: str = Header(alias="id-account"),
):
    """Rate to convert 1 unit of `source` into `target` (e.g. USD → EUR)."""
    src, src_from = await brl_quote(source.upper())
    tgt, tgt_from = await brl_quote(target.upper())
    # X-Cache: miss if PTAX was called, stale if an expired rate was served, hit otherwise
    froms = {src_from, tgt_from}
    response.headers["X-Cache"] = "miss" if "miss" in froms else "stale" if "stale" in froms else "hit"
    # PTAX quotes every currency in BRL, so the cross rate goes through BRL:
    # buy  = what the market pays for 1 `source`, in `target` (it buys source, sells target)
    # sell = what the market charges for 1 `source`, in `target` (it sells source, buys target)
    return {
        "sell": round(src["sell"] / tgt["buy"], 6),
        "buy": round(src["buy"] / tgt["sell"], 6),
        "date": src["date"] or tgt["date"],
        "id-account": id_account,
    }


@app.get("/exchange/currencies")
async def currencies():
    """Currencies PTAX quotes (besides BRL)."""
    try:
        response = await app.state.client.get(f"{PTAX_URL}/Moedas?$format=json&$select=simbolo,nomeFormatado")
        response.raise_for_status()
    except httpx.HTTPError as e:
        raise HTTPException(status_code=502, detail=f"PTAX unavailable: {e!r}") from e
    return [{"symbol": m["simbolo"], "name": m["nomeFormatado"]} for m in response.json()["value"]]


@app.get("/health")
async def health():
    return {"status": "ok"}
Endpoint Retorna
GET /exchange/{from}/{to} a taxa de uma moeda para outra (também responde em /exchanges/..., como o enunciado do exercício escreve)
GET /exchange/currencies as moedas que a PTAX cota, além do BRL
GET /health {"status": "ok"}, para o health check do contêiner

Toda resposta de taxa traz o header X-Cache: miss (a PTAX foi chamada), hit (taxa da memória) ou stale (a PTAX falhou e uma taxa vencida foi servida). As configurações vêm de variáveis de ambiente, então o contêiner as muda sem uma nova imagem:

Variável Padrão O que define
PTAX_URL o endereço do BCB URL base da API PTAX
PTAX_TIMEOUT 3 segundos de espera pela PTAX
CACHE_SECONDS 300 por quanto tempo uma taxa é reutilizada antes de perguntar de novo à PTAX
RETRY_SECONDS 30 depois de uma chamada que falhou, por quanto tempo a taxa antiga é servida antes de tentar de novo

Rode localmente

Na pasta exchange/:

uv lock                                   # creates uv.lock from pyproject.toml
uv run uvicorn main:app --reload --port 8000

Em outro terminal:

curl -H "id-account: 0195ae95-5be7-7dd3-b35d-7a7d87c404fb" localhost:8000/exchange/USD/EUR

Você deve ver algo como:

{"sell":0.906885,"buy":0.9066,"date":"2026-11-13 13:03:27","id-account":"0195ae95-5be7-7dd3-b35d-7a7d87c404fb"}

O date é o boletim da PTAX usado: num fim de semana ou antes das 10h (Brasília) é o último dia útil. Sem o header o serviço responde 422; uma moeda desconhecida (/exchange/XYZ/BRL) responde 404.

Sua tarefa: o contêiner

  1. Escreva o Dockerfile do serviço:
    • imagem base python:3.12-slim, com o binário uv copiado de ghcr.io/astral-sh/uv1;
    • copie pyproject.toml e uv.lock antes do main.py e rode uv sync --frozen, para que uma mudança no código não reinstale as dependências;
    • inicie uvicorn main:app em 0.0.0.0:8000.
  2. Adicione o serviço exchange ao compose.yaml da plataforma (sem porta publicada: só o gateway chega até ele).
  3. Adicione a rota do gateway Path=/exchange/** → http://exchange:8000, atrás da autenticação como as outras rotas de negócio.
  4. Verifique pelo gateway: faça login e então GET /exchange/USD/EUR com o token devolve a taxa e o seu id-account.
  5. Na nuvem: de um pod do cluster, rode curl na URL da PTAX uma vez para confirmar que o provedor responde a partir da AWS.

Limites da PTAX

  • Só há cotação em dias úteis, entre cerca de 10h e 13h (Brasília); fora dessa janela o serviço devolve o último boletim.
  • O cache vive na memória do processo: um contêiner reiniciado pergunta de novo à PTAX e, se o BCB não responder e não houver taxa em cache, o serviço responde 502.
  • A PTAX é um serviço público do BCB: não faça teste de carga nela. Mantenha o cache ligado; um teste de carga contra o seu gateway deve causar só algumas chamadas à PTAX (conte os X-Cache: miss).