Como Consultar a PTAX do Banco Central em JavaScript (e o Bug do Fim de Semana)

Ola HaWkers, se você é dev PJ e recebe de cliente lá fora, cedo ou tarde precisa da cotação PTAX do dia em que o dinheiro caiu. Dá pra pegar direto da API de dados abertos do Banco Central, sem chave e com CORS liberado. Mas tem uma pegadinha que quebra a consulta ingênua.

A API

O Banco Central publica a PTAX no serviço Olinda. Dois endpoints resolvem quase tudo:

• CotacaoDolarDia(dataCotacao=@dataCotacao): cotação de um dia específico.
• CotacaoDolarPeriodo(dataInicial=@dataInicial,dataFinalCotacao=@dataFinalCotacao): todas as cotações num intervalo.

As datas vão no formato MM-DD-AAAA, entre aspas simples.

const base = 'https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/odata';
const url = `${base}/CotacaoDolarDia(dataCotacao=@dataCotacao)?@dataCotacao='10-23-2026'&$format=json`;

const { value } = await (await fetch(url)).json();
console.log(value[0]); // { cotacaoCompra: 5.0371, cotacaoVenda: 5.0377, dataHoraCotacao: '2026-10-23 13:07:14.xxx' }

O bug do fim de semana

Troque a data para um sábado e value volta vazio. O Banco Central só publica PTAX em dia útil: sábado, domingo e feriado não têm cotação. Se o dinheiro do cliente caiu num domingo, value[0] é undefined e seu código quebra.

A correção é pedir um período que termina na data desejada e pegar a última cotação disponível:

const pad = (n) => String(n).padStart(2, '0');
const fmt = (d) => `${pad(d.getMonth() + 1)}-${pad(d.getDate())}-${d.getFullYear()}`;

async function ptax(dataISO) {
  const fim = new Date(`${dataISO}T12:00:00`);
  const inicio = new Date(fim);
  inicio.setDate(inicio.getDate() - 10); // cobre feriado prolongado

  const url = `${base}/CotacaoDolarPeriodo(dataInicial=@dataInicial,dataFinalCotacao=@dataFinalCotacao)`
    + `?@dataInicial='${fmt(inicio)}'&@dataFinalCotacao='${fmt(fim)}'&$format=json`;

  const { value } = await (await fetch(url)).json();
  const ultima = value.at(-1);
  if (!ultima) return null;

  return {
    data: ultima.dataHoraCotacao.slice(0, 10), // a data efetivamente usada
    compra: ultima.cotacaoCompra,
    venda: ultima.cotacaoVenda,
  };
}

console.log(await ptax('2026-10-25')); // domingo → usa sexta, 2026-10-23

Dois detalhes:

• Guarde a data efetivamente usada, não só a cotação. Na hora de conferir com o contador, "PTAX de 23/10 usada para o recebimento de 25/10" é a informação que importa.
• Use meio-dia ao montar a data (T12:00:00). Evita que o fuso horário empurre a data para o dia anterior.

Compra ou venda?

A PTAX vem com duas taxas. Para converter receita recebida do exterior, é comum usar a de compra do dia do recebimento, mas isso depende da obrigação e do regime. Confirme com seu contador antes de fixar no código.

Quer pular essa parte?

Montei a Fatura Gringa em cima exatamente desse código: tem uma consulta de PTAX grátis de qualquer data, um gerador de invoice em inglês grátis e, na versão paga, o invoice sai sozinho todo mês e a PTAX é anotada quando você marca o recebimento.

Conclusão

A API do Banco Central é simples e aberta, mas trate dia sem cotação desde o começo: busque um intervalo, pegue a última cotação e guarde a data que você usou de fato.

Bora pra cima! 🦅