API PTAX do Banco Central: por que a cotação vem vazia

1 Chame a função do dia

Os recursos de cotação são funções OData: o nome tem parênteses e o valor de cada parâmetro vai em outro lugar da URL, como alias com @. A data tem três regras: formato MM-DD-AAAA, entre aspas simples, e o mês vem primeiro.

curl -s "https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/odata/CotacaoDolarDia(dataCotacao=@dataCotacao)?@dataCotacao='11-06-2026'&\$format=json"

{"value":[{"cotacaoCompra":5.50070,"cotacaoVenda":5.50130,"dataHoraCotacao":"2026-11-06 13:06:13.966362"}]}

dataHoraCotacao vem como texto, com a hora do fechamento. Os números vêm como número, não como texto.

2 Dia sem cotação: volte ao dia útil anterior

Peça a PTAX de um sábado, de um feriado ou de uma data futura e a resposta é 200 com "value":[]. Não é erro: é a API dizendo que não há boletim naquele dia.

Quem precisa da "PTAX vigente" (um contrato que pede a PTAX do dia útil anterior, por exemplo) resolve voltando dia a dia até achar uma cotação. Este script foi executado em 07/11/2026, um sábado:

import json, time, urllib.error, urllib.request
from datetime import date, timedelta

BASE = "https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/odata"

def baixar(url, tentativas=3):
    for n in range(1, tentativas + 1):
        try:
            with urllib.request.urlopen(url, timeout=60) as r:
                return json.loads(r.read())["value"]
        except urllib.error.HTTPError as e:
            if e.code in (502, 503, 504) and n < tentativas:
                time.sleep(5 * n)
                continue
            raise

def mmddaaaa(d):                       # a PTAX quer MM-DD-AAAA, e a data vai entre aspas simples
    return d.strftime("%m-%d-%Y")

def dolar_dia(d):
    url = (f"{BASE}/CotacaoDolarDia(dataCotacao=@dataCotacao)"
           f"?@dataCotacao='{mmddaaaa(d)}'&$format=json")
    return baixar(url)                 # lista vazia = fim de semana, feriado ou data futura (não é erro)

def ptax_do_dia_ou_anterior(d, limite=10):
    for volta in range(limite):
        achou = dolar_dia(d - timedelta(days=volta))
        if achou:
            return d - timedelta(days=volta), achou[0]
    raise RuntimeError(f"nenhuma cotação nos {limite} dias até {d}")

dia, cot = ptax_do_dia_ou_anterior(date(2026, 11, 7))        # sábado
print("pedido 07/11/2026 (sábado) ->", dia, cot["cotacaoCompra"], cot["cotacaoVenda"], cot["dataHoraCotacao"][11:16])

pedido 07/11/2026 (sábado) -> 2026-11-06 5.5007 5.5013 13:06

Por que assim:

• A retentativa em 502, 503 e 504 é a mesma defesa que usamos com as APIs do Banco Central: elas falham de vez em quando e passam na segunda tentativa.
• O limite de 10 dias evita um laço infinito se o parâmetro estiver errado. Um feriado prolongado tem poucos dias seguidos sem cotação.
• timedelta em vez de mexer no dia do mês, para o código não quebrar na virada de mês e em 29/02.

Quais dias úteis ficam sem cotação? Em 2026, até 06/11, foram 10: 01/01, 16/02, 17/02, 03/04, 21/04, 01/05, 04/06, 07/09, 12/10 e 02/11. Pelas datas, são os feriados bancários nacionais. Para não depender de uma lista sua de feriados, deixe a API dizer.

3 Abertura × fechamento: os boletins do dia

Para ver os cinco boletins de uma moeda, use CotacaoMoedaDia. Este código foi executado em 07/11/2026 e compara a abertura com o fechamento de 06/11:

def boletins(moeda, d):
    url = (f"{BASE}/CotacaoMoedaDia(moeda=@moeda,dataCotacao=@dataCotacao)"
           f"?@moeda='{moeda}'&@dataCotacao='{mmddaaaa(d)}'&$format=json")
    return sorted(baixar(url), key=lambda r: r["dataHoraCotacao"])

