Documentação da API

Referência completa de todos os endpoints da API bolsai. Dados financeiros do Brasil provenientes de fontes oficiais: B3, CVM e BCB.

Testar no playground
Base URL: https://api.usebolsai.com/api/v1
OpenAPI Spec (Postman)

Autenticação

Todas as requisições devem incluir o header X-API-Key com sua chave de acesso. Você pode obter sua chave gratuitamente fazendo login com sua conta Google e gerenciar suas chaves (criar, rotacionar, excluir) direto no dashboard. Cada conta pode ter até 5 chaves ativas no plano Free e 20 no plano Pro.

Plano Grátis

  • 200 requisições por dia
  • Fundamentos e preços atuais
  • Busca de empresas e FIIs

Plano Pro — R$ 49/mês

  • 10.000 requisições por dia
  • Todos os endpoints liberados
  • 10+ anos de dados históricos

Os limites são resetados à meia-noite UTC. Se o limite for excedido, a API retorna 429 Too Many Requests. O header X-RateLimit-Remaining indica quantas requisições restam.

Exemplo de requisição autenticada 
curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/fundamentals/PETR4

Exportação CSV

A maioria dos endpoints aceita o parâmetro format=csv para exportar os dados em formato CSV. Útil para importar no Excel, Google Sheets ou scripts de análise.

Exemplo de exportação CSV 
curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/stocks/PETR4/history?format=csv" \
  -o petr4_precos.csv

Gerenciamento de chaves

Os endpoints abaixo são usados pelo dashboard para listar, criar, rotacionar e excluir chaves. Eles autenticam por cookie de sessão (login Google) — não por X-API-Key. Para integrações via terminal, recomendamos usar o dashboard direto.

Ao rotacionar ou excluir uma chave, ela deixa de funcionar imediatamente. O limite de requisições é compartilhado entre todas as chaves de uma mesma conta — criar mais chaves não aumenta sua cota diária.

GET

/keys

Lista as chaves ativas da conta. Os valores das chaves são retornados mascarados — o segredo completo só é exibido uma vez no momento da criação ou rotação.

Resposta (200) 
[
  {
    "id": 42,
    "label": "default",
    "key_masked": "sk_697d••••••••f485",
    "is_active": true,
    "created_at": "2026-03-24T20:38:39",
    "last_used_at": "2026-05-12T13:21:04"
  }
]
POST

/keys

Cria uma nova chave com o rótulo (label) informado. Retorna o segredo completo apenas uma vez — guarde-o em local seguro. Retorna 400 se a conta já atingiu o limite (5 no Free, 20 no Pro).

Campo Tipo Obrig. Descrição
label string Sim Rótulo da chave (1-50 caracteres). Ex: "produção", "laptop", "CI".
Resposta (200) 
{
  "id": 43,
  "label": "laptop",
  "key": "sk_a4b9c2d1e0f8..."
}
POST

/keys/{id}/rotate

Gera um novo segredo para a chave mantendo o mesmo rótulo e id. O segredo antigo deixa de funcionar imediatamente. O novo segredo é retornado uma única vez na resposta.

Resposta (200) 
{
  "id": 43,
  "label": "laptop",
  "key": "sk_novosecreto..."
}
DELETE

/keys/{id}

Exclui (revoga) a chave. A chave deixa de funcionar imediatamente. Retorna 400 se essa for a única chave ativa da conta — toda conta precisa ter pelo menos uma chave ativa.

Resposta (200) 
{
  "ok": true
}
GET

/keys/usage

Consulte o uso atual da sua API key: requisições feitas hoje, limite diário e tier do plano.

Parâmetro Tipo Obrig. Descrição
api_key string Sim Sua API key (query parameter)
Exemplo 
curl "https://api.usebolsai.com/api/v1/keys/usage?api_key=sua_chave"
Resposta 
{
  "tier": "free",
  "used_today": 42,
  "daily_limit": 200,
  "remaining": 158
}

Empresas

Listagem e consulta de companhias registradas na CVM, com filtros por setor, status e busca textual.

GET

/companies

Lista todas as empresas registradas, com suporte a filtros por setor, status e busca por nome.

