15 indicadores macroeconômicos do Banco Central — Selic, CDI, IPCA, IGP-M, IBC-Br, desemprego e mais — em um único endpoint composable. Sem precisar entender o BCB SGS, sem código de série numérica, sem integração separada por indicador.
Em maio de 2026 lançamos o /api/v2/macro, um endpoint unificado que
consolida em uma única chamada o que antes exigia raspar dezenas de séries do
BCB SGS ou orquestrar requisições para os endpoints legados /api/v2/inflation
e /api/v2/prime-rate (deprecados, sunset em 31/07/2026).
Se você integra dados macroeconômicos brasileiros em fintechs, dashboards, robôs de investimento ou ferramentas de análise, este post mostra como migrar e o que ganha de quebra.
Por que um endpoint único de macroeconomia?
O BCB SGS (Sistema Gerenciador de Séries Temporais) tem dezenas de milhares de séries identificadas por códigos numéricos (1, 432, 13522, 21619…). Trabalhar diretamente com SGS exige:
- Consultar a documentação para descobrir o código de cada série
- Interpretar formatos de data e valor inconsistentes
- Lidar com a infraestrutura instável do BCB (timeouts frequentes)
- Implementar cache, retry e paralelização por conta própria
O /api/v2/macro resolve tudo isso por trás de slugs estáveis —
identificadores curtos, em letras minúsculas, que nunca mudam:
| Slug | Indicador | Frequência | Início |
|---|---|---|---|
selic | Taxa Selic Meta | diária | 1999-03-05 |
selicovernight | Selic Overnight (efetiva) | diária | 1986-03-04 |
cdi | Certificado de Depósito Interbancário | diária | 1986-03-06 |
tr | Taxa Referencial | mensal | 1991-03-01 |
ipca | IPCA mensal | mensal | 1980-01-01 |
ipca12m | IPCA acumulado em 12 meses | mensal | 1981-01-01 |
inpc | INPC | mensal | 1979-04-01 |
igpm | IGP-M | mensal | 1989-06-01 |
igpdi | IGP-DI | mensal | 1944-08-01 |
ibcbr | IBC-Br (proxy do PIB mensal) | mensal | 2003-01-01 |
pibmensal | PIB mensal | mensal | 1990-01-01 |
desemprego | Taxa de desocupação (PNAD Contínua) | mensal | 2012-03-01 |
m1 | Agregado monetário M1 | mensal | 1988-07-01 |
m4 | Agregado monetário M4 | mensal | 1988-07-01 |
reservas | Reservas internacionais | diária | 2000-01-03 |
Cada slug aceita aliases (escritas alternativas) e a API resolve automaticamente — útil para LLMs e ferramentas que adivinham nomes.
Códigos BCB nunca aparecem na resposta
A API esconde os códigos SGS (selo de "agregador de dados"). Você nunca vê o
número 432, apenas o slug selic. Se um dia o BCB renumerar uma série,
o slug continua igual.
Os 3 endpoints da API de macroeconomia
A API de macroeconomia tem três endpoints, cada um para um caso de uso:
1. GET /api/v2/macro — Séries históricas
Retorna observações históricas para uma ou mais séries. Composable: aceita até 20 slugs separados por vírgula em uma única chamada.
curl -H "Authorization: Bearer SEU_TOKEN" \
"https://brapi.dev/api/v2/macro?symbols=selic,ipca12m&startDate=2024-01-01&endDate=2026-04-30"Resposta:
{
"results": [
{
"series": {
"slug": "selic",
"name": "Taxa Selic",
"description": "Taxa básica de juros da economia brasileira...",
"unit": "percentPerYear",
"frequency": "daily",
"category": "interestRate",
"startDate": "1999-03-05"
},
"observations": [
{ "date": "2026-04-30", "value": 14.5 },
{ "date": "2026-04-29", "value": 14.75 }
]
},
{
"series": {
"slug": "ipca12m",
"name": "IPCA 12 meses",
"unit": "percent",
"frequency": "monthly",
"category": "inflation"
},
"observations": [
{ "date": "2026-03-01", "value": 4.14 },
{ "date": "2026-02-01", "value": 3.81 }
]
}
],
"requestedAt": "2026-04-30T12:00:00.000Z",
"took": 23
}Parâmetros:
| Parâmetro | Descrição | Default |
|---|---|---|
symbols (obrigatório) | Slugs separados por vírgula (máx. 20) | — |
startDate | Data inicial YYYY-MM-DD | 12 meses atrás |
endDate | Data final YYYY-MM-DD | hoje |
sortOrder | asc ou desc | desc |
limit | Observações por série (sem teto) | 20 |
Para histórico completo de uma série, passe limit=10000.
2. GET /api/v2/macro/latest — Snapshot atual
Retorna apenas a observação mais recente de cada série. Ideal para dashboards
que mostram só o valor corrente. Se symbols for omitido, retorna todas as
séries disponíveis.
curl -H "Authorization: Bearer SEU_TOKEN" \
"https://brapi.dev/api/v2/macro/latest?symbols=selic,cdi,ipca12m"{
"results": [
{
"series": { "slug": "selic", "name": "Taxa Selic", "unit": "percentPerYear" },
"latest": { "date": "2026-04-30", "value": 14.5 }
},
{
"series": { "slug": "cdi", "name": "CDI", "unit": "percentPerDay" },
"latest": { "date": "2026-04-30", "value": 0.054267 }
},
{
"series": { "slug": "ipca12m", "name": "IPCA 12 meses", "unit": "percent" },
"latest": { "date": "2026-03-01", "value": 4.14 }
}
],
"requestedAt": "2026-04-30T12:00:00.000Z",
"took": 18
}3. GET /api/v2/macro/available — Catálogo público
Endpoint público (sem autenticação). Lista os slugs disponíveis com metadados — use antes de chamar os outros para descobrir o que existe:
# Buscar séries de juros
curl "https://brapi.dev/api/v2/macro/available?category=interestRate"
# Busca textual (slug, alias, nome ou descrição)
curl "https://brapi.dev/api/v2/macro/available?q=ipca"A busca por q ordena por relevância: matches em slug vêm primeiro,
depois em alias, nome e descrição.
Atenção às unidades
Cada série tem uma unit específica. Não interprete um número sem checar:
unit | Significado | Exemplo |
|---|---|---|
percentPerYear | % ao ano | Selic = 14.5 → 14,5% a.a. |
percentPerDay | % ao dia | CDI = 0.054267 → 0,054267% ao dia |
percentPerMonth | % ao mês | IPCA = 0.43 → 0,43% no mês |
percent | % puro (não-anualizado) | IPCA12m = 4.14 → 4,14% (acumulado 12m) |
index | Número-índice | IBC-Br |
brl | Reais (BRL) | USD-BRL = 5.21 |
brlMillion | Milhões de R$ | PIB mensal |
brlThousand | Mil R$ | M1, M4 |
usdMillion | Milhões de USD | Reservas internacionais |
CDI vem em % ao dia, não a.a.
A série cdi retorna o fator diário (ex: 0.054267). Para anualizar,
use 252 dias úteis: (1 + cdi/100) ** 252 - 1. O resultado típico é
~0,1 ponto percentual abaixo da Selic Meta.
Exemplo TypeScript: Dashboard macroeconômico
type MacroLatest = {
results: Array<{
series: { slug: string; name: string; unit: string };
latest: { date: string; value: number } | null;
}>;
};
const auth = { headers: { Authorization: `Bearer ${process.env.BRAPI_TOKEN}` } };
async function getMacroSnapshot() {
const res = await fetch(
'https://brapi.dev/api/v2/macro/latest?symbols=selic,cdi,ipca12m,igpm,desemprego',
auth,
);
const data: MacroLatest = await res.json();
const get = (slug: string) =>
data.results.find((r) => r.series.slug === slug)?.latest?.value;
const selic = get('selic') ?? 0;
const cdiDiario = get('cdi') ?? 0;
const cdiAnual = (Math.pow(1 + cdiDiario / 100, 252) - 1) * 100;
const ipca = get('ipca12m') ?? 0;
const igpm = get('igpm') ?? 0;
const desemprego = get('desemprego') ?? 0;
// Juro real ex-ante: (1+selic) / (1+ipca) - 1
const juroReal = ((1 + selic / 100) / (1 + ipca / 100) - 1) * 100;
return { selic, cdiAnual, ipca, igpm, desemprego, juroReal };
}Exemplo Python: Histórico para gráfico
import os
import requests
def fetch_macro_history(symbols: list[str], start: str, end: str):
response = requests.get(
'https://brapi.dev/api/v2/macro',
params={
'symbols': ','.join(symbols),
'startDate': start,
'endDate': end,
'sortOrder': 'asc',
'limit': 10000, # histórico completo
},
headers={'Authorization': f"Bearer {os.environ['BRAPI_TOKEN']}"},
)
response.raise_for_status()
return response.json()['results']
# Selic, IPCA12m e CDI em um único request
data = fetch_macro_history(
['selic', 'ipca12m', 'cdi'],
start='2020-01-01',
end='2026-04-30',
)
for series in data:
slug = series['series']['slug']
obs = series['observations']
print(f"{slug}: {len(obs)} observações")Exemplo cURL: Lista o catálogo completo
# Sem autenticação — descobre todos os slugs disponíveis
curl "https://brapi.dev/api/v2/macro/available" | jq '.results[].slug'
# Filtra por categoria de inflação
curl "https://brapi.dev/api/v2/macro/available?category=inflation"
# Busca textual fuzzy
curl "https://brapi.dev/api/v2/macro/available?q=juros"Migrando dos endpoints legados
Se você usa hoje /api/v2/inflation ou /api/v2/prime-rate, atualize antes
do sunset em 31/07/2026. A migração é simples — todos os dados estão na
mesma série, só muda a forma de pedir e o shape da resposta.
Selic: antes vs. depois
- const r = await fetch('https://brapi.dev/api/v2/prime-rate');
- const data = await r.json();
- const selic = data['prime-rate'][0].value;
+ const r = await fetch(
+ 'https://brapi.dev/api/v2/macro/latest?symbols=selic',
+ { headers: { Authorization: `Bearer ${process.env.BRAPI_TOKEN}` } },
+ );
+ const { results } = await r.json();
+ const selic = results[0].latest.value;IPCA: antes vs. depois
- const r = await fetch('https://brapi.dev/api/v2/inflation?country=brazil');
- const data = await r.json();
- const ipca = data.inflation[0].value;
+ // Use ipca12m para o acumulado em 12 meses (que era a métrica usada pelo COPOM)
+ const r = await fetch(
+ 'https://brapi.dev/api/v2/macro/latest?symbols=ipca12m',
+ { headers: { Authorization: `Bearer ${process.env.BRAPI_TOKEN}` } },
+ );
+ const { results } = await r.json();
+ const ipca12m = results[0].latest.value;Diferenças importantes:
- O endpoint legado
/api/v2/inflationretornava IPCA mensal, mas a maioria dos casos de uso (juro real, comparativos) precisa do acumulado em 12 meses. Useipca12mpara esse cenário;ipcapara a variação mensal. /api/v2/macroexige token Bearer (mesmo Startup Plan). O/availableé público.- Datas usam ISO
YYYY-MM-DDem vez deDD/MM/YYYY.
Autenticação, planos e limites
| Endpoint | Autenticação | Plano mínimo |
|---|---|---|
GET /api/v2/macro/available | Pública | Free |
GET /api/v2/macro | Bearer token | Startup |
GET /api/v2/macro/latest | Bearer token | Startup |
Cache no servidor: as respostas de /macro (séries) ficam em cache por 15
min, /latest por 5 min e /available por 24 h. Use os cabeçalhos
Cache-Control: s-maxage=... retornados pela API para cachear no seu lado.
Limite de 20 slugs por requisição: se você precisa de mais, particione em batches (raríssimo — o catálogo todo tem 15 séries).
Casos de uso
Calculadoras de investimento
Selic + CDI + IPCA12m em uma única chamada para calcular rendimento líquido, juro real ex-ante e benchmark de carteira.
Dashboards executivos
Snapshot via /latest exibe valor atual + data de atualização. Cache de 5 min
evita re-fetch desnecessário.
Backtesting
limit=10000 traz o histórico completo (até 1944 para IGP-DI). Combine com
nosso endpoint de cotações históricas de moedas
para backtests cambiais.
Modelagem econômica
IBC-Br como proxy mensal do PIB, M1/M4 como agregados monetários, reservas internacionais e desemprego em um único pipeline.
Próximos passos
- 📖 Documentação completa do
/api/v2/macro - 🔍 Lista de slugs e metadados
- 💱 Histórico de moedas via PTAX
- 🧮 Como calcular juro real (Selic - IPCA)
- 📊 CDI histórico via API
Crie sua conta gratuita em brapi.dev para receber seu
token e testar. As chamadas /available funcionam sem token — comece por aí.
