SDK Python

Integre dados do mercado financeiro brasileiro às suas aplicações com o SDK Python oficial da Partnr API.

O pacote partnr-api oferece um cliente autenticado e tipado para consultar empresas listadas, demonstrações financeiras, indicadores fundamentalistas, cotações, fundos, notícias, dados macroeconômicos e screeners sem precisar construir manualmente requisições HTTP.

O SDK é indicado para aplicações backend, APIs, pipelines de dados, notebooks, modelos quantitativos, processos de research, automações e projetos de inteligência artificial.

SDKs apenas server-side

As SDKs são destinadas a ambientes server-side (backend). Não utilize em frontend/browser, pois a chave de API não deve ser exposta. Para uso em apps web/mobile, crie um proxy no seu backend.

Requisitos

Antes da instalação, verifique se o ambiente utiliza:

• Python 3.9 ou superior
• Um gerenciador de pacotes compatível, como pip, Poetry ou uv
• Uma API key válida da Partnr
• HTTPS liberado para comunicação com a Partnr API

A biblioteca utiliza modelos tipados para representar as respostas e um cliente HTTP para gerenciar as requisições.

Instalação

Você pode instalar a SDK usando qualquer um dos seguintes comandos, de acordo com o seu gerenciador de dependências preferido.

pip install partnr-api

poetry add partnr-api

uv add partnr-api

Configuração

from partnr_api import PartnrClient

client = PartnrClient(api_key="SUA_API_KEY")

Faça sua primeira consulta

Depois de instalar o pacote e configurar a credencial, consulte uma empresa listada:

from partnr import PartnrClient

client = PartnrClient()

company = client.companies.get("PETR3")

print(company.trading_name)

O método retorna um objeto tipado. Isso permite acessar propriedades da resposta diretamente, com autocomplete e validação durante o desenvolvimento.

Importação principal e compatibilidade

A importação recomendada é:

from partnr import PartnrClient

A importação pelo namespace do pacote também é suportada por compatibilidade:

from partnr_api import PartnrClient

Para novos projetos, prefira from partnr import PartnrClient e mantenha o mesmo padrão em todos os arquivos da aplicação.

Configuração do cliente

O cliente pode receber configurações adicionais para controlar URL, timeout, retries e headers personalizados.

from partnr import PartnrClient

client = PartnrClient(
    api_key="SUA_API_KEY",
    base_url="https://data.partnr.ai/v2/",
    timeout=30.0,
    max_retries=2,
    headers={
        "X-Custom-Header": "value",
    },
)

Opções disponíveis

Opção	Função
api_key	Credencial utilizada na autenticação
base_url	Endereço base da Partnr API
timeout	Tempo máximo de espera por requisição
max_retries	Quantidade máxima de novas tentativas
headers	Headers adicionais enviados nas requisições

Na maioria das integrações, informar a API key ou configurar PARTNR_API_KEY é suficiente.

Utilização como context manager

O cliente pode ser utilizado como context manager para garantir o fechamento adequado das conexões:

from partnr import PartnrClient

with PartnrClient() as client:
    company = client.companies.get("PETR3")
    print(company.trading_name)

Esse padrão é útil em scripts, jobs e processos com ciclo de vida bem definido.

Consultar empresas listadas

Para listar empresas:

companies = client.companies.list()

for company in companies:
    print(company.symbol, company.trading_name)

Também é possível solicitar campos opcionais:

companies = client.companies.list(
    show_sector=True,
    show_market_cap=True,
)

Para consultar uma empresa específica:

company = client.companies.get(
    "PETR3",
    show_market_cap=True,
    show_logo=True,
    show_company_details=True,
)

print(company.trading_name)

if company.market_cap:
    print(company.market_cap.value)

A consulta pode utilizar diferentes identificadores aceitos pelo recurso, como ticker ou identificador cadastral, conforme a documentação de empresas.

Consulte a documentação de empresas.

Consultar cotações históricas

Utilize o módulo quotes para acessar o histórico de preços:

quotes = client.quotes.get_historical_quotes(
    "PETR4",
    start_date="2025-01-01",
    end_date="2025-12-31",
    adjusted=True,
)

for quote in quotes:
    print(
        quote.date,
        quote.close_price,
        quote.volume,
    )

O parâmetro adjusted indica se a série deve considerar os ajustes suportados pelo recurso.

Consulte a documentação de cotações.

Executar um screener de ações

O SDK permite criar rankings com filtros de preço, setor e indicadores:

results = client.screener.run(
    order_by="droplet:PRICE_TO_EARNINGS",
    order="asc",
    limit=10,
    primary_only=True,
    filters=[
        {
            "type": "close_price",
            "op": ">=",
            "value": 5,
        },
        {
            "type": "sector",
            "in": ["BANKING", "TECHNOLOGY"],
        },
        {
            "type": "droplet:PRICE_TO_EARNINGS",
            "op": "<",
            "value": 15,
        },
    ],
)

for item in results.data:
    print(item.ticker, item.current_price)

Consulte a documentação do Screener.

Consultar indicadores macroeconômicos

Liste os indicadores disponíveis:

indicators = client.macroeconomics.list_indicators()

for indicator in indicators:
    print(indicator.id)

Consulte uma série temporal:

interest_rate = client.macroeconomics.get_indicator_series(
    "INTEREST_RATE",
    country="BRA",
    unit="ANNUAL",
    limit=12,
)

for point in interest_rate:
    print(point.date, point.value)

Antes de solicitar uma série, verifique quais combinações de indicador, país e frequência estão disponíveis.

Consulte a documentação de Macroeconomia.

Consultar fundos listados

Liste os fundos disponíveis:

funds = client.traded_funds.list()

for fund in funds:
    print(fund.symbol, fund.name)

Consulte um fundo específico:

fund = client.traded_funds.get("HGLG11")

print(fund.symbol)
print(fund.dividend_yield_12m)

O recurso pode ser utilizado para trabalhar com fundos imobiliários, ETFs e outros fundos negociados, conforme a cobertura contratada.

Consulte a documentação de fundos listados.

Recursos

• Tipagem completa com type hints
• Suporte a async/await
• Retry automático em caso de erros transitórios
• Compatível com Python 3.9+

Acesse a SDK completa por meio do PyPI: partnr-api.

Boas práticas

• Armazene a API key em uma variável de ambiente ou gerenciador de segredos.
• Não exponha a credencial no frontend.
• Mantenha o pacote atualizado no gerenciador de dependências.
• Defina timeouts adequados para o seu tipo de aplicação.
• Trate erros específicos antes de capturar ApiError.
• Utilize o cliente assíncrono apenas em fluxos realmente assíncronos.
• Não misture PartnrClient e AsyncPartnrClient no mesmo fluxo sem necessidade.
• Consulte a documentação do recurso para validar parâmetros e campos.
• Registre o request_id em logs de erro, sem registrar a API key.