Parâmetro Tipo Obrig. Descrição
sector string Não Filtrar por setor (ex: "Financeiro")
status string Não Filtrar por status (ex: "ATIVO")
search string Não Buscar por razão social ou nome de pregão (max 100 caracteres)
limit int Não Itens por página (1-500, padrão: 50)
offset int Não Deslocamento para paginação (padrão: 0)
Requisição 
curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/companies/?search=petro&limit=2"
Resposta 
{
  "data": [
    {
      "ticker_primary": "PETR4",
      "corporate_name": "PETROLEO BRASILEIRO S.A. PETROBRAS",
      "trade_name": "PETROBRAS",
      "cvm_code": "9512",
      "cnpj": "33.000.167/0001-01",
      "sector": "Petroleo, Gas e Biocombustiveis",
      "status": "ATIVO"
    },
    {
      "ticker_primary": "RECV3",
      "corporate_name": "PETRO RECÔNCAVO S.A.",
      "trade_name": "PETRORECONCAVO",
      "cvm_code": "25607",
      "cnpj": "03.342.704/0001-30",
      "sector": "Petroleo, Gas e Biocombustiveis",
      "status": "ATIVO"
    }
  ],
  "count": 2,
  "total": 5,
  "offset": 0,
  "limit": 2
}
GET

/companies/sectors

Lista todos os setores disponíveis com a contagem de empresas ativas com ticker em cada um. Útil para descobrir nomes de setores válidos para os filtros de /companies e /screener.

Requisição 
curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/companies/sectors
Resposta 
{
  "sectors": [
    { "name": "Bancos", "count": 19 },
    { "name": "Energia Elétrica", "count": 18 },
    { "name": "Construção Civil, Mat. Constr. e Decoração", "count": 16 },
    // ...
  ],
  "total": 42
}
GET

/companies/{ticker}

Retorna informações detalhadas de uma empresa a partir do ticker. O campo queried_ticker ecoa o ticker consultado e tickers lista todas as classes de ação (ON/PN/Unit) da empresa.

Parâmetro Tipo Obrig. Descrição
ticker string Sim Ticker da empresa (ex: PETR4, VALE3)
Requisição 
curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/companies/PETR4
Resposta 
{
  "ticker_primary": "PETR4",
  "queried_ticker": "PETR4",
  "tickers": ["PETR3", "PETR4"],
  "corporate_name": "PETROLEO BRASILEIRO S.A. PETROBRAS",
  "trade_name": "PETROBRAS",
  "cvm_code": "9512",
  "cnpj": "33.000.167/0001-01",
  "sector": "Petroleo, Gas e Biocombustiveis",
  "status": "ATIVO",
  "registration_date": "1977-08-15",
  "registration_category": "A",
  "market_type": "BOLSA",
  "country": "Brasil",
  "state": "RJ",
  "city": "Rio de Janeiro",
  "email": "",
  "website": ""
}

Ações

Cotações em tempo real, histórico OHLCV ajustado por splits e bonificações, estatísticas e eventos corporativos.

GET

/stocks

Lista todos os tickers disponíveis, filtrados por código BDI.

Parâmetro Tipo Obrig. Descrição
bdi_code string Não Código BDI: "02" = ações, "12" = FIIs, "14" = BDRs (padrão: "02")
limit int Não Máximo de resultados (1-5000, padrão: 500)
offset int Não Deslocamento para paginação (padrão: 0)
Requisição 
curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/stocks/?bdi_code=02&limit=10"
Resposta 
{
  "count": 312,
  "total": 312,
  "tickers": [
    "ABEV3",
    "ALPA4",
    "AMER3",
    // ... +309 tickers
  ]
}
GET

/stocks/{ticker}/quote

Retorna a cotação mais recente de um ticker, incluindo preço de abertura, máxima, mínima, fechamento e volume.

Parâmetro Tipo Obrig. Descrição
ticker string Sim Ticker da ação (ex: PETR4, VALE3)
Requisição 
curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/stocks/PETR4/quote
Resposta 
{
  "ticker": "PETR4",
  "trade_date": "2026-03-21",
  "open": 45.12,
  "high": 46.03,
  "low": 44.89,
  "close": 45.67,
  "volume": 42318700,
  "traded_amount": 1932045876.54,
  "num_trades": 187432
}
GET

/stocks/{ticker}/stats

Estatísticas de preço: máxima/mínima de 52 semanas, retorno YTD, variação diária e volume médio.

