# Dicionário de Campos da API
URL: /docs/dicionario.mdx

Consulte todos os campos disponíveis na API da brapi com nomes em português, descrições detalhadas, fórmulas de cálculo, tipos, unidades e endpoints. Entenda por que alguns campos retornam null.

***

title: Dicionário de Campos da API
description: >-
Consulte todos os campos disponíveis na API da brapi com nomes em português,
descrições detalhadas, fórmulas de cálculo, tipos, unidades e endpoints.
Entenda por que alguns campos retornam null.
full: true
keywords: brapi, api, dicionário, campos, documentação, null, referência
openGraph:
title: Dicionário de Campos da API
description: >-
Consulte todos os campos da API da brapi: nomes em português, descrições,
fórmulas, tipos, unidades e endpoints. Entenda por que campos retornam null.
type: website
locale: pt\_BR
lastUpdated: '2026-05-22T00:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/dictionary
-------------------------

import { Callout } from 'fumadocs-ui/components/callout';
import { Card, Cards } from 'fumadocs-ui/components/card';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

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.

<Callout title="Endpoint público" type="info">
  `GET /api/v2/dictionary` — sem autenticação, sem limites de plano. Ideal para
  construir tooltips, labels dinâmicos, documentação automatizada e integrações.
</Callout>

## 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

<Tabs items={['cURL', 'TypeScript', 'Python']}>
  <Tab value="cURL">
    ```bash
    # 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"
    ```
  </Tab>

  <Tab value="TypeScript">
    ```typescript
    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"
    ```
  </Tab>

  <Tab value="Python">
    ```python
    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"
    ```
  </Tab>
</Tabs>

## 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

```json
{
  "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

<Tabs items={['Cotações', 'Demonstrativos', 'FIIs', 'Tesouro Direto', 'Dividendos']}>
  <Tab value="Cotações">
    ```bash
    # 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"
    ```
  </Tab>

  <Tab value="Demonstrativos">
    ```bash
    # 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"
    ```
  </Tab>

  <Tab value="FIIs">
    ```bash
    # 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"
    ```
  </Tab>

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

  <Tab value="Dividendos">
    ```bash
    # Campos de dividendos e JCP
    curl "https://brapi.dev/api/v2/dictionary?category=dividends"
    ```
  </Tab>
</Tabs>

## 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:

| 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`.                                                                                                             |

<Callout title="Dica" type="info">
  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.
</Callout>

## Perguntas frequentes

<AnswerBox
  question="O dicionário requer autenticação?"
  answer="Não. O endpoint /api/v2/dictionary é 100% público e não exige token nem plano pago."
  relatedEndpoints={[
  { name: 'dictionary', path: '/api/v2/dictionary' },
]}
/>

<AnswerBox question="Como descobrir todos os campos de uma categoria?" answer="Use o parâmetro category. Por exemplo, /api/v2/dictionary?category=balance-sheet retorna todos os campos do Balanço Patrimonial." codeExample={`curl "https://brapi.dev/api/v2/dictionary?category=balance-sheet"`} />

<AnswerBox question="Como saber se um campo tem fórmula de cálculo?" answer="O campo calculation da entrada do dicionário contém a fórmula quando aplicável. Se for null, o campo é um dado primário (não calculado)." />

<AnswerBox question="Por que um campo do balanço retorna null para bancos?" answer="Instituições financeiras usam o Plano Cosif, que organiza o balanço de forma diferente. Campos como costOfRevenue e grossProfit não se aplicam. Use /api/v2/dictionary?search=deposits para ver os campos específicos de bancos." codeExample={`curl "https://brapi.dev/api/v2/dictionary?category=balance-sheet&search=depósito"`} />

<AnswerBox
  question="Como usar o dicionário para gerar tooltips na minha aplicação?"
  answer="Busque os campos da categoria que você está exibindo e use label como título do tooltip e description como conteúdo. O campo unit ajuda a formatar o valor."
  codeExample={`const dict = await fetch('/api/v2/dictionary?category=fii').then(r => r.json());
const tooltips = Object.fromEntries(dict.fields.map(f => [f.key, { label: f.label, desc: f.description, unit: f.unit }]));`}
/>

<br />