SDKs Oficiais

Use as SDKs oficiais quando quiser chamar a brapi com tipos, retry e tratamento de erros já configurados. Elas são úteis para backends, scripts, dashboards e integrações que consultam a API com frequência.

Por que usar as SDKs?

Requisição HTTP manual

const response = await fetch("https://brapi.dev/api/quote/PETR4", {
  headers: { Authorization: `Bearer ${token}` },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
const price = data.results[0].regularMarketPrice; // sem tipos gerados

Com SDK

const quote = await client.quote.retrieve('PETR4');
const price = quote.results[0].regularMarketPrice; // tipado pelo SDK

As SDKs reduzem boilerplate e deixam explícitos os casos importantes:

tipos para autocomplete e validação no editor
retry configurável
erros específicos por status
clientes síncronos ou assíncronos, dependendo da linguagem
mesma autenticação da API REST

SDKs disponíveis

TypeScript / JavaScript

SDK oficial para TypeScript e JavaScript com suporte a Node.js e navegador.

Instalação

npm install brapi
# ou
yarn add brapi
# ou
pnpm add brapi
# ou
bun add brapi

Exemplo rápido

import Brapi from 'brapi';

const client = new Brapi({
  apiKey: process.env.BRAPI_API_KEY,
});

const quote = await client.quote.retrieve('PETR4');
console.log(quote.results[0].regularMarketPrice);

Características

Tipos TypeScript
Suporte a Node.js e navegador
Bundle tree-shakeable
Integração com Next.js, Express e outros frameworks
Retry automático configurável

Links:

Python

SDK oficial para Python 3.8+ com suporte síncrono e assíncrono.

Instalação

pip install brapi

# Com suporte a aiohttp (opcional, melhor performance)
pip install brapi[aiohttp]

Exemplo rápido (síncrono)

from brapi import Brapi

client = Brapi(api_key="seu_token")
quote = client.quote.retrieve(tickers="PETR4")
print(quote.results[0].regular_market_price)

Exemplo rápido (assíncrono)

import asyncio
from brapi import AsyncBrapi

async def main():
    async with AsyncBrapi(api_key="seu_token") as client:
        quote = await client.quote.retrieve(tickers="PETR4")
        print(quote.results[0].regular_market_price)

asyncio.run(main())

Características

Type hints
Cliente síncrono e assíncrono
httpx com suporte a HTTP/2
Integração com Flask, FastAPI e Pandas
Context managers

Links:

Comparação

Feature	TypeScript/JS	Python
Tipos	TypeScript	Type hints
Autocomplete IDE	Sim	Sim
Sync/Async	Async	Ambos
Retry automático	Sim	Sim
Erros tipados	Sim	Sim
HTTP/2	Sim	Sim
Bundle size	Pequeno	N/A
Python 3.8+	N/A	Sim
Node.js/Browser	Sim	N/A

Casos de Uso

1. Aplicações Web

Next.js / React:

import Brapi from 'brapi';

// Server Component
const client = new Brapi({ apiKey: process.env.BRAPI_API_KEY });
const quote = await client.quote.retrieve('PETR4');

FastAPI / Flask:

from fastapi import FastAPI
from brapi import AsyncBrapi

app = FastAPI()
client = AsyncBrapi(api_key="seu_token")

@app.get("/quote/{ticker}")
async def get_quote(ticker: str):
    quote = await client.quote.retrieve(tickers=ticker)
    return quote.results[0]

2. Análise de Dados

Python com Pandas:

import pandas as pd
from brapi import Brapi

client = Brapi(api_key="seu_token")

# Buscar múltiplas cotações
tickers = "PETR4,VALE3,ITUB4"
quote = client.quote.retrieve(tickers=tickers)

# Converter para DataFrame
df = pd.DataFrame([
    {
        'symbol': r.symbol,
        'price': r.regular_market_price,
        'change': r.regular_market_change_percent
    }
    for r in quote.results
])

print(df)

3. Scripts e Automação

Monitoramento de Preços:

from brapi import Brapi
import time

client = Brapi(api_key="seu_token")

while True:
    quote = client.quote.retrieve(tickers="PETR4")
    price = quote.results[0].regular_market_price
    print(f"PETR4: R$ {price:.2f}")
    time.sleep(60)  # Atualiza a cada minuto

4. APIs e Microsserviços

Express.js API:

import express from 'express';
import Brapi from 'brapi';

const app = express();
const client = new Brapi({ apiKey: process.env.BRAPI_API_KEY });

app.get('/api/quote/:ticker', async (req, res) => {
  try {
    const quote = await client.quote.retrieve(req.params.ticker);
    res.json(quote);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000);

5. Dashboards e Visualizações

TypeScript com Chart.js:

const client = new Brapi({ apiKey: process.env.BRAPI_API_KEY });

async function updateChart() {
  const quote = await client.quote.retrieve('PETR4,VALE3,ITUB4');
  
  const labels = quote.results.map(r => r.symbol);
  const prices = quote.results.map(r => r.regularMarketPrice);
  
  // Atualizar gráfico com os dados
  chart.data.labels = labels;
  chart.data.datasets[0].data = prices;
  chart.update();
}

Recursos suportados

Ambas as SDKs suportam todos os endpoints da API:

Mercado Brasileiro

Cotações - ações, ETFs, FIIs e BDRs
Dados fundamentalistas - balanços, DRE e indicadores
Dividendos - histórico de proventos
Histórico - preços históricos

Criptomoedas

Preços - Bitcoin, Ethereum e outros criptoativos
Lista de moedas disponíveis

Indicadores Econômicos

Inflação - IPCA, IGP-M e outros índices
Taxa de juros - SELIC e CDI
Câmbio - USD, EUR e outras moedas

Tratamento de erros

Ambas as SDKs lançam exceções específicas por tipo de erro:

TypeScript

import Brapi from 'brapi';

try {
  const quote = await client.quote.retrieve('INVALID');
} catch (error) {
  if (error instanceof Brapi.NotFoundError) {
    console.log('Ticker não encontrado');
  } else if (error instanceof Brapi.RateLimitError) {
    console.log('Limite de requisições atingido');
  } else if (error instanceof Brapi.AuthenticationError) {
    console.log('Token inválido');
  }
}

Python

from brapi import Brapi, NotFoundError, RateLimitError

try:
    quote = client.quote.retrieve(tickers="INVALID")
except NotFoundError:
    print("Ticker não encontrado")
except RateLimitError:
    print("Limite de requisições atingido")

Configuração avançada

Retry automático

// TypeScript
const client = new Brapi({
  apiKey: process.env.BRAPI_API_KEY,
  maxRetries: 3,  // Tenta até 3 vezes
});

# Python
client = Brapi(
    api_key="seu_token",
    max_retries=3,  # Tenta até 3 vezes
)

Timeouts

// TypeScript
const client = new Brapi({
  apiKey: process.env.BRAPI_API_KEY,
  timeout: 10000,  // 10 segundos
});

# Python
client = Brapi(
    api_key="seu_token",
    timeout=10.0,  # 10 segundos
)

Como as SDKs são mantidas

As SDKs são geradas com Stainless a partir da especificação da API. Isso mantém tipos, métodos e documentação inline alinhados com os endpoints publicados.

Tipos gerados a partir da especificação
Documentação inline nos clientes
Testes automáticos nos repositórios das SDKs

Começar a usar

Escolha a SDK da sua linguagem:

TypeScript / JavaScript

npm install brapi

Ver documentação TypeScript

Links:

Python

pip install brapi

Ver documentação Python

Links:

Futuras SDKs

Estamos trabalhando em SDKs para:

Go - em desenvolvimento
PHP - planejado
Java - planejado
Ruby - planejado

Sugestões de SDKs podem ser enviadas pelo GitHub.

Suporte e comunidade

Open Source

As SDKs são open source e licenciadas sob MIT.

Por que usar as SDKs?

Requisição HTTP manual

const response = await fetch("https://brapi.dev/api/quote/PETR4", {
  headers: { Authorization: `Bearer ${token}` },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
const price = data.results[0].regularMarketPrice; // sem tipos gerados

Com SDK

const quote = await client.quote.retrieve('PETR4');
const price = quote.results[0].regularMarketPrice; // tipado pelo SDK

As SDKs reduzem boilerplate e deixam explícitos os casos importantes:

tipos para autocomplete e validação no editor
retry configurável
erros específicos por status
clientes síncronos ou assíncronos, dependendo da linguagem
mesma autenticação da API REST

SDKs disponíveis

TypeScript / JavaScript

SDK oficial para TypeScript e JavaScript com suporte a Node.js e navegador.

Instalação

npm install brapi
# ou
yarn add brapi
# ou
pnpm add brapi
# ou
bun add brapi

Exemplo rápido

import Brapi from 'brapi';

const client = new Brapi({
  apiKey: process.env.BRAPI_API_KEY,
});

const quote = await client.quote.retrieve('PETR4');
console.log(quote.results[0].regularMarketPrice);

Características

Tipos TypeScript
Suporte a Node.js e navegador
Bundle tree-shakeable
Integração com Next.js, Express e outros frameworks
Retry automático configurável

Links:

Python

SDK oficial para Python 3.8+ com suporte síncrono e assíncrono.

Instalação

pip install brapi

# Com suporte a aiohttp (opcional, melhor performance)
pip install brapi[aiohttp]

Exemplo rápido (síncrono)

from brapi import Brapi

client = Brapi(api_key="seu_token")
quote = client.quote.retrieve(tickers="PETR4")
print(quote.results[0].regular_market_price)

Exemplo rápido (assíncrono)

import asyncio
from brapi import AsyncBrapi

async def main():
    async with AsyncBrapi(api_key="seu_token") as client:
        quote = await client.quote.retrieve(tickers="PETR4")
        print(quote.results[0].regular_market_price)

asyncio.run(main())

Características

Type hints
Cliente síncrono e assíncrono
httpx com suporte a HTTP/2
Integração com Flask, FastAPI e Pandas
Context managers

Links:

Comparação

Feature	TypeScript/JS	Python
Tipos	TypeScript	Type hints
Autocomplete IDE	Sim	Sim
Sync/Async	Async	Ambos
Retry automático	Sim	Sim
Erros tipados	Sim	Sim
HTTP/2	Sim	Sim
Bundle size	Pequeno	N/A
Python 3.8+	N/A	Sim
Node.js/Browser	Sim	N/A

Casos de Uso

1. Aplicações Web

Next.js / React:

import Brapi from 'brapi';

// Server Component
const client = new Brapi({ apiKey: process.env.BRAPI_API_KEY });
const quote = await client.quote.retrieve('PETR4');

FastAPI / Flask:

from fastapi import FastAPI
from brapi import AsyncBrapi

app = FastAPI()
client = AsyncBrapi(api_key="seu_token")

@app.get("/quote/{ticker}")
async def get_quote(ticker: str):
    quote = await client.quote.retrieve(tickers=ticker)
    return quote.results[0]

2. Análise de Dados

Python com Pandas:

import pandas as pd
from brapi import Brapi

client = Brapi(api_key="seu_token")

# Buscar múltiplas cotações
tickers = "PETR4,VALE3,ITUB4"
quote = client.quote.retrieve(tickers=tickers)

# Converter para DataFrame
df = pd.DataFrame([
    {
        'symbol': r.symbol,
        'price': r.regular_market_price,
        'change': r.regular_market_change_percent
    }
    for r in quote.results
])

print(df)

3. Scripts e Automação

Monitoramento de Preços:

from brapi import Brapi
import time

client = Brapi(api_key="seu_token")

while True:
    quote = client.quote.retrieve(tickers="PETR4")
    price = quote.results[0].regular_market_price
    print(f"PETR4: R$ {price:.2f}")
    time.sleep(60)  # Atualiza a cada minuto

4. APIs e Microsserviços

Express.js API:

import express from 'express';
import Brapi from 'brapi';

const app = express();
const client = new Brapi({ apiKey: process.env.BRAPI_API_KEY });

app.get('/api/quote/:ticker', async (req, res) => {
  try {
    const quote = await client.quote.retrieve(req.params.ticker);
    res.json(quote);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000);

5. Dashboards e Visualizações

TypeScript com Chart.js:

const client = new Brapi({ apiKey: process.env.BRAPI_API_KEY });

async function updateChart() {
  const quote = await client.quote.retrieve('PETR4,VALE3,ITUB4');
  
  const labels = quote.results.map(r => r.symbol);
  const prices = quote.results.map(r => r.regularMarketPrice);
  
  // Atualizar gráfico com os dados
  chart.data.labels = labels;
  chart.data.datasets[0].data = prices;
  chart.update();
}

Recursos suportados

Ambas as SDKs suportam todos os endpoints da API:

Mercado Brasileiro

Cotações - ações, ETFs, FIIs e BDRs
Dados fundamentalistas - balanços, DRE e indicadores
Dividendos - histórico de proventos
Histórico - preços históricos

Criptomoedas

Preços - Bitcoin, Ethereum e outros criptoativos
Lista de moedas disponíveis

Indicadores Econômicos

Inflação - IPCA, IGP-M e outros índices
Taxa de juros - SELIC e CDI
Câmbio - USD, EUR e outras moedas

Tratamento de erros

Ambas as SDKs lançam exceções específicas por tipo de erro:

TypeScript

import Brapi from 'brapi';

try {
  const quote = await client.quote.retrieve('INVALID');
} catch (error) {
  if (error instanceof Brapi.NotFoundError) {
    console.log('Ticker não encontrado');
  } else if (error instanceof Brapi.RateLimitError) {
    console.log('Limite de requisições atingido');
  } else if (error instanceof Brapi.AuthenticationError) {
    console.log('Token inválido');
  }
}

Python

from brapi import Brapi, NotFoundError, RateLimitError

try:
    quote = client.quote.retrieve(tickers="INVALID")
except NotFoundError:
    print("Ticker não encontrado")
except RateLimitError:
    print("Limite de requisições atingido")

Configuração avançada

Retry automático

// TypeScript
const client = new Brapi({
  apiKey: process.env.BRAPI_API_KEY,
  maxRetries: 3,  // Tenta até 3 vezes
});

# Python
client = Brapi(
    api_key="seu_token",
    max_retries=3,  # Tenta até 3 vezes
)

Timeouts

// TypeScript
const client = new Brapi({
  apiKey: process.env.BRAPI_API_KEY,
  timeout: 10000,  // 10 segundos
});

# Python
client = Brapi(
    api_key="seu_token",
    timeout=10.0,  # 10 segundos
)

Como as SDKs são mantidas

As SDKs são geradas com Stainless a partir da especificação da API. Isso mantém tipos, métodos e documentação inline alinhados com os endpoints publicados.