Parâmetro Tipo Obrig. Descrição
ticker string Sim Ticker da ação (ex: ITUB4)
Requisição 
curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/stocks/ITUB4/stats
Resposta 
{
  "ticker": "ITUB4",
  "trade_date": "2026-03-21",
  "close": 34.52,
  "daily_change": 0.38,
  "daily_change_pct": 1.11,
  "week_52_low": 27.15,
  "week_52_high": 36.89,
  "avg_volume_52w": 24563100,
  "ytd_return_pct": 12.45
}
GET

/stocks/{ticker}/history

Retorna o histórico de preços de um ticker, ordenado do mais recente para o mais antigo. Inclui preços ajustados por splits, grupamentos e dividendos. Dados desde 1986. Consultar tickers antigos (ex: VIIA3) retorna histórico completo da empresa.

Parâmetro Tipo Obrig. Descrição
ticker string Sim Ticker da ação (ex: VALE3)
start date Não Data de início (formato: YYYY-MM-DD)
end date Não Data de fim (formato: YYYY-MM-DD)
limit int Não Número máximo de registros (1-5000, padrão: 252)
Requisição 
curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/stocks/VALE3/history?start=2026-01-01&limit=5"
Resposta 
{
  "ticker": "VALE3",
  "count": 5,
  "prices": [
    {
      "trade_date": "2026-03-21",
      "open": 62.45,
      "high": 63.10,
      "low": 61.80,
      "close": 62.87,
      "adjusted_open": 62.45,
      "adjusted_high": 63.10,
      "adjusted_low": 61.80,
      "adjusted_close": 62.87,
      "volume": 35214600,
      "adjusted_volume": 35214600,
      "traded_amount": 2213784521.30,
      "num_trades": 142567
    }
    // ... mais registros
  ]
}
GET

/stocks/{ticker}/corporate-events

Retorna desdobramentos (splits) e grupamentos (reverse splits) confirmados pela B3 para um ticker.

Parâmetro Tipo Obrig. Descrição
ticker string Sim Ticker da ação (ex: MGLU3)
Requisição 
curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/stocks/MGLU3/corporate-events
Resposta 
{
  "ticker": "FESA4",
  "count": 2,
  "events": [
    {
      "date": "2024-01-23",
      "type": "SPLIT",
      "ratio_from": 1,
      "ratio_to": 4,
      "description": "1:4",
      "factor": 0.25
    }
  ]
}
GET

/stocks/corporate-events

Lista todos os desdobramentos e grupamentos confirmados pela B3 para todos os tickers.

Parâmetro Tipo Obrig. Descrição
year int Não Filtrar por ano (ex: 2025)
limit int Não Máximo de resultados (1-1000, padrão: 100)
Requisição 
curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/stocks/corporate-events?year=2025"
Resposta 
{
  "count": 2,
  "events": [
    {
      "ticker": "FESA4",
      "date": "2024-01-23",
      "type": "SPLIT",
      "ratio_from": 1,
      "ratio_to": 4,
      "description": "1:4",
      "factor": 0.25
    },
    {
      "ticker": "MGLU3",
      "date": "2024-05-24",
      "type": "INPLIT",
      "ratio_from": 10,
      "ratio_to": 1,
      "description": "10:1",
      "factor": 10.0
    }
  ]
}
GET

/stocks/{ticker}/ticker-history

Retorna o histórico de tickers de uma empresa, incluindo renomeações. Consultar VIIA3 ou BHIA3 retorna o mesmo resultado (dados completos da empresa).

{
  "cvm_code": "6505",
  "corporate_name": "GRUPO CASAS BAHIA S.A.",
  "current_ticker": "BHIA3",
  "tickers": [
    {
      "ticker": "BHIA3",
      "first_traded": "2023-09-20",
      "last_traded": "2026-03-25",
      "current": true
    },
    {
      "ticker": "VIIA3",
      "first_traded": "2020-09-14",
      "last_traded": "2023-09-19",
      "current": false
    }
  ]
}

Screener

Filtragem de ações por qualquer combinação de indicadores fundamentalistas, com ordenação e paginação.

GET

/screener

Filtra todas as ~264 ações negociadas por indicadores fundamentalistas. Use sufixos _gt (maior que) e _lt (menor que) nos parâmetros. Conta como 1 requisição. Requer plano Pro. Os indicadores aqui são calculados no nível da empresa (ticker principal / mais líquido), uma linha por empresa; para múltiplos por classe de ação (ON/PN/Unit), use /fundamentals/{ticker}.

