Pular para conteúdo

Serviço do BACEN

O serviço de câmbio do exercício 8, pronto para rodar: Python com FastAPI, apoiado na PTAX do Banco Central do Brasil (BCB). A PTAX é uma API pública, sem chave nem cadastro, que cota as principais moedas em reais (BRL). Algumas APIs gratuitas de câmbio bloqueiam requisições vindas de provedores de nuvem; a PTAX é a padrão aqui porque não exige conta, mas continua sendo um provedor que não é seu, e o exercício trata justamente de conviver com isso.

Objetivos de aprendizagem

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

  • Ler um serviço pequeno que chama um provedor externo através de um cache, um timeout e um fallback com taxa vencida.
  • Explicar como uma taxa cruzada (USD → EUR) sai de cotações que estão todas em BRL.
  • Rodar o serviço com o uv e ler o header X-Cache de cada resposta.

Como funciona

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 CACHE_SECONDS 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 e só tenta de novo depois de RETRY_SECONDS.

sequenceDiagram
    participant G as gateway
    participant E as exchange
    participant P as PTAX (BCB)
    G->>E: GET /exchange/USD/EUR
    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, guarda as duas cotações
    E-->>G: 200 taxa, X-Cache miss
    G->>E: GET /exchange/USD/EUR (dentro de CACHE_SECONDS)
    E-->>G: 200 taxa, X-Cache hit (PTAX não chamada)

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.

Peça O que ela protege
Cache de CACHE_SECONDS (300) por moeda A PTAX publica poucos boletins por dia: milhares de fãs pedindo a taxa custam poucas chamadas
Uma atualização por moeda de cada vez (asyncio.Lock) Um cache frio ou vencido sob carga não vira uma rajada de chamadas idênticas ao provedor
Timeout de PTAX_TIMEOUT (3 s) Um provedor lento não segura uma requisição por mais tempo do que um fã esperaria
Taxa vencida por RETRY_SECONDS (30) depois de uma falha O provedor caiu ou está nos bloqueando: uma taxa antiga é melhor que um erro e não tentamos de novo a cada requisição
X-Cache: miss / hit / stale Dá para contar, de fora, quantas vezes o provedor foi chamado e quantas vezes falhou

O projeto

No repositório do BoxOffice o serviço fica em services/exchange/:

services/exchange/
├── pyproject.toml
├── uv.lock          # created by uv lock: commit it
├── main.py
└── Dockerfile       # your part (exercise 8, step 2)
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, 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}")
async def exchange(source: str, target: str, response: Response):
    """Rate to convert 1 unit of `source` into `target` (e.g. USD → EUR)."""
    source, target = source.upper(), target.upper()
    src, src_from = await brl_quote(source)
    tgt, tgt_from = await brl_quote(target)
    # 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 {
        "from": source,
        "to": target,
        "sell": round(src["sell"] / tgt["buy"], 6),
        "buy": round(src["buy"] / tgt["sell"], 6),
        "date": src["date"] or tgt["date"],
    }


@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, com o header X-Cache
GET /exchange/currencies as moedas que a PTAX cota, além do BRL
GET /health {"status": "ok"}, para o health check do contêiner

As configurações vêm de variáveis de ambiente, então o Compose ou o Kubernetes as mudam 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

Em services/exchange/:

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

Em outro terminal, duas vezes:

curl -i localhost:8000/exchange/USD/EUR

Você deve ver x-cache: miss na primeira resposta e x-cache: hit na segunda, com o mesmo corpo:

{"from":"USD","to":"EUR","sell":0.906885,"buy":0.9066,"date":"2026-11-13 13:03:27"}

O date é o boletim da PTAX usado: num fim de semana ou antes das 10h (Brasília) é o último dia útil. Uma moeda desconhecida (/exchange/XYZ/BRL) responde 404; a PTAX inacessível sem nada em memória responde 502.

A PTAX não é sua para teste de carga

  • 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.
  • A PTAX é um serviço público do BCB, compartilhado por todos os alunos da turma. Nunca rode um teste de carga com o cache desligado (CACHE_SECONDS=0): uma execução do k6 a 100 requisições/s mandaria ao BCB 200 chamadas por segundo, e um provedor que vê isso vindo de um endereço o bloqueia. Com o cache ligado, a execução inteira do exercício 8 custa poucas chamadas.