Dicionário de Campos da API

O dicionário é um endpoint público (não requer autenticação) que retorna todos os campos disponíveis na API, com nome em português, descrição detalhada, fórmula de cálculo, tipo de dado, unidade e em quais endpoints cada campo aparece.

Como usar

O endpoint aceita dois parâmetros de query opcionais:

Ambos podem ser combinados: ?category=balance-sheet&search=ativo.

Início rápido

# Listar todos os campos
curl "https://brapi.dev/api/v2/dictionary"

# Buscar por termo
curl "https://brapi.dev/api/v2/dictionary?search=patrimônio"

# Filtrar por categoria
curl "https://brapi.dev/api/v2/dictionary?category=fii"

# Combinar busca e categoria
curl "https://brapi.dev/api/v2/dictionary?category=balance-sheet&search=ativo"

const BASE = 'https://brapi.dev/api/v2/dictionary';

// Listar todos os campos
const all = await fetch(BASE).then((r) => r.json());

// Buscar por termo
const search = await fetch(`${BASE}?search=patrimônio`).then((r) => r.json());

// Filtrar por categoria
const fiiFields = await fetch(`${BASE}?category=fii`).then((r) => r.json());

// Gerar labels dinâmicos a partir do dicionário
const labelMap = Object.fromEntries(
  all.fields.map((f) => [f.key, f.label]),
);
console.log(labelMap['dividendYield12m']); // "Dividend Yield 12 meses"

import requests

BASE = "https://brapi.dev/api/v2/dictionary"

# Listar todos os campos
all_fields = requests.get(BASE).json()

# Buscar por termo
search = requests.get(BASE, params={"search": "patrimônio"}).json()

# Filtrar por categoria
fii_fields = requests.get(BASE, params={"category": "fii"}).json()

# Gerar labels dinâmicos
label_map = {f["key"]: f["label"] for f in all_fields["fields"]}
print(label_map["dividendYield12m"])  # "Dividend Yield 12 meses"

Estrutura de cada entrada

Cada campo retornado contém:

Exemplo de resposta

{
  "fields": [
    {
      "key": "dividendYield12m",
      "label": "Dividend Yield 12 meses",
      "description": "Rendimento de dividendos/rendimentos acumulados dos últimos 12 meses em relação ao preço atual da cota",
      "calculation": "(soma dos rendimentos dos últimos 12 meses / preço atual) × 100",
      "endpoints": ["/api/v2/fii/indicators", "/api/v2/fii/indicators/history"],
      "category": "fii",
      "type": "number",
      "unit": "%"
    }
  ],
  "requestedAt": "2026-05-22T12:00:00.000Z",
  "took": 1
}

Categorias disponíveis

Use o parâmetro category para filtrar campos por área:

Exemplos por categoria

# Campos de cotação (preço, variação, volume, etc.)
curl "https://brapi.dev/api/v2/dictionary?category=quote"

# Campos históricos (OHLCV)
curl "https://brapi.dev/api/v2/dictionary?category=historical"

# Balanço Patrimonial
curl "https://brapi.dev/api/v2/dictionary?category=balance-sheet"

# DRE
curl "https://brapi.dev/api/v2/dictionary?category=income-statement"

# Fluxo de Caixa
curl "https://brapi.dev/api/v2/dictionary?category=cash-flow"

# Dados financeiros agregados
curl "https://brapi.dev/api/v2/dictionary?category=financial-data"

# Indicadores de FIIs (P/VP, DY, vacância, etc.)
curl "https://brapi.dev/api/v2/dictionary?category=fii"

# Relatórios CVM de FIIs
curl "https://brapi.dev/api/v2/dictionary?category=fii-reports"

# Campos de Tesouro Direto (taxas, preços indicativos, indexadores)
curl "https://brapi.dev/api/v2/dictionary?category=treasury"

# Campos de dividendos e JCP
curl "https://brapi.dev/api/v2/dictionary?category=dividends"

Casos de uso

• Labels dinâmicos: use label para exibir nomes em português na sua interface sem manter uma tabela manual de traduções.
• Tooltips/descrições: use description para mostrar o que cada campo significa ao passar o mouse.
• Fórmulas: mostre calculation para que o usuário entenda como um indicador é calculado (ex: "Dividend Yield = (rendimentos 12m / preço) × 100").
• Tipos e unidades: use type e unit para formatar valores automaticamente (ex: number + % → 12,5%; number + R$ → R$ 1.234,56).
• Documentação automatizada: gere páginas de referência a partir do dicionário para manter sua documentação interna sempre atualizada com a API.

Por que este campo está null?

Alguns campos retornam null em determinadas consultas. Isso é esperado e acontece por diferentes razões:

Disponibilidade na fonte

Nem todos os campos são publicados para todos os ativos. A brapi consolida dados de fontes oficiais (CVM, B3, BCB) e cada fonte tem cobertura diferente. Se uma empresa ou fundo não publica determinada informação, o campo correspondente retorna null.

Diferenças por setor e padrão contábil

Empresas de setores distintos seguem padrões contábeis diferentes. Campos como costOfRevenue (custo da receita) e grossProfit (lucro bruto) são comuns em indústria e comércio, mas instituições financeiras e bancos usam o Plano Cosif — seus balanços não separam custo de receita da mesma forma, então esses campos vêm como null.

Exemplos comuns:

Seguradoras

Seguradoras seguem normas contábeis específicas da SUSEP. Vários campos do balanço padrão (como propertyPlantEquipment) podem vir como null porque a estrutura patrimonial de seguradoras é organizada de forma diferente (provisões técnicas, sinistros, prêmios).

Small caps e empresas sem demonstrativos recentes

Empresas de menor porte ou que não enviaram demonstrativos recentes à CVM podem ter campos fundamentalistas como null. Isso é comum em:

• Empresas que acabaram de abrir capital (IPO recente)
• Empresas com demonstrativos atrasados ou em análise na CVM
• Ativos com baixa liquidez e pouca cobertura

Campos que não se aplicam ao tipo de ativo

Diferentes tipos de ativos têm campos diferentes. Campos que existem para ações não necessariamente se aplicam a outros tipos:

Perguntas frequentes

curl -X GET "https://brapi.dev/api/v2/dictionary"

{
  "fields": [
    {
      "key": "symbol",
      "label": "Símbolo",
      "description": "Código de negociação do ativo brasileiro (ex: PETR4, VALE3)",
      "calculation": null,
      "endpoints": [
        "/api/quote/{tickers}",
        "/api/quote/list"
      ],
      "category": "quote",
      "type": "string",
      "unit": null
    },
    {
      "key": "shortName",
      "label": "Nome Curto",
      "description": "Nome resumido do ativo",
      "calculation": null,
      "endpoints": [
        "/api/quote/{tickers}",
        "/api/quote/list"
      ],
      "category": "quote",
      "type": "string",
      "unit": null
    },
    {
      "key": "longName",
      "label": "Nome Completo",
      "description": "Nome completo da empresa ou fundo",
      "calculation": null,
      "endpoints": [
        "/api/quote/{tickers}"
      ],
      "category": "quote",
      "type": "string",
      "unit": null
    }
  ],
  "requestedAt": "2026-02-08T16:25:35.000Z",
  "took": 2
}