Parâmetro Tipo Obrig. Descrição
{metric}_gt float Não Filtro "maior que". Métricas: pl, pvp, ev_ebitda, roe, roa, roic, net_margin, gross_margin, ebitda_margin, dividend_yield, debt_equity, net_debt_ebitda, market_cap, lpa, vpa, current_ratio, p_sr, cagr_revenue_5y, cagr_earnings_5y, daily_change, daily_change_pct
{metric}_lt float Não Filtro "menor que". Mesmas métricas acima
sector string Não Filtrar por setor (ex: "Bancos", "Energia Elétrica")
sort string Não Ordenar por métrica (padrão: market_cap)
order string Não Ordem: "asc" ou "desc" (padrão: desc)
limit int Não Resultados por página (1-500, padrão: 50)
offset int Não Paginação (padrão: 0)
Requisição 
curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/screener?dividend_yield_gt=6&roe_gt=10&sort=dividend_yield&order=desc&limit=5"
Resposta 
{
  "data": [
    {
      "ticker": "PETR4",
      "corporate_name": "PETRÓLEO BRASILEIRO S.A.",
      "sector": "Petróleo e Gás",
      "close_price": 49.03,
      "market_cap": 631934567271.83,
      "dividend_yield": 12.3,
      "pl": 5.74,
      "pvp": 1.52,
      "roe": 26.49,
      "net_margin": 22.23,
      "daily_change": 0.38,
      "daily_change_pct": 1.11,
      // ... 20+ mais indicadores
    }
  ],
  "count": 5,
  "total": 23,
  "offset": 0,
  "limit": 5
}
GET

/macro/{series_name}/stats

Estatísticas de preço para uma série macroeconômica: variação diária, máxima/mínima 52 semanas e retorno no ano. Útil para exibir o Ibovespa ou câmbio com o mesmo formato do endpoint /stocks/{ticker}/stats.

Requisição 
curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/macro/ibovespa/stats
Resposta 
{
  "series": "ibovespa",
  "reference_date": "2026-06-23",
  "close": 137420.5,
  "daily_change": 843.2,
  "daily_change_pct": 0.62,
  "week_52_low": 118340.0,
  "week_52_high": 141200.0,
  "ytd_return_pct": 12.34
}

Fundamentos

27+ indicadores fundamentalistas (P/L, P/VP, ROE, ROIC, EV/EBITDA, DY, LPA, VPA, margens) com snapshot atual e série histórica.

GET

/fundamentals/{ticker}

Retorna indicadores fundamentalistas calculados: P/L, EV/EBITDA, ROE, margem líquida, dívida/patrimônio e mais. Usa os dados DFP/ITR mais recentes disponíveis. Múltiplos de preço (P/L, P/VP, EV/EBITDA, market_cap) são calculados para a classe de ação consultada — ON, PN e Unit têm preços diferentes, então esses valores variam entre elas. Métricas por empresa (LPA, VPA, ROE, margens) são idênticas entre as classes. O campo queried_ticker ecoa o ticker consultado.

Parâmetro Tipo Obrig. Descrição
ticker string Sim Ticker da empresa (ex: PETR4)
reference_date date Não Data de referência do balanço (formato: YYYY-MM-DD). Se omitido, usa o mais recente
Requisição 
curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/fundamentals/PETR4
Resposta 
{
  "cvm_code": "9512",
  "ticker": "PETR4",
  "queried_ticker": "PETR4",
  "reference_date": "2025-12-31",
  "close_price": 45.67,
  "shares_outstanding": 12888732761,
  "market_cap": 588628425194.87,
  "pl": 5.32,
  "pvp": 1.42,
  "ev_ebitda": 3.27,
  "ev_ebit": 4.67,
  "p_ebitda": 2.65,
  "p_ebit": 2.98,
  "p_sr": 1.18,
  "lpa": 8.54,
  "vpa": 32.26,
  "roe": 26.6,
  "roa": 9.04,
  "roic": 17.4,
  "net_margin": 22.23,
  "gross_margin": 47.6,
  "ebitda_margin": 39.6,
  "ebit_margin": 33.2,
  "debt_equity": 0.92,
  "net_debt_equity": 0.8,
  "net_debt_ebitda": 1.18,
  "net_debt_ebit": 1.69,
  "current_ratio": 0.71,
  "asset_turnover": 0.41,
  "p_assets": 0.48,
  "ebit_over_assets": 16.1,
  "cagr_revenue_5y": -0.8,
  "cagr_earnings_5y": null,
  "net_income": 110605000,
  "equity": 415786000,
  "net_revenue": 497549000,
  "total_debt": 384025000,
  "ebitda": 281630000,
  "ebit": 197242000,
  "net_debt": 333417000,
  "cash": 50608000,
  "total_assets": 1223390000,
  "current_assets": 140026000,
  "current_liabilities": 198341000,
  "corporate_name": "PETRÓLEO BRASILEIRO  S.A.  - PETROBRAS"
}
GET

