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.

Endpoint público

GET /api/v2/dictionary — sem autenticação, sem limites de plano. Ideal para construir tooltips, labels dinâmicos, documentação automatizada e integrações.

Como usar

O endpoint aceita dois parâmetros de query opcionais:

Parâmetro	Descrição	Exemplo
`search`	Busca textual em key, label, description, category e endpoints	`?search=patrimônio`
`category`	Filtra por categoria (case-insensitive)	`?category=fii`

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"

Estrutura de cada entrada

Cada campo retornado contém:

Campo	Tipo	Descrição
`key`	string	Identificador do campo (ex: `dividendYield12m`)
`label`	string	Nome em português (ex: "Dividend Yield 12 meses")
`description`	string	Descrição detalhada do que o campo representa
`calculation`	string \| null	Fórmula de cálculo, quando aplicável
`endpoints`	string[]	Endpoints onde o campo aparece
`category`	string	Categoria do campo
`type`	string	Tipo de dado: `number`, `string`, `boolean`, `date`, `object`, `array`
`unit`	string \| null	Unidade de medida (`%`, `R$`, etc.)

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:

Categoria	Descrição	Exemplo de endpoint
`quote`	Cotações de ações, FIIs, ETFs, BDRs	`/api/quote/{tickers}`
`historical`	Dados históricos OHLCV	`/api/quote/{tickers}`
`financial-data`	Dados financeiros (receita, EBITDA, margens)	`/api/quote/{tickers}?modules=financialData`
`balance-sheet`	Balanço Patrimonial	`/api/quote/{tickers}?modules=balanceSheetHistory`
`income-statement`	Demonstração de Resultado (DRE)	`/api/quote/{tickers}?modules=incomeStatementHistory`
`cash-flow`	Demonstração de Fluxo de Caixa (DFC)	`/api/quote/{tickers}?modules=cashflowHistory`
`value-added`	Demonstração de Valor Adicionado (DVA)	`/api/quote/{tickers}?modules=valueAddedHistory`
`statistics`	Estatísticas-chave (P/L, ROE, Valor de Mercado)	`/api/quote/{tickers}?modules=defaultKeyStatistics`
`dividends`	Dividendos e JCP	`/api/quote/{tickers}?dividends=true`
`fii`	Indicadores de Fundos Imobiliários	`/api/v2/fii/indicators`
`fii-reports`	Relatórios gerenciais mensais da CVM	`/api/v2/fii/reports`
`treasury`	Tesouro Direto (taxas e preços)	`/api/v2/treasury/indicators`
`crypto`	Criptomoedas	`/api/v2/crypto`
`currency`	Taxas de câmbio	`/api/v2/currency`
`inflation`	Indicadores de inflação (IPCA, IGPM)	`/api/v2/inflation`
`prime-rate`	Taxa SELIC	`/api/v2/prime-rate`
`futures`	Contratos futuros B3	`/api/v2/futures/*`
`future-options`	Opções sobre futuros	`/api/v2/futures/options/*`

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"

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:

Cobertura por ativo

Nem todo campo se aplica a todo ativo. A brapi consolida dados da CVM, B3 e BCB, e cada mercado tem um modelo próprio de divulgação. Quando um campo não se aplica ao ativo ou ao período consultado, ele 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:

Campos	Quem tem	Quem não tem
`costOfRevenue`, `grossProfit`	Indústria, comércio, varejo	Bancos, seguradoras, holdings financeiras
`inventories`, `accountsReceivable`	Comércio, indústria	Bancos, seguradoras
`deposits`, `loansNet`	Bancos	Empresas não-financeiras

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:

Tipo de ativo	Campos que retornam null
FIIs	Campos de balanço patrimonial de empresas (`grossProfit`, `ebitda`, etc.). Use `category=fii` e `category=fii-reports` no dicionário para ver os campos específicos de FIIs.
ETFs	Campos fundamentalistas (não têm balanço próprio).
BDRs	Alguns campos fundamentalistas podem estar indisponíveis (dados da empresa estrangeira).
Índices (ex: ^BVSP)	A maioria dos campos além de cotação e histórico retorna `null`.

Dica

Use o dicionário para descobrir quais campos pertencem a cada categoria e endpoint. Se um campo aparece no endpoint que você está consultando mas retorna null, provavelmente é uma das situações acima.

Perguntas frequentes

Query Parameters

search?string

Termo de busca para filtrar campos (busca em key, label, description e category)

category?string

Filtrar por categoria (ex: fii, treasury, quote, balance-sheet, income-statement)

Response Body

`application/json`

curl -X GET "https://example.com/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}

Dicionário de Campos da API

200application/json

200application/json

`application/json`

`application/json`