# SDK Python
URL: /docs/sdks/python.mdx

SDK oficial Python da brapi.dev. Biblioteca completa com type hints, suporte síncrono e assíncrono, integração com asyncio e aiohttp, tratamento de erros automático.

***

title: 'SDK Python'
description: >-
SDK oficial Python da brapi.dev. Biblioteca completa com type hints, suporte
síncrono e assíncrono, integração com asyncio e aiohttp, tratamento de erros
automático.
full: false
keywords:
brapi, sdk, python, pip, api client, asyncio, httpx
openGraph:
title: SDK Python - brapi.dev
description: >-
SDK oficial Python com type hints e suporte síncrono e assíncrono
type: website
locale: pt\_BR
lastUpdated: '2025-10-12T20:00:00.000Z'
lang: pt-BR
howToSteps:

* name: 'Instale a SDK via pip'
  text: 'Execute pip install brapi no terminal. Para melhor performance async, use pip install brapi\[aiohttp].'
* name: 'Configure a variável de ambiente com seu token'
  text: 'Crie um arquivo .env com BRAPI\_API\_KEY=seu\_token\_aqui e use python-dotenv para carregar: from dotenv import load\_dotenv; load\_dotenv().'
* name: 'Importe e inicialize o cliente Brapi'
  text: 'No seu código Python, importe com from brapi import Brapi e crie uma instância: client = Brapi(api\_key=os.environ.get("BRAPI\_API\_KEY")).'
* name: 'Busque cotações com o cliente síncrono ou assíncrono'
  text: 'Use quote = client.quote.retrieve(tickers="PETR4") para síncrono, ou await client.quote.retrieve(tickers="PETR4") com AsyncBrapi para async.'
* name: 'Trate erros usando as exceções tipadas'
  text: 'Importe exceções como NotFoundError, RateLimitError e use try/except para tratamento específico de cada tipo de erro.'
  howToTools:
* 'Python 3.8+'
* 'pip'
* 'Editor de código'
  howToSupplies:
* 'Conta brapi.dev'
* 'Token de API brapi.dev'
* 'Ambiente Python configurado'

***

SDK oficial da brapi.dev para Python 3.8+, oferecendo acesso conveniente à API REST com type hints completos e suporte síncrono e assíncrono.

## Características

* ✅ **Type hints completos** - Autocomplete e validação no IDE
* ✅ **Python 3.8+** - Compatível com versões modernas
* ✅ **Sync e Async** - Cliente síncrono e assíncrono
* ✅ **Powered by httpx** - HTTP/2 e connection pooling
* ✅ **Suporte aiohttp** - Performance assíncrona otimizada
* ✅ **Tratamento de erros** - Exceções tipadas e descritivas
* ✅ **Retry automático** - Tratamento inteligente de falhas
* ✅ **Gerado com Stainless** - Sempre atualizado com a API

## Instalação

```bash
pip install brapi
```

Com suporte a aiohttp (opcional, para melhor performance async):

```bash
pip install brapi[aiohttp]
```

<a href="https://pypi.org/project/brapi/" target="_blank" rel="noreferrer">
  <img src="https://img.shields.io/pypi/v/brapi.svg" alt="Versão no PyPI" loading="lazy" decoding="async" />
</a>

## Início Rápido

### Cliente Síncrono

```python
import os
from brapi import Brapi

client = Brapi(
    api_key=os.environ.get("BRAPI_API_KEY"),
)

# Buscar cotação
quote = client.quote.retrieve(tickers="PETR4")
print(quote.results[0].regular_market_price)

# Múltiplas ações
quotes = client.quote.retrieve(tickers="PETR4,VALE3,ITUB4")
for stock in quotes.results:
    print(f"{stock.symbol}: R$ {stock.regular_market_price}")
```

### Cliente Assíncrono

```python
import os
import asyncio
from brapi import AsyncBrapi

client = AsyncBrapi(
    api_key=os.environ.get("BRAPI_API_KEY"),
)

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

asyncio.run(main())
```

## Configuração

### Variáveis de Ambiente

Recomendamos usar `python-dotenv` para gerenciar variáveis de ambiente:

```bash
pip install python-dotenv
```

Crie um arquivo `.env`:

```bash
BRAPI_API_KEY=seu_token_aqui
```

No seu código:

```python
import os
from dotenv import load_dotenv
from brapi import Brapi

load_dotenv()

client = Brapi(
    api_key=os.environ.get("BRAPI_API_KEY"),
)
```

### Opções do Cliente

```python
client = Brapi(
    api_key="seu_token",
    environment="production",  # 'production' ou 'sandbox'
    max_retries=2,  # Número de tentativas (padrão: 2)
    timeout=60.0,  # Timeout em segundos (padrão: 60)
)
```