/fundamentals/{ticker}/history

Retorna o histórico de indicadores fundamentalistas, um por trimestre, do mais recente ao mais antigo.

Parâmetro Tipo Obrig. Descrição
ticker string Sim Ticker da empresa (ex: WEGE3)
limit int Não Número de trimestres (1-80, padrão: 40)
Requisição 
curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/fundamentals/WEGE3/history?limit=2"
Resposta 
{
  "ticker": "WEGE3",
  "queried_ticker": "WEGE3",
  "corporate_name": "WEG S.A.",
  "count": 2,
  "history": [
    {
      "reference_date": "2025-12-31",
      "close_price": 52.30,
      "pl": 38.12,
      "pvp": 11.45,
      "roe": 30.02,
      "net_margin": 18.65,
      // ... demais indicadores
    },
    {
      "reference_date": "2025-09-30",
      "close_price": 48.75,
      "pl": 35.67,
      "pvp": 10.89,
      "roe": 29.45,
      "net_margin": 17.92,
      // ... demais indicadores
    }
  ]
}

Demonstrações financeiras

DFP (anual) e ITR (trimestral) da CVM: DRE, balanço patrimonial e fluxo de caixa por código de conta padronizado.

GET

/financials/{ticker}

Retorna as demonstrações financeiras (DFP anuais ou ITR trimestrais) de uma empresa. Inclui Balanço Patrimonial Ativo (BPA), Passivo (BPP), DRE, Fluxo de Caixa (DFC_MI) e DVA.

Parâmetro Tipo Obrig. Descrição
ticker string Sim Ticker da empresa (ex: BBDC4)
report_type string Não "DFP" para anual ou "ITR" para trimestral (padrão: "DFP")
statement_type string Não Tipo: BPA, BPP, DRE, DFC_MI ou DVA
reference_date date Não Data de referência específica (formato: YYYY-MM-DD)
limit int Não Número máximo de linhas (1-5000, padrão: 1000)
Requisição 
curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/financials/BBDC4?report_type=DFP&statement_type=DRE&reference_date=2025-12-31"
Resposta 
{
  "ticker": "BBDC4",
  "cvm_code": "9512",
  "report_type": "DFP",
  "count": 42,
  "statements": [
    {
      "reference_date": "2025-12-31",
      "statement_type": "DRE",
      "account_code": "3.01",
      "account_name": "Receita de Intermediacao Financeira",
      "value": 198432000000.0
    },
    {
      "reference_date": "2025-12-31",
      "statement_type": "DRE",
      "account_code": "3.02",
      "account_name": "Despesas da Intermediacao Financeira",
      "value": -142567000000.0
    }
    // ... mais linhas
  ]
}

Dividendos

Histórico completo de proventos com data com, data ex, data de pagamento, tipo (Dividendo ou JCP) e valor por ação.

GET

/dividends/{ticker}

Retorna o histórico de dividendos e JCP de um ticker, incluindo dividend yield dos últimos 12 meses, resumo anual e lista de pagamentos com datas de pagamento. Consultar tickers antigos (ex: VIIA3) retorna dados completos da empresa atual (BHIA3).

Parâmetro Tipo Obrig. Descrição
ticker string Sim Ticker da ação ou FII (ex: BBAS3, HGLG11)
years int Não Anos de histórico (1-20, padrão: 5)
Requisição 
curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/dividends/BBAS3?years=3"
Resposta 
{
  "ticker": "BBAS3",
  "dividend_yield_ttm": 8.45,
  "ttm_per_share": 2.3412,
  "current_price": 27.71,
  "total_payments": 18,
  "annual_summary": [
    {
      "year": 2026,
      "total_per_share": 0.5843,
      "payments": 2
    },
    {
      "year": 2025,
      "total_per_share": 2.8756,
      "payments": 8
    }
  ],
  "payments": [
    {
      "ex_date": "2026-03-14",
      "payment_date": "2026-04-20",
      "type": "JCP",
      "value_per_share": 0.2934,
      "adjusted": false
    },
    {
      "ex_date": "2026-02-21",
      "payment_date": "2026-03-20",
      "type": "Dividendo",
      "value_per_share": 0.2909,
      "adjusted": false
    }
    // ... mais pagamentos
  ]
}

