Documentação

Autenticação

Todos os endpoints /api/v1/ requerem autenticação via Bearer token. Inclua sua chave no header de cada requisição:

curl -H "Authorization: Bearer SUA_CHAVE" \
     https://quartil.com.br/api/v1/stocks

O endpoint GET /api/health é público e não requer autenticação.

Escopo dos dados

A Quartil entrega dados confiáveis e atualizados a partir de fontes oficiais. Indicadores calculados usam dados EOD oficiais, depois de ingestão e validação.

A Quartil não é terminal de trading, feed tick-by-tick, roteador de ordens ou sistema de execução. Use os dados como contexto para análise, pesquisa, produtos e agentes.

Limites de uso

Cada chave tem um limite diário de requisições baseado no plano:

O contador reseta automaticamente a cada dia. Use GET /api/v1/me para ver seu consumo atual.

Paginação

Endpoints paginados aceitam os parâmetros limit e offset:

GET /api/v1/stocks?limit=50&offset=100

A resposta inclui metadados de paginação:

{
  "count": 396,
  "items": [...],
  "limit": 50,
  "offset": 100
}

Você pode aumentar o limit para reduzir o número de requisições. Endpoints não paginados retornam todos os resultados diretamente.

Formato de resposta

Todas as respostas são em JSON. Convenções:

• Datas no formato ISO 8601: "2026-04-08"
• Valores decimais como strings para precisão: "48.94"
• Campos sem dado retornam null (nunca valores inventados)

Endpoints

GET /api/v1/me

Informações da chave de API autenticada e consumo do dia.

curl -H "Authorization: Bearer SUA_CHAVE" \
     https://quartil.com.br/api/v1/me

{
  "plan": "free",
  "requests_today": 42,
  "daily_limit": 100
}

GET /api/v1/stocks

Lista de ações com filtros e paginação.

GET /api/v1/stocks?sector=financials&stock_type=ACAO&limit=3

{
  "count": 42,
  "items": [
    {
      "ticker": "ITUB4",
      "name": "Itau Unibanco",
      "stock_type": "ACAO",
      "sector": {"name": "Financeiro", "slug": "financials"},
      "price": "32.45",
      "price_change_pct": "1.2300",
      "market_cap": "310000000000.00",
      "volume": 45678900,
      "is_active": true
    }
  ]
}

GET /api/v1/stocks/{ticker}

Dados completos de uma acao, incluindo indicadores fundamentalistas mais recentes.

GET /api/v1/stocks/PETR4

{
  "ticker": "PETR4",
  "name": "Petrobras",
  "stock_type": "ACAO",
  "sector": {"name": "Minerais Energeticos", "slug": "energy-minerals"},
  "cnpj": "33.000.167/0001-01",
  "governance_level": "NIVEL 2",
  "listing_date": "2002-04-22",
  "price": "38.94",
  "price_open": "38.50",
  "price_high": "39.20",
  "price_low": "38.30",
  "price_previous_close": "38.45",
  "price_change_pct": "1.2700",
  "market_cap": "505000000000.00",
  "volume": 89012345,
  "total_shares": 12967604860,
  "avg_volume_3m": 75000000,
  "avg_volume_10d": 80000000,
  "week_52_high": "42.50",
  "week_52_low": "30.10",
  "is_active": true,
  "last_quote_update": "2026-04-08T18:05:00-03:00",
  "pl": "5.12",
  "pvpa": "1.34",
  "dividend_yield": "12.4500",
  "roe": "26.18",
  "net_margin": "22.50",
  "ev_ebitda": "3.80",
  "roic": "18.90",
  "debt_to_equity": "0.65"
}

GET /api/v1/stocks/{ticker}/prices

Histórico de cotações OHLCV. Paginado (padrão: 500 registros).

GET /api/v1/stocks/VALE3/prices?start_date=2026-01-01&end_date=2026-03-31

{
  "count": 62,
  "items": [
    {
      "date": "2026-03-31",
      "open": "58.20",
      "high": "59.10",
      "low": "57.80",
      "close": "58.90",
      "volume": 32456789,
      "adjusted_close": "58.90"
    }
  ]
}

GET /api/v1/stocks/{ticker}/dividends

Histórico de dividendos e JCP. Paginado (padrão: 500 registros).