## Exemplos de Uso

### Cotações

```python
# Cotação única
quote = client.quote.retrieve(tickers="PETR4")
stock = quote.results[0]

print(f"Símbolo: {stock.symbol}")
print(f"Nome: {stock.short_name}")
print(f"Preço: R$ {stock.regular_market_price}")
print(f"Variação: {stock.regular_market_change_percent}%")

# Com módulos adicionais
quote_with_data = client.quote.retrieve(
    tickers="PETR4",
    modules="summaryProfile,balanceSheetHistory"
)
```

### Lista de Ações

```python
# Todas as ações disponíveis
stocks = client.quote.list()

for stock in stocks.stocks:
    print(f"{stock.stock}: {stock.name} ({stock.type})")

# Com paginação
stocks_page = client.quote.list(page=1, limit=50)
```

### Criptomoedas

```python
# Cotação de cripto
crypto = client.crypto.retrieve(coin="BTC")
print(f"Bitcoin: ${crypto.currency}")

# Lista de criptos disponíveis
cryptos = client.crypto.available()
for coin in cryptos.coins:
    print(f"{coin.coin}: {coin.name}")
```

### Moedas

```python
# Cotação de moeda
currency = client.currency.retrieve(currency="USD-BRL")
print(f"Dólar: R$ {currency.ask}")

# Lista de moedas disponíveis
currencies = client.currency.available()
```

### Inflação

```python
# Dados de inflação do Brasil
inflation = client.inflation.retrieve(country="brazil")
print(f"IPCA: {inflation.IPCA}")

# Países disponíveis
countries = client.inflation.available()
```

### Taxa de Juros

```python
# Taxa SELIC
selic = client.prime_rate.retrieve(country="brazil")
print(f"SELIC: {selic.value}%")

# Países disponíveis
countries = client.prime_rate.available()
```

## Cliente Assíncrono

### Com httpx (padrão)

```python
import asyncio
from brapi import AsyncBrapi

async def main():
    client = AsyncBrapi(api_key="seu_token")
    
    # Todas as operações usam await
    quote = await client.quote.retrieve(tickers="PETR4")
    print(quote.results[0].regular_market_price)
    
    # Não esqueça de fechar o cliente
    await client.close()

asyncio.run(main())
```

### Com Context Manager

```python
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)
    # Cliente fechado automaticamente

asyncio.run(main())
```

### Com aiohttp (melhor performance)

```python
import asyncio
from brapi import AsyncBrapi, DefaultAioHttpClient

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

asyncio.run(main())
```

### Requisições Concorrentes

```python
import asyncio
from brapi import AsyncBrapi

async def get_multiple_quotes():
    async with AsyncBrapi(api_key="seu_token") as client:
        # Buscar várias cotações em paralelo
        tasks = [
            client.quote.retrieve(tickers="PETR4"),
            client.quote.retrieve(tickers="VALE3"),
            client.quote.retrieve(tickers="ITUB4"),
        ]
        
        results = await asyncio.gather(*tasks)
        
        for quote in results:
            stock = quote.results[0]
            print(f"{stock.symbol}: R$ {stock.regular_market_price}")

asyncio.run(get_multiple_quotes())
```

## Tratamento de Erros

```python
from brapi import Brapi
from brapi import (
    APIError,
    BadRequestError,
    AuthenticationError,
    NotFoundError,
    RateLimitError,
)

client = Brapi(api_key="seu_token")

try:
    quote = client.quote.retrieve(tickers="INVALID")
except NotFoundError as e:
    print(f"Ticker não encontrado: {e}")
except RateLimitError as e:
    print(f"Limite de requisições: {e}")
except AuthenticationError as e:
    print(f"Token inválido: {e}")
except APIError as e:
    print(f"Erro na API: {e}")
```

### Tipos de Exceção

| Exception                  | Status | Descrição              |
| -------------------------- | ------ | ---------------------- |
| `BadRequestError`          | 400    | Requisição inválida    |
| `AuthenticationError`      | 401    | Token inválido         |
| `PermissionDeniedError`    | 403    | Sem permissão          |
| `NotFoundError`            | 404    | Recurso não encontrado |
| `UnprocessableEntityError` | 422    | Dados inválidos        |
| `RateLimitError`           | 429    | Limite de requisições  |
| `InternalServerError`      | 5xx    | Erro no servidor       |
| `APIConnectionError`       | N/A    | Erro de conexão        |

## Integração com Flask

```python
from flask import Flask, jsonify
from brapi import Brapi

app = Flask(__name__)
client = Brapi(api_key="seu_token")

@app.route('/api/quote/<ticker>')
def get_quote(ticker):
    try:
        quote = client.quote.retrieve(tickers=ticker)
        return jsonify({
            'symbol': quote.results[0].symbol,
            'price': quote.results[0].regular_market_price,
        })
    except NotFoundError:
        return jsonify({'error': 'Ticker not found'}), 404

if __name__ == '__main__':
    app.run()
```