FIIs (Fundos Imobiliários)

Cotações, rendimentos, P/VP, dividend yield, segmentação (Tijolo/Papel/Híbrido/Fundo de Fundos), vacância, inadimplência, principais imóveis e concentração por setor de inquilinos.

GET

/fiis

Lista todos os FIIs negociados na B3 com os dados mais recentes: nome, segmento, tipo de gestão e número de cotistas.

Parâmetro Tipo Obrig. Descrição
limit int Não Máximo de resultados (1-5000, padrão: 500)
offset int Não Deslocamento para paginação (padrão: 0)
Requisição 
curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/fiis/
Resposta 
{
  "count": 185,
  "total": 423,
  "fiis": [
    {
      "ticker": "HGLG11",
      "name": "CSHG LOGISTICA FDO INV IMOB - FII",
      "segment": "Logistica",
      "management_type": "Gestao Ativa",
      "total_shareholders": 487523
    },
    {
      "ticker": "KNRI11",
      "name": "KINEA RENDA IMOBILIARIA FDO INV IMOB - FII",
      "segment": "Hibrido",
      "management_type": "Gestao Ativa",
      "total_shareholders": 312456
    }
    // ... mais FIIs
  ]
}
GET

/fiis/{ticker}

Retorna fundamentos + perfil operacional de um FII: P/VP, dividend yield 12m, NAV, cotistas, administrator, mandate, asset composition, fund_type (Tijolo/Papel/Híbrido/Fundo de Fundos), vacância, inadimplência, lista das principais propriedades. Dados de imóveis (vacância/inadimplência) vêm do informe trimestral CVM.

Parâmetro Tipo Obrig. Descrição
ticker string Sim Ticker do FII (ex: HGLG11 ou HGLG)
Requisição 
curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/fiis/HGLG11
Resposta 
{
  "ticker": "HGLG11",
  "name": "CSHG LOGISTICA FDO INV IMOB - FII",
  "reference_date": "2026-02-28",
  "close_price": 162.45,
  "book_value_per_share": 148.32,
  "pvp": 1.10,
  "dividend_yield_ttm": 8.74,
  "net_asset_value": 4523000000.0,
  "shares_outstanding": 30498200,
  "total_shareholders": 487523,
  "segment": "Logistica",
  "management_type": "Gestao Ativa",
  "administrator": "CREDIT SUISSE HEDGING-GRIFFO CV S.A.",
  "administrator_cnpj": "61809182000130",
  "mandate": "Renda",
  "inception_date": "2010-06-01",
  "duration_type": "Indeterminado",
  "target_investors": "INVESTIDORES EM GERAL",
  "website": "www.cshg.com.br",
  "email": "investidores@cshg.com.br",
  "fund_type": "Tijolo",
  "asset_composition": {
    "real_estate_leased_pct": 84.31,
    "real_estate_under_construction_pct": 0.0,
    "real_estate_for_sale_pct": 0.0,
    "land_pct": 0.0,
    "other_real_estate_pct": 0.0,
    "cri_pct": 0.0,
    "lci_pct": 0.0,
    "cepac_pct": 0.0,
    "debentures_pct": 0.0,
    "fii_holdings_pct": 15.69,
    "fip_fdic_pct": 0.0,
    "stocks_pct": 0.0,
    "cash_pct": 0.49,
    "other_pct": 0.0
  },
  "fees_paid_last_month": {
    "admin": 105112.97,
    "performance": 0.0
  },
  "property_count": 28,
  "total_area_sqm": 1595382.91,
  "vacancy_pct": 2.91,
  "delinquency_pct": 0.0,
  "leased_pct": 97.09,
  "top_properties": [
    {
      "name": "Galpão Cajamar",
      "address": "Rod. Anhanguera - Cajamar/SP",
      "asset_class": "Imóveis para renda acabados",
      "area_sqm": 125000.0,
      "revenue_pct": 45.0,
      "vacancy_pct": 2.0,
      "leased_pct": 98.0
    }
  ],
  "property_reference_date": "2024-12-31"
}
GET