GET /api/v1/stocks/BBAS3/dividends?type=JCP

{
  "count": 15,
  "items": [
    {
      "payment_date": "2026-03-15",
      "ex_dividend_date": "2026-02-28",
      "rate": "0.523400",
      "dividend_type": "JCP",
      "related_to": "4T2025",
      "label": "Juros sobre Capital Próprio"
    }
  ]
}

GET /api/v1/stocks/{ticker}/financials

Demonstrações financeiras: balanço patrimonial (BP), demonstração de resultado (DRE) e fluxo de caixa (FC). Não paginado (limite configurável).

GET /api/v1/stocks/WEGE3/financials?type=is&quarterly=false&limit=2

{
  "ticker": "WEGE3",
  "income_statements": [
    {
      "date": "2025-12-31",
      "is_quarterly": false,
      "total_revenue": "32450000000.00",
      "cost_of_revenue": "21200000000.00",
      "gross_profit": "11250000000.00",
      "ebit": "7200000000.00",
      "ebitda": "8100000000.00",
      "net_income": "5800000000.00",
      "basic_eps": "2.7500",
      "diluted_eps": "2.7200"
    }
  ]
}

GET /api/v1/stocks/{ticker}/metrics

Histórico de indicadores fundamentalistas. Paginado (padrão: 500 registros).

Campos retornados: pl, pvpa, ev_ebitda, ev_ebit, psr, dividend_yield, roe, roa, roic, gross_margin, ebitda_margin, net_margin, debt_to_equity, current_ratio, net_debt_to_ebitda, eps, book_value_per_share, payout_ratio, revenue_growth_1y, earnings_growth_1y.

GET /api/v1/stocks/ITUB4/metrics?start_date=2026-01-01

{
  "count": 65,
  "items": [
    {
      "date": "2026-04-08",
      "pl": "8.20",
      "pvpa": "1.65",
      "ev_ebitda": null,
      "dividend_yield": "6.8500",
      "roe": "20.30",
      "net_margin": "24.10",
      "debt_to_equity": "2.15",
      "eps": "4.1200",
      "revenue_growth_1y": "12.50"
    }
  ]
}

GET /api/v1/movers

Maiores altas ou baixas do dia. Não paginado.

GET /api/v1/movers?direction=gainers&limit=3

[
  {
    "ticker": "MGLU3",
    "name": "Magazine Luiza",
    "sector": {"name": "Varejo", "slug": "retail-trade"},
    "price": "12.45",
    "price_change_pct": "8.5200",
    "volume": 98765432,
    "market_cap": "15000000000.00"
  }
]

GET /api/v1/bulk/stocks

Todas as ações com indicadores fundamentalistas em uma única chamada. Não paginado.

GET /api/v1/bulk/stocks

[
  {
    "ticker": "PETR4",
    "name": "Petrobras",
    "stock_type": "ACAO",
    "sector": {"name": "Minerais Energeticos", "slug": "energy-minerals"},
    "price": "38.94",
    "price_change_pct": "1.2700",
    "market_cap": "505000000000.00",
    "volume": 89012345,
    "pl": "5.12",
    "pvpa": "1.34",
    "dividend_yield": "12.4500",
    "roe": "26.18",
    "roic": "18.90",
    "net_margin": "22.50",
    "ev_ebitda": "3.80",
    "debt_to_equity": "0.65"
  }
]

Ideal para quem precisa de todos os dados de uma vez. Consome apenas 1 requisição da sua cota.

GET /api/v1/screener

Filtre ações por criterios fundamentalistas. Paginado (padrão: 100).

Opções de sort: ticker, -ticker, volume, -volume, price, -price, market_cap, -market_cap, m_pl, -m_pl, m_pvpa, -m_pvpa, m_dy, -m_dy, m_roe, -m_roe, m_roic, -m_roic, m_ev_ebitda, -m_ev_ebitda, m_net_margin, -m_net_margin. Prefixo - = decrescente.

GET /api/v1/screener?dy_min=6&roe_min=15&sort=-m_dy&limit=3

{
  "count": 28,
  "items": [
    {
      "ticker": "BBAS3",
      "name": "Banco do Brasil",
      "price": "28.50",
      "dividend_yield": "10.2500",
      "roe": "21.30",
      "pl": "4.80"
    }
  ]
}