bs = boletins("USD", date(2026, 11, 6))
for b in bs: print(f'{b["tipoBoletim"]:<16} {b["dataHoraCotacao"][11:16]}  compra {b["cotacaoCompra"]:.4f}  venda {b["cotacaoVenda"]:.4f}')
abertura = bs[0]; fech = bs[-1]
print("variação abertura -> fechamento (venda): %+.4f" % (fech["cotacaoVenda"] - abertura["cotacaoVenda"]))
media = round(sum(b["cotacaoCompra"] for b in bs[:4]) / 4, 4)
print("média dos 4 primeiros boletins (compra):", media, "| fechamento PTAX:", round(fech["cotacaoCompra"], 4))

Abertura         10:02  compra 5.5042  venda 5.5048
Intermediário    11:09  compra 5.5174  venda 5.5180
Intermediário    12:06  compra 5.4882  venda 5.4888
Intermediário    13:06  compra 5.4930  venda 5.4936
Fechamento PTAX  13:06  compra 5.5007  venda 5.5013
variação abertura -> fechamento (venda): -0.0035
média dos 4 primeiros boletins (compra): 5.5007 | fechamento PTAX: 5.5007

O último intermediário e o fechamento saem com o mesmo horário (13:06:13); os microssegundos desempatam, e por isso ordenar por dataHoraCotacao e pegar o último funciona.

4 Outras moedas: tipo A e tipo B

Moedas lista as 10 moedas: AUD, CAD, CHF, DKK, EUR, GBP, JPY, NOK, SEK e USD. Cada uma tem um tipo, que muda o sentido da paridade:

• Tipo A (CAD, CHF, DKK, JPY, NOK, SEK, USD): a paridade é a quantidade da moeda por 1 dólar.
• Tipo B (AUD, EUR, GBP): a paridade é a quantidade de dólares por 1 unidade da moeda.

Não calcule a cotação em reais pela paridade: ela já vem pronta em cotacaoCompra e cotacaoVenda. Para o fechamento de 06/11/2026 (consulta CotacaoMoedaDia com $filter=tipoBoletim eq 'Fechamento PTAX'):

EUR (tipo B)  paridade 1.1144 / 1.1146   cotação em reais 6.13 / 6.1317
JPY (tipo A)  paridade 158.23 / 158.27   cotação em reais 0.03476 / 0.03477

Na prática: o euro vale 1,1144 dólar e custa R$ 6,13. O iene tem 158,23 unidades por dólar e custa R$ 0,03476.

5 O histórico inteiro, sem limite de 10 anos

Quem usa a SGS do Banco Central conhece o limite: desde 26/03/2025, séries diárias aceitam no máximo 10 anos por consulta. A Olinda PTAX não tem esse limite. Este código pede 27 anos em uma chamada só e foi executado em 07/11/2026:

def dolar_periodo(inicio, fim):
    mdy = lambda d: d.strftime("%m-%d-%Y")
    url = (f"{BASE}/CotacaoDolarPeriodo(dataInicial=@dataInicial,dataFinalCotacao=@dataFinalCotacao)"
           f"?@dataInicial='{mdy(inicio)}'&@dataFinalCotacao='{mdy(fim)}'&$format=json")
    return baixar(url)

historico = dolar_periodo(date(1999, 1, 1), date(2026, 11, 6))   # 27 anos em um pedido só
datas = [r["dataHoraCotacao"][:10] for r in historico]
print(len(historico), "linhas")
print(datas[0], historico[0]["cotacaoVenda"], "->", datas[-1], historico[-1]["cotacaoVenda"])
print("datas repetidas:", len(datas) - len(set(datas)))

6995 linhas
1999-01-04 1.2078 -> 2026-11-06 5.5013
datas repetidas: 2

A resposta tem cerca de 630 KB e voltou em menos de um segundo. E repare na última linha: 2 datas repetidas. CotacaoDolarPeriodo devolve, em geral, uma linha por dia útil, mas não é garantido. Em 21/12/2001 a mesma linha veio duas vezes, e em 23/04/2025 vieram dois fechamentos que diferem só nos milissegundos (13:06:30.416 e 13:06:30.443). Quem soma ou conta por data duplica esses dois dias.

A correção é guardar uma linha por dia, a última por dataHoraCotacao:

por_dia = {}
for r in sorted(historico, key=lambda r: r["dataHoraCotacao"]):
    por_dia[r["dataHoraCotacao"][:10]] = r          # a última linha do dia vence
print(len(historico), "linhas ->", len(por_dia), "dias únicos")

6995 linhas -> 6993 dias únicos

É a mesma regra do dashboard: "se a API repetir o dia, vale a última".

6 Power Query: o dólar por período

Conforme a documentação oficial do Web.Contents (link nas referências); não executado aqui. Teste no seu Power BI Desktop antes de publicar.

let
    Inicio = #date(2026, 1, 1),
    Fim = Date.From(DateTime.LocalNow()),
    Mdy = (d as date) as text => "'" & Date.ToText(d, "MM-dd-yyyy", "en-US") & "'",
    Fonte = Json.Document(Web.Contents("https://olinda.bcb.gov.br", [
        RelativePath = "olinda/servico/PTAX/versao/v1/odata/CotacaoDolarPeriodo(dataInicial=@dataInicial,dataFinalCotacao=@dataFinalCotacao)",
        Query = [
            #"@dataInicial" = Mdy(Inicio),
            #"@dataFinalCotacao" = Mdy(Fim),
            #"$format" = "json"
        ]
    ])),
    Linhas = Fonte[value],
    Tabela = if List.IsEmpty(Linhas)
        then #table(type table [Data = date, Compra = number, Venda = number], {})
        else Table.FromRecords(Linhas),
    Tipada = if List.IsEmpty(Linhas) then Tabela else Table.TransformColumnTypes(
        Table.RenameColumns(
            Table.TransformColumns(Tabela, {{"dataHoraCotacao", each Text.Start(_, 10), type text}}),
            {{"dataHoraCotacao", "Data"}, {"cotacaoCompra", "Compra"}, {"cotacaoVenda", "Venda"}}),
        {{"Data", type date}, {"Compra", type number}, {"Venda", type number}}, "en-US")
in
    Tipada

Por que montar assim:

• RelativePath e Query em vez de concatenar a URL. O serviço do Power BI não atualiza fonte dinâmica, aquela cuja URL só se conhece quando a consulta roda. Com a base fixa no primeiro argumento do Web.Contents, a atualização agendada funciona.
• Date.ToText(d, "MM-dd-yyyy", "en-US"). A cultura fixa em en-US garante o mês na frente mesmo num Power BI em português. É a defesa contra a troca de 06-11 por 11-06 do passo 1.
• O if List.IsEmpty. Se Linhas vier vazia (período sem cotação), Table.FromRecords gera uma tabela sem colunas, e as etapas seguintes falhariam. A tabela vazia com as colunas certas evita isso.
• Text.Start(_, 10) pega os 10 primeiros caracteres de dataHoraCotacao (2026-11-06) e deixa a data limpa.

Para as duas datas repetidas do passo 5, acrescente ao final um Table.Distinct pela coluna Data. Ele fica com a primeira ocorrência de cada data; como as duas linhas repetidas trazem os mesmos valores de compra e venda, o resultado é o mesmo.

Para os boletins do dia de uma moeda, transforme a consulta em função:

(moeda as text, dia as date) as table =>
let
    Mdy = "'" & Date.ToText(dia, "MM-dd-yyyy", "en-US") & "'",
    Fonte = Json.Document(Web.Contents("https://olinda.bcb.gov.br", [
        RelativePath = "olinda/servico/PTAX/versao/v1/odata/CotacaoMoedaDia(moeda=@moeda,dataCotacao=@dataCotacao)",
        Query = [#"@moeda" = "'" & moeda & "'", #"@dataCotacao" = Mdy, #"$format" = "json"]
    ])),
    Tabela = Table.FromRecords(Fonte[value])
in
    Tabela

Também não executado. Dois pontos que não consegui testar sem o Power BI: se o Web.Contents aceita os parênteses e o @ dentro do RelativePath e das chaves do Query, e como ele monta a URL final. O que eu verifiquei foi o lado da API: a Olinda aceita a URL com @ e aspas codificadas (%40dataCotacao=%2711-06-2026%27) e com os parênteses codificados.