/fiis/{ticker}/history

Retorna o histórico mensal de um FII: evolução do P/VP, DY mensal, NAV e cotistas.

Parâmetro Tipo Obrig. Descrição
ticker string Sim Ticker do FII (ex: HGLG11 ou HGLG)
limit int Não Número de meses (1-120, padrão: 24)
Requisição 
curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/fiis/HGLG11/history?limit=3"
Resposta 
{
  "ticker": "HGLG11",
  "name": "CSHG LOGISTICA FDO INV IMOB - FII",
  "count": 3,
  "history": [
    {
      "reference_date": "2026-02-28",
      "close_price": 162.45,
      "book_value_per_share": 148.32,
      "pvp": 1.10,
      "dy_month_pct": 0.7234,
      "value_per_share": 1.0732,
      "net_asset_value": 4523000000.0,
      "shares_outstanding": 30498200,
      "total_shareholders": 487523
    },
    {
      "reference_date": "2026-01-31",
      "close_price": 160.80,
      "book_value_per_share": 147.90,
      "pvp": 1.09,
      "dy_month_pct": 0.6892,
      "value_per_share": 1.0191,
      "net_asset_value": 4510000000.0,
      "shares_outstanding": 30498200,
      "total_shareholders": 482190
    }
    // ... mais meses
  ]
}
GET

/fiis/{ticker}/distributions

Retorna o histórico de distribuições de um FII: R$/cota mensal, totais anuais e dividend yield dos últimos 12 meses.

Parâmetro Tipo Obrig. Descrição
ticker string Sim Ticker do FII (ex: XPLG11 ou XPLG)
years int Não Anos de histórico (1-20, padrão: 5)
Requisição 
curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/fiis/XPLG11/distributions?years=2"
Resposta 
{
  "ticker": "XPLG11",
  "name": "XP LOG FDO INV IMOB - FII",
  "dividend_yield_ttm": 9.12,
  "ttm_per_share": 9.2456,
  "close_price": 101.38,
  "total_payments": 24,
  "annual_summary": [
    {
      "year": 2026,
      "total_per_share": 2.3145,
      "payments": 3
    },
    {
      "year": 2025,
      "total_per_share": 9.5623,
      "payments": 12
    }
  ],
  "payments": [
    {
      "reference_date": "2026-03-01",
      "value_per_share": 0.7832,
      "dy_month_pct": 0.7612,
      "book_value_per_share": 102.89
    },
    {
      "reference_date": "2026-02-01",
      "value_per_share": 0.7654,
      "dy_month_pct": 0.7445,
      "book_value_per_share": 102.82
    }
    // ... mais pagamentos
  ]
}
GET

/fiis/screener

Filtra todos os FIIs negociados na B3 por P/VP, dividend yield, NAV, número de cotistas e mais. Use sufixos _gt (maior que) e _lt (menor que) nos parâmetros. Conta como 1 requisição. Requer plano Pro.

Parâmetro Tipo Obrig. Descrição
{metric}_gt float Não Filtro "maior que". Métricas: pvp, dividend_yield_ttm, dy_month_pct, close_price, total_shareholders, shares_outstanding, net_asset_value, book_value_per_share, vacancy_pct, delinquency_pct, leased_pct, property_count, total_area_sqm
{metric}_lt float Não Filtro "menor que". Mesmas métricas acima
segment string Não Filtrar por segmento (ex: "Logística", "Lajes Corporativas")
management_type string Não Filtrar por tipo de gestão (ex: "Ativa", "Passiva")
mandate string Não Filtrar por mandato ("Renda", "Ganho de Capital", "Híbrido"). Valores em PT-BR pois vêm direto da CVM.
fund_type string Não Filtrar por classificação derivada do balanço: "Tijolo", "Papel", "Fundo de Fundos", "Híbrido"
administrator string Não Filtrar por administrador (case-insensitive)
sort string Não Ordenar por métrica (padrão: dividend_yield_ttm)
order string Não Ordem: "asc" ou "desc" (padrão: desc)
limit int Não Resultados por página (1-500, padrão: 50)
offset int Não Paginação (padrão: 0)
Requisição 
curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/fiis/screener?pvp_lt=1&dividend_yield_ttm_gt=8&sort=dividend_yield_ttm&order=desc&limit=10"
Resposta 
{
  "data": [
    {
      "ticker": "HGLG11",
      "name": "CSHG LOGÍSTICA FII",
      "segment": "Logística",
      "management_type": "Ativa",
      "reference_date": "2026-03-31",
      "close_price": 158.40,
      "book_value_per_share": 165.50,
      "net_asset_value": 3500000000.00,
      "shares_outstanding": 21148036,
      "total_shareholders": 350000,
      "pvp": 0.96,
      "dividend_yield_ttm": 8.42,
      "dy_month_pct": 0.65,
      "mandate": "Renda",
      "administrator_name": "CREDIT SUISSE HEDGING-GRIFFO CV S.A.",
      "fund_type": "Tijolo",
      "vacancy_pct": 2.91,
      "delinquency_pct": 0.0,
      "leased_pct": 97.09,
      "property_count": 28,
      "total_area_sqm": 1595382.91
    }
  ],
  "count": 10,
  "total": 28,
  "offset": 0,
  "limit": 10
}
GET