## Integração com FastAPI

```python
from fastapi import FastAPI, HTTPException
from brapi import AsyncBrapi, NotFoundError

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

@app.get("/api/quote/{ticker}")
async def get_quote(ticker: str):
    try:
        quote = await client.quote.retrieve(tickers=ticker)
        return {
            'symbol': quote.results[0].symbol,
            'price': quote.results[0].regular_market_price,
        }
    except NotFoundError:
        raise HTTPException(status_code=404, detail="Ticker not found")

@app.on_event("shutdown")
async def shutdown():
    await client.close()
```

## Integração com Pandas

```python
import pandas as pd
from brapi import Brapi

client = Brapi(api_key="seu_token")

def get_quotes_dataframe(tickers: list[str]) -> pd.DataFrame:
    """Retorna cotações como DataFrame"""
    tickers_str = ','.join(tickers)
    quote = client.quote.retrieve(tickers=tickers_str)
    
    data = []
    for stock in quote.results:
        data.append({
            'symbol': stock.symbol,
            'name': stock.short_name,
            'price': stock.regular_market_price,
            'change_percent': stock.regular_market_change_percent,
        })
    
    return pd.DataFrame(data)

# Uso
df = get_quotes_dataframe(['PETR4', 'VALE3', 'ITUB4'])
print(df)

# Salvar em Excel
df.to_excel('cotacoes.xlsx', index=False)
```

## Timeouts

```python
# Timeout global
client = Brapi(
    api_key="seu_token",
    timeout=10.0,  # 10 segundos
)

# Timeout por requisição
quote = client.quote.retrieve(
    tickers="PETR4",
    timeout=5.0,  # 5 segundos
)
```

## Retry Automático

```python
# Configurar retries
client = Brapi(
    api_key="seu_token",
    max_retries=3,  # Tenta até 3 vezes
)

# Desabilitar retries
client = Brapi(
    api_key="seu_token",
    max_retries=0,  # Sem retry
)
```

## Type Hints

A SDK inclui type hints completos para todas as operações:

```python
from brapi import Brapi
from brapi.types import QuoteRetrieveResponse

client: Brapi = Brapi(api_key="seu_token")

# Type checking automático
quote: QuoteRetrieveResponse = client.quote.retrieve(tickers="PETR4")

# Autocomplete no IDE
price: float = quote.results[0].regular_market_price
```

## Boas Práticas

### 1. Reutilize o Cliente

```python
# ✅ Bom - Crie uma instância e reutilize
from brapi import Brapi

client = Brapi(api_key="seu_token")

def get_quote(ticker):
    return client.quote.retrieve(tickers=ticker)

# ❌ Ruim - Criar nova instância a cada uso
def get_quote(ticker):
    client = Brapi(api_key="seu_token")  # Não faça isso
    return client.quote.retrieve(tickers=ticker)
```

### 2. Use Variáveis de Ambiente

```python
# ✅ Bom
import os
from brapi import Brapi

client = Brapi(api_key=os.environ.get("BRAPI_API_KEY"))

# ❌ Ruim - Nunca hardcode o token
client = Brapi(api_key="meu-token-secreto")  # Não faça isso!
```

### 3. Use Context Manager com Async

```python
# ✅ Bom
async with AsyncBrapi(api_key="seu_token") as client:
    quote = await client.quote.retrieve(tickers="PETR4")
# Cliente fechado automaticamente

# ❌ Ruim
client = AsyncBrapi(api_key="seu_token")
quote = await client.quote.retrieve(tickers="PETR4")
# Esqueceu de fechar!
```

## Links Úteis

* 📦 [Pacote PyPI](https://pypi.org/project/brapi/)
* 🔧 [Repositório GitHub](https://github.com/brapi-dev/brapi-python)
* 📚 [Documentação Completa da API](/docs)
* 🐛 [Reportar Bug](https://github.com/brapi-dev/brapi-python/issues)

## Suporte

Precisa de ajuda? Entre em contato:

* 💬 [Abra uma issue](https://github.com/brapi-dev/brapi-python/issues)
* 📧 [Suporte por email](mailto:contato@brapi.dev)
* 📖 [Documentação completa](/docs)

## Contribuindo

Contribuições são bem-vindas! Veja o [guia de contribuição](https://github.com/brapi-dev/brapi-python/blob/main/CONTRIBUTING.md).

## Licença

MIT License - veja [LICENSE](https://github.com/brapi-dev/brapi-python/blob/main/LICENSE) para detalhes.