GET /api/v1/indices

Lista de índices de mercado da B3. Não paginado.

GET /api/v1/indices?category=AMPLO

[
  {"code": "IBOV", "name": "Ibovespa", "category": "AMPLO", "is_active": true},
  {"code": "IBRX", "name": "IBrX 100", "category": "AMPLO", "is_active": true}
]

GET /api/v1/indices/{code}

Detalhes do índice com composicao atual e ultimo preco.

GET /api/v1/indices/IBOV

{
  "code": "IBOV",
  "name": "Ibovespa",
  "description": "Principal índice de ações da B3",
  "category": "AMPLO",
  "methodology_url": "https://www.b3.com.br/...",
  "is_active": true,
  "composition": [
    {"ticker": "VALE3", "name": "Vale", "weight": "12.34500", "theoretical_quantity": 1234567},
    {"ticker": "PETR4", "name": "Petrobras", "weight": "8.21000", "theoretical_quantity": 987654}
  ],
  "latest_price": {
    "date": "2026-04-08",
    "open": "128500.00",
    "high": "129200.00",
    "low": "127800.00",
    "close": "129050.00",
    "volume": 12345678900
  }
}

GET /api/v1/sectors

Lista de setores com contagem de ações ativas. Não paginado.

GET /api/v1/sectors

[
  {"name": "Financeiro", "slug": "financials", "icon": "ti ti-building-bank", "stock_count": 42},
  {"name": "Minerais Energeticos", "slug": "energy-minerals", "icon": "ti ti-flame", "stock_count": 8}
]

GET /api/v1/sectors/{slug}

Detalhes do setor com todas as ações ativas, ordenadas por valor de mercado.

GET /api/v1/sectors/financials

{
  "name": "Financeiro",
  "slug": "financials",
  "icon": "ti ti-building-bank",
  "stocks": [
    {
      "ticker": "ITUB4",
      "name": "Itau Unibanco",
      "price": "32.45",
      "price_change_pct": "1.2300",
      "market_cap": "310000000000.00",
      "volume": 45678900
    }
  ]
}

GET /api/v1/macro

Resumo com o valor mais recente de cada indicador macroeconômico. Não paginado.

GET /api/v1/macro

[
  {"indicator": "selic", "latest_date": "2026-04-02", "latest_value": "14.25", "unit": "% a.a."},
  {"indicator": "ipca", "latest_date": "2026-03-01", "latest_value": "0.56", "unit": "% mensal"},
  {"indicator": "usd_brl", "latest_date": "2026-04-08", "latest_value": "5.6320", "unit": "BRL"},
  {"indicator": "pib", "latest_date": "2025-Q4", "latest_value": "2890000.00", "unit": "R$ milhoes"}
]

GET /api/v1/macro/{indicator}

Serie temporal de um indicador específico. Paginado (padrão: 500).

Indicadores disponiveis: selic, ipca, usd_brl, eur_brl, pib, pib_sa, desemprego, producao_industrial, vendas_varejo, servicos.

GET /api/v1/macro/selic?limit=3

{
  "count": 245,
  "items": [
    {"indicator": "selic", "date": "2026-04-02", "value": "14.25", "unit": "% a.a.", "accumulated_12m": null},
    {"indicator": "selic", "date": "2026-03-19", "value": "14.25", "unit": "% a.a.", "accumulated_12m": null}
  ]
}

Para o IPCA, o campo accumulated_12m traz a inflação acumulada em 12 meses.

Erros

{"detail": "Stock 'NOPE9' not found"}

Fontes de dados

Todos os dados vem exclusivamente de fontes oficiais:

• B3 — cotações, dividendos, desdobramentos, composicao de índices
• CVM — demonstrações financeiras (DFP/ITR)
• BCB — SELIC, IPCA, taxas de cambio
• IBGE — PIB, desemprego, producao industrial, varejo, servicos

Sem scraping, sem fontes não oficiais. Dados que você pode confiar.

Servidor MCP

Além da API REST, os mesmos dados estão disponíveis via servidor MCP para assistentes de IA.

Ver documentação do MCP →

Para LLMs e agentes

Disponibilizamos um arquivo llms.txt com a referência compacta de toda a API, otimizado para consumo por LLMs e agentes autônomos.