/fiis/{ticker}/tenants

Retorna a concentração de receita por setor de inquilino (Comércio, Serviço, Indústria, etc.) para o trimestre mais recente. Os inquilinos individuais não são publicados pela CVM; a agregação é feita por setor de atuação.

Parâmetro Tipo Obrig. Descrição
ticker string Sim Ticker do FII (ex: HGLG11)
format string Não "json" (padrão) ou "csv"
Requisição 
curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/fiis/HGLG11/tenants
Resposta 
{
  "ticker": "HGLG11",
  "reference_date": "2024-12-31",
  "count": 3,
  "top_sector_pct": 71.0,
  "sectors": [
    {"sector": "Logística", "revenue_pct": 71.0},
    {"sector": "Comércio", "revenue_pct": 20.0},
    {"sector": "Indústria", "revenue_pct": 9.0}
  ]
}

Macroeconômicos

Séries históricas do Banco Central do Brasil: SELIC, IPCA, CDI, IGP-M e demais indicadores macroeconômicos via API REST.

GET

/macro

Lista todas as séries macroeconômicas disponíveis: Selic, IPCA, CDI, USD/BRL (PTAX) e Meta Selic. O Ibovespa diário está disponível via /stocks/IBOV/stats.

Requisição 
curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/macro/
Resposta 
{
  "series": {
    "selic": { "code": "1178", "name": "Taxa Selic" },
    "selic_target": { "code": "432", "name": "Meta Selic" },
    "ipca": { "code": "433", "name": "IPCA" },
    "cdi": { "code": "4389", "name": "CDI" },
    "usd_brl": { "code": "1", "name": "USD/BRL (PTAX)" },
    "eur_brl": { "code": "21620", "name": "EUR/BRL (PTAX)" }
  }
}
GET

/macro/{series_name}

Retorna os dados históricos de uma série macroeconômica. Séries disponíveis: selic, selic_target, ipca, cdi, usd_brl, eur_brl. A série selic é a taxa Selic efetiva anualizada (base 252, % ao ano); selic_target é a meta definida pelo Copom.

Parâmetro Tipo Obrig. Descrição
series_name string Sim Nome da série: selic, selic_target, ipca, cdi, usd_brl, eur_brl
start date Não Data de início (formato: YYYY-MM-DD)
end date Não Data de fim (formato: YYYY-MM-DD)
limit int Não Número máximo de registros (1-5000, padrão: 252)
Requisição 
curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/macro/selic?start=2026-01-01&limit=5"
Resposta 
{
  "series": "selic",
  "series_code": "1178",
  "count": 5,
  "data": [
    { "date": "2026-03-21", "value": 14.15 },
    { "date": "2026-03-20", "value": 14.15 },
    { "date": "2026-03-19", "value": 14.15 },
    { "date": "2026-03-18", "value": 14.15 },
    { "date": "2026-03-17", "value": 14.15 }
  ]
}

Health

Endpoint público para verificação de disponibilidade do serviço.

GET

/health

Verifica o status de saúde da API e suas dependências (PostgreSQL e Redis). Não requer autenticação.

Requisição 
curl https://api.usebolsai.com/health
Resposta 200 
{
  "status": "ok",
  "environment": "production",
  "checks": {
    "postgres": "ok",
    "redis": "ok"
  }
}

Retorna 200 quando todos os serviços estão saudáveis, ou 503 se algum está indisponível (status: "degraded").