diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7c37599..1421905 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -18,7 +18,7 @@ jobs: lint: timeout-minutes: 10 name: lint - runs-on: ${{ github.repository == 'stainless-sdks/brapi-python' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }} + runs-on: ${{ startsWith(github.repository, 'stainless-sdks/') && 'depot-ubuntu-24.04' || 'ubuntu-latest' }} if: (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata') steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 @@ -44,7 +44,7 @@ jobs: permissions: contents: read id-token: write - runs-on: ${{ github.repository == 'stainless-sdks/brapi-python' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }} + runs-on: ${{ startsWith(github.repository, 'stainless-sdks/') && 'depot-ubuntu-24.04' || 'ubuntu-latest' }} steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 @@ -84,7 +84,7 @@ jobs: test: timeout-minutes: 10 name: test - runs-on: ${{ github.repository == 'stainless-sdks/brapi-python' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }} + runs-on: ${{ startsWith(github.repository, 'stainless-sdks/') && 'depot-ubuntu-24.04' || 'ubuntu-latest' }} if: github.event_name == 'push' || github.event.pull_request.head.repo.fork steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 7deae33..cce9d1c 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "1.6.0" + ".": "1.7.0" } \ No newline at end of file diff --git a/.stats.yml b/.stats.yml index 9cc0f72..47c403e 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,4 +1,4 @@ configured_endpoints: 11 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/alisson/brapi-763c52c3811b3a28985947ecdba690fa83368b40c6dbd27ac740c241d52ea2a8.yml -openapi_spec_hash: 4020950d95877b91e854f0e1917341b1 +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/alisson/brapi-cd497ed299df95a41e4d2132fd412d0fa7c4464e96594478869e8f02baf57d45.yml +openapi_spec_hash: d16e0ab2614dd2530cf3c8c350a4d8ca config_hash: 14da4c1963f3e0764a3e82d626a1d762 diff --git a/CHANGELOG.md b/CHANGELOG.md index e8789f0..8c1216e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,21 @@ # Changelog +## 1.7.0 (2026-09-04) + +Full Changelog: [v1.6.0...v1.7.0](https://github.com/brapi-dev/brapi-python/compare/v1.6.0...v1.7.0) + +### Features + +* **api:** api update ([846d1cc](https://github.com/brapi-dev/brapi-python/commit/846d1cc7b3963e8253ba9aa0f534c7c0c5a15854)) +* **api:** api update ([fd52eeb](https://github.com/brapi-dev/brapi-python/commit/fd52eebdf6030812a49dbd949418146de3b9eee9)) +* **api:** api update ([4ad61a5](https://github.com/brapi-dev/brapi-python/commit/4ad61a5d636f09dc6ec038adcef069a61f6ccc59)) +* **api:** api update ([bc65837](https://github.com/brapi-dev/brapi-python/commit/bc658373787b240ee985a587901aa8d9ad2532a3)) +* **api:** api update ([4d2bc0a](https://github.com/brapi-dev/brapi-python/commit/4d2bc0aab3ce83a2ee54198df763edac1c338470)) +* **api:** api update ([ea7470f](https://github.com/brapi-dev/brapi-python/commit/ea7470f791b60a043840d9ea5c7cc5e64832baa3)) +* **api:** api update ([26541f2](https://github.com/brapi-dev/brapi-python/commit/26541f26d59fb1c56c09d3eb229dc3aaba57edc1)) +* **api:** api update ([bb284b5](https://github.com/brapi-dev/brapi-python/commit/bb284b566f4543033d89fd10055457d7a6d7bd70)) +* **stlc:** configurable CI runner and private-production-repo support in workflow templates ([7e697d6](https://github.com/brapi-dev/brapi-python/commit/7e697d6099b1e28a9babeb18df7f81749d7f23f8)) + ## 1.6.0 (2026-07-10) Full Changelog: [v1.5.0...v1.6.0](https://github.com/brapi-dev/brapi-python/compare/v1.5.0...v1.6.0) diff --git a/api.md b/api.md index fd9c66f..2ea8b8c 100644 --- a/api.md +++ b/api.md @@ -67,7 +67,7 @@ from brapi.types.v2 import InflationRetrieveResponse, InflationListAvailableResp Methods: - client.v2.inflation.retrieve(\*\*params) -> InflationRetrieveResponse -- client.v2.inflation.list_available() -> InflationListAvailableResponse +- client.v2.inflation.list_available(\*\*params) -> InflationListAvailableResponse ## PrimeRate @@ -80,4 +80,4 @@ from brapi.types.v2 import PrimeRateRetrieveResponse, PrimeRateListAvailableResp Methods: - client.v2.prime_rate.retrieve(\*\*params) -> PrimeRateRetrieveResponse -- client.v2.prime_rate.list_available() -> PrimeRateListAvailableResponse +- client.v2.prime_rate.list_available(\*\*params) -> PrimeRateListAvailableResponse diff --git a/pyproject.toml b/pyproject.toml index c835169..6c81123 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "brapi" -version = "1.6.0" +version = "1.7.0" description = "The official Python library for the brapi API" dynamic = ["readme"] license = "Apache-2.0" diff --git a/src/brapi/_version.py b/src/brapi/_version.py index 8ad3a3e..555d3b7 100644 --- a/src/brapi/_version.py +++ b/src/brapi/_version.py @@ -1,4 +1,4 @@ # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. __title__ = "brapi" -__version__ = "1.6.0" # x-release-please-version +__version__ = "1.7.0" # x-release-please-version diff --git a/src/brapi/resources/available.py b/src/brapi/resources/available.py index d9adaf9..90850ba 100644 --- a/src/brapi/resources/available.py +++ b/src/brapi/resources/available.py @@ -57,54 +57,19 @@ def list( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> AvailableListResponse: """ - Retorna a lista completa de **ações e índices** disponíveis para consulta na API - brapi. + Lista todos os ativos que a API aceita: ações, FIIs, BDRs e ETFs da B3, mais os + índices com cotação disponível. - ### Funcionalidades - - - **Ações brasileiras:** Todas as ações, FIIs, BDRs e ETFs negociados na bolsa - brasileira - - **Índices:** Índices do mercado brasileiro com cotação disponível na API - - **Filtro por Nome:** Use `search` para filtrar por código ou nome do ativo - - ### Características - - - **Sem Autenticação:** Este endpoint é **público** e não requer token - - **Cache:** Dados cacheados por 15 minutos - - **Atualização automática:** Conforme novos ativos são listados na bolsa - brasileira - - ### Exemplos de Uso + Filtre por código ou nome com `search`. ```bash - # Listar todos os ativos - curl "https://brapi.dev/api/available" - - # Buscar por código de ticker curl "https://brapi.dev/api/available?search=PETR" - - # Buscar por nome da empresa - curl "https://brapi.dev/api/available?search=banco" ``` - ### Índices Disponíveis - - - `^BVSP` — Ibovespa (Índice Bovespa) - - `IFIX.SA` — Índice de Fundos Imobiliários - - ### Campos da Resposta - - - `stocks` — Array com códigos das ações (ex: ["PETR4", "VALE3", "ITUB4", ...]) - - `indexes` — Array com códigos dos índices (ex: ["^BVSP", "IFIX.SA"]) - - ### Como Usar - - Use os códigos retornados como parâmetro no endpoint `/api/quote/{tickers}` para - obter cotações detalhadas. - - **Fonte:** Bolsa de Valores do Brasil + Endpoint público, sem token. A resposta fica em cache por 15 minutos e é + atualizada conforme novos ativos entram na bolsa. - **Plano Mínimo:** Gratuito **Autenticação:** Não necessária (Público) + Para busca com filtros por setor e tipo, `/api/v2/tickers` é mais completo. Args: search: Filtrar ações e índices por nome ou código @@ -166,54 +131,19 @@ async def list( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> AvailableListResponse: """ - Retorna a lista completa de **ações e índices** disponíveis para consulta na API - brapi. + Lista todos os ativos que a API aceita: ações, FIIs, BDRs e ETFs da B3, mais os + índices com cotação disponível. - ### Funcionalidades - - - **Ações brasileiras:** Todas as ações, FIIs, BDRs e ETFs negociados na bolsa - brasileira - - **Índices:** Índices do mercado brasileiro com cotação disponível na API - - **Filtro por Nome:** Use `search` para filtrar por código ou nome do ativo - - ### Características - - - **Sem Autenticação:** Este endpoint é **público** e não requer token - - **Cache:** Dados cacheados por 15 minutos - - **Atualização automática:** Conforme novos ativos são listados na bolsa - brasileira - - ### Exemplos de Uso + Filtre por código ou nome com `search`. ```bash - # Listar todos os ativos - curl "https://brapi.dev/api/available" - - # Buscar por código de ticker curl "https://brapi.dev/api/available?search=PETR" - - # Buscar por nome da empresa - curl "https://brapi.dev/api/available?search=banco" ``` - ### Índices Disponíveis - - - `^BVSP` — Ibovespa (Índice Bovespa) - - `IFIX.SA` — Índice de Fundos Imobiliários - - ### Campos da Resposta - - - `stocks` — Array com códigos das ações (ex: ["PETR4", "VALE3", "ITUB4", ...]) - - `indexes` — Array com códigos dos índices (ex: ["^BVSP", "IFIX.SA"]) - - ### Como Usar - - Use os códigos retornados como parâmetro no endpoint `/api/quote/{tickers}` para - obter cotações detalhadas. - - **Fonte:** Bolsa de Valores do Brasil + Endpoint público, sem token. A resposta fica em cache por 15 minutos e é + atualizada conforme novos ativos entram na bolsa. - **Plano Mínimo:** Gratuito **Autenticação:** Não necessária (Público) + Para busca com filtros por setor e tipo, `/api/v2/tickers` é mais completo. Args: search: Filtrar ações e índices por nome ou código diff --git a/src/brapi/resources/quote.py b/src/brapi/resources/quote.py index b29f848..27243d6 100644 --- a/src/brapi/resources/quote.py +++ b/src/brapi/resources/quote.py @@ -56,6 +56,7 @@ def retrieve( token: str | Omit = omit, dividends: Literal["true", "false"] | Omit = omit, end_date: str | Omit = omit, + include_raw: Literal["true", "false"] | Omit = omit, interval: Literal["1m", "2m", "5m", "15m", "30m", "60m", "90m", "1h", "1d", "5d", "1wk", "1mo", "3mo"] | Omit = omit, modules: str | Omit = omit, @@ -70,136 +71,64 @@ def retrieve( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> QuoteRetrieveResponse: """ - **O ENDPOINT MAIS IMPORTANTE DA API.** Obtém dados detalhados e abrangentes de - um ou múltiplos ativos (ações, FIIs, BDRs) em uma única requisição. Combine - cotações em tempo real, dados históricos, fundamentos e dividendos conforme - necessário. + Devolve cotação, histórico, dividendos e fundamentos de um ou mais ativos em uma + única resposta. É o endpoint original da brapi e continua funcionando sem data + de remoção. - ### Funcionalidades: + Para integrações novas, prefira `/api/v2/stocks/*`. Lá cada chamada traz um tipo + de dado e a resposta chega menor. Veja o guia em + [brapi.dev/docs/acoes/migracao-v2](https://brapi.dev/docs/acoes/migracao-v2). - - **Cotação em Tempo Real:** Preço atual, variação absoluta e percentual, - volume, máxima/mínima do dia, range de 52 semanas. - - **Dados Históricos:** Preços OHLCV (Open, High, Low, Close, Volume) com - intervalos flexíveis (1d, 5d, 1wk, 1mo, 3mo) e períodos (1d até max). - - **Fundamentos:** Balanço Patrimonial, DRE, Fluxo de Caixa, DVA, - Indicadores-chave (P/L, P/VP, ROE, etc) via parâmetro `modules`. - - **Dividendos:** Histórico completo de proventos em dinheiro (dividendos, JCP) - e bonificações. + ### O que a resposta traz - ### Autenticação: + Sempre: `symbol`, `shortName`, `currency`, `regularMarketPrice`, + `regularMarketChange`, `regularMarketChangePercent`, `regularMarketVolume`, + `regularMarketDayHigh`, `regularMarketDayLow`, `fiftyTwoWeekHigh`, + `fiftyTwoWeekLow` e `marketCap`. - Requer token Bearer no header ou como query param. Tickers de teste **PETR4** e - **VALE3** funcionam sem autenticação. + Com `range` e `interval`: `historicalDataPrice` com a série OHLCV. Com + `includeRaw=true` e intervalo diário: os campos `rawOpen`, `rawHigh`, `rawLow` e + `rawClose` quando existirem no banco. Intervalos intradiários não retornam + campos `raw*`. Com `dividends=true`: `dividendsData` com dividendos, JCP e + bonificações. Com `modules`: um objeto por módulo pedido. - ```bash - # Via header (recomendado) - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/PETR4" + ### Parâmetros de histórico - # Via query param - curl "https://brapi.dev/api/quote/PETR4?token=SEU_TOKEN" - ``` + `interval` aceita `1d`, `5d`, `1wk`, `1mo` e `3mo`. `range` aceita `1d`, `5d`, + `1mo`, `3mo`, `6mo`, `1y`, `2y`, `5y`, `10y`, `ytd` e `max`. O quanto de + histórico você enxerga depende do plano. - ### Exemplos de Requisição: + ### Módulos - ```bash - # Simples: apenas cotação atual - curl "https://brapi.dev/api/quote/PETR4?token=SEU_TOKEN" + `modules` aceita uma lista separada por vírgula: - # Múltiplos tickers em uma requisição - curl "https://brapi.dev/api/quote/PETR4,VALE3,ITUB4?token=SEU_TOKEN" + - `summaryProfile` - cadastro da empresa: CNPJ, setor, descrição, site, + funcionários + - `defaultKeyStatistics` - múltiplos nos últimos 12 meses: P/L, P/VP, ROE, + dividend yield + - `financialData` - receita, EBITDA, margens e dívida nos últimos 12 meses + - `balanceSheetHistory` - balanço patrimonial anual + - `incomeStatementHistory` - DRE anual + - `cashflowHistory` - fluxo de caixa anual + - `valueAddedHistory` - DVA anual - # Com dados históricos (últimos 12 meses, diário) - curl "https://brapi.dev/api/quote/PETR4?range=1y&interval=1d&token=SEU_TOKEN" + Cada módulo de histórico tem a versão trimestral com o sufixo `Quarterly`. Os + módulos `defaultKeyStatistics` e `financialData` também aceitam os sufixos + `History` e `HistoryQuarterly`. - # Com módulos de fundamentos (balanço e DRE) - curl "https://brapi.dev/api/quote/PETR4?modules=balanceSheetHistory,incomeStatementHistory&token=SEU_TOKEN" - - # Completo: histórico + dividendos + estatísticas-chave - curl "https://brapi.dev/api/quote/PETR4?range=6mo&interval=1d÷nds=true&modules=balanceSheetHistory,defaultKeyStatistics&token=SEU_TOKEN" + ```bash + curl -H "Authorization: Bearer SEU_TOKEN" \\ + "https://brapi.dev/api/quote/PETR4?range=6mo&interval=1d÷nds=true&modules=defaultKeyStatistics" ``` - ### Módulos Disponíveis: - - - `summaryProfile` — Perfil da empresa (CNPJ, setor, descrição, website, - funcionários) - - `balanceSheetHistory` — Balanço Patrimonial anual - - `balanceSheetHistoryQuarterly` — Balanço Patrimonial trimestral - - `incomeStatementHistory` — DRE anual (Demonstração de Resultado do Exercício) - - `incomeStatementHistoryQuarterly` — DRE trimestral - - `financialData` — Indicadores financeiros atuais (TTM - Trailing Twelve - Months) - - `financialDataHistory` — Histórico anual de indicadores financeiros - - `financialDataHistoryQuarterly` — Histórico trimestral de indicadores - financeiros - - `defaultKeyStatistics` — Estatísticas-chave (P/L, P/VP, ROE, Dividend Yield, - etc) - - `defaultKeyStatisticsHistory` — Histórico anual de estatísticas-chave - - `defaultKeyStatisticsHistoryQuarterly` — Histórico trimestral de - estatísticas-chave - - `cashflowHistory` — Fluxo de Caixa anual - - `cashflowHistoryQuarterly` — Fluxo de Caixa trimestral - - `valueAddedHistory` — DVA anual (Demonstração de Valor Adicionado) - - `valueAddedHistoryQuarterly` — DVA trimestral - - ### Intervalos Válidos (histórico): - - - `1d` — Diário - - `5d` — 5 dias - - `1wk` — Semanal - - `1mo` — Mensal - - `3mo` — Trimestral - - ### Períodos Válidos (range): - - - `1d` — Último dia - - `5d` — Últimos 5 dias - - `1mo` — Último mês - - `3mo` — Últimos 3 meses - - `6mo` — Últimos 6 meses - - `1y` — Último ano - - `2y` — Últimos 2 anos - - `5y` — Últimos 5 anos - - `10y` — Últimos 10 anos - - `ytd` — Ano até hoje - - `max` — Máximo disponível - - ### Campos Principais da Resposta: - - - `symbol` — Ticker do ativo (ex: PETR4) - - `shortName` — Nome curto da empresa - - `currency` — Moeda (BRL) - - `regularMarketPrice` — Preço atual em BRL - - `regularMarketChange` — Variação absoluta - - `regularMarketChangePercent` — Variação percentual (%) - - `regularMarketVolume` — Volume de negociação do dia - - `regularMarketDayHigh` — Máxima do dia - - `regularMarketDayLow` — Mínima do dia - - `fiftyTwoWeekHigh` — Máxima de 52 semanas - - `fiftyTwoWeekLow` — Mínima de 52 semanas - - `marketCap` — Capitalização de mercado - - `historicalDataPrice` — Array de dados OHLCV (quando `range`/`interval` - fornecidos) - - `dividendsData` — Histórico de dividendos (quando `dividends=true`) - - ### Tickers Populares (Teste): - - - `PETR4` — Petrobras (Energia) - - `VALE3` — Vale (Mineração) - - `ITUB4` — Itaú Unibanco (Financeiro) - - `BBDC4` — Bradesco (Financeiro) - - `ABEV3` — Ambev (Consumo) - - `WEGE3` — WEG (Indústria) - - `RENT3` — Localiza (Transporte) - - `BBAS3` — Banco do Brasil (Financeiro) - - `MGLU3` — Magazine Luiza (Varejo) - - ### Fonte dos Dados: - - CVM (Comissão de Valores Mobiliários) - - **Plano Mínimo:** Gratuito (limitado a 1 ticker/requisição e módulos básicos) - **Autenticação:** Necessária para produção (tickers de teste PETR4 e VALE3 - funcionam sem token) + ### Autenticação + + PETR4, MGLU3, VALE3 e ITUB4 respondem sem token, com todos os recursos. Se você + misturar um desses com outro ticker na mesma requisição, a chamada inteira passa + a exigir token. Envie o token no header `Authorization` sempre que a sua + ferramenta permitir. + + Os fundamentos vêm dos documentos que as companhias entregam à CVM. Args: tickers: Ticker(s) de ativos separados por vírgula (ex: PETR4 ou PETR4,VALE3,ITUB4) @@ -210,6 +139,9 @@ def retrieve( end_date: Data final para dados históricos (formato YYYY-MM-DD) + include_raw: Incluir preços OHLC originais armazenados no banco da brapi para intervalos + diários. Use includeRaw=true. Disponível no plano Pro. + interval: Intervalo/granularidade dos dados históricos modules: Módulos de dados adicionais separados por vírgula @@ -240,6 +172,7 @@ def retrieve( "token": token, "dividends": dividends, "end_date": end_date, + "include_raw": include_raw, "interval": interval, "modules": modules, "range": range, @@ -261,6 +194,7 @@ def list( sector: str | Omit = omit, sort_by: Literal["name", "close", "change", "change_abs", "volume", "market_cap_basic"] | Omit = omit, sort_order: Literal["asc", "desc"] | Omit = omit, + subsector: str | Omit = omit, sub_type: Literal["stock", "unit", "fii", "etf", "fi-infra", "fi-agro", "fip", "fidc", "bdr"] | Omit = omit, type: Literal["stock", "fund", "bdr"] | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. @@ -270,60 +204,29 @@ def list( extra_body: Body | None = None, timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> QuoteListResponse: - """ - Retorna uma lista paginada de todos os ativos disponíveis na API (Ações, FIIs, - BDRs, ETFs, Índices). Use este endpoint para construir screeners, exploradores - de ações ou para descobrir novos ativos. - - ### Funcionalidades: + """Lista paginada de ativos da B3 com a cotação de cada um. - - **Busca por Nome ou Ticker:** Encontre ativos digitando "Petrobras", "PETR4" - ou qualquer termo. - - **Filtros por Tipo:** Ações (stock), Fundos Imobiliários (fund), BDRs (bdr). - - **Filtros por Subtipo:** Units, FIIs, ETFs, FI-Infra, FI-Agro, FIPs, FIDCs e - BDRs via `subType`. - - **Filtros por Setor:** Energia, Financeiro, Tecnologia, Saúde, etc. - - **Ordenação Flexível:** Ordene por volume, preço, market cap ou nome. - - **Paginação:** Controle o número de resultados com `limit` e `page`. + Serve para montar + screener, tabela de mercado ou autocomplete de busca. - ### Autenticação: + Busque por nome ou ticker com `search`, aceitando tanto "Petrobras" quanto + "PETR4". Filtre por `type` (`stock`, `fund`, `bdr`), por `subType` (units, FIIs, + ETFs, FI-Infra, FI-Agro, FIPs, FIDCs, BDRs) e por `sector`. - Requer token Bearer. Obtenha seu token em - [brapi.dev/dashboard](https://brapi.dev/dashboard). + Ordene com `sortBy` usando `volume`, `close`, `market_cap_basic` ou `name`, mais + `sortOrder`. Pagine com `page` e `limit`. O padrão devolve os primeiros 100 + ativos. - ### Exemplos de Requisição: + A resposta também traz `availableSectors` e `availableStockTypes`, então você + monta os filtros da sua interface sem manter uma lista fixa no código. ```bash - # Listar todos os ativos (primeiros 100) - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/list" - - # Buscar por nome ou ticker - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/list?search=petrobras" - - # Filtrar por tipo e ordenar por volume - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/list?type=stock&sortBy=volume&sortOrder=desc&limit=10" - - # Filtrar por subtipo - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/list?subType=fi-agro&limit=10" - - # Listar apenas FIIs de um setor específico - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/list?type=fund§or=Logística&limit=20" + curl -H "Authorization: Bearer SEU_TOKEN" \\ + "https://brapi.dev/api/quote/list?type=stock&sortBy=volume&sortOrder=desc&limit=10" ``` - ### Parâmetros de Ordenação: - - - `volume` — Volume de negociação do dia - - `close` — Preço de fechamento - - `market_cap_basic` — Capitalização de mercado - - `name` — Nome da empresa (alfabético) - - ### Tipos de Ativo: - - - `stock` — Ações (Ações ordinárias e preferenciais) - - `fund` — Fundos Imobiliários (FIIs) e ETFs - - `bdr` — BDRs (Brazilian Depositary Receipts) - - **Plano Mínimo:** Gratuito **Autenticação:** Necessária (Bearer Token) + Exige token, disponível em qualquer plano. Para buscar e validar símbolos sem + carregar cotação, `/api/v2/tickers` é mais leve. Args: token: Token de autenticação (alternativa ao header Authorization) @@ -340,6 +243,8 @@ def list( sort_order: Ordem de classificação + subsector: Filtrar pelo subsetor B3 + sub_type: Filtrar por classificação aditiva: stock, unit, fii, etf, fi-infra, fi-agro, fip, fidc ou bdr @@ -369,6 +274,7 @@ def list( "sector": sector, "sort_by": sort_by, "sort_order": sort_order, + "subsector": subsector, "sub_type": sub_type, "type": type, }, @@ -411,6 +317,7 @@ async def retrieve( token: str | Omit = omit, dividends: Literal["true", "false"] | Omit = omit, end_date: str | Omit = omit, + include_raw: Literal["true", "false"] | Omit = omit, interval: Literal["1m", "2m", "5m", "15m", "30m", "60m", "90m", "1h", "1d", "5d", "1wk", "1mo", "3mo"] | Omit = omit, modules: str | Omit = omit, @@ -425,136 +332,64 @@ async def retrieve( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> QuoteRetrieveResponse: """ - **O ENDPOINT MAIS IMPORTANTE DA API.** Obtém dados detalhados e abrangentes de - um ou múltiplos ativos (ações, FIIs, BDRs) em uma única requisição. Combine - cotações em tempo real, dados históricos, fundamentos e dividendos conforme - necessário. + Devolve cotação, histórico, dividendos e fundamentos de um ou mais ativos em uma + única resposta. É o endpoint original da brapi e continua funcionando sem data + de remoção. - ### Funcionalidades: + Para integrações novas, prefira `/api/v2/stocks/*`. Lá cada chamada traz um tipo + de dado e a resposta chega menor. Veja o guia em + [brapi.dev/docs/acoes/migracao-v2](https://brapi.dev/docs/acoes/migracao-v2). - - **Cotação em Tempo Real:** Preço atual, variação absoluta e percentual, - volume, máxima/mínima do dia, range de 52 semanas. - - **Dados Históricos:** Preços OHLCV (Open, High, Low, Close, Volume) com - intervalos flexíveis (1d, 5d, 1wk, 1mo, 3mo) e períodos (1d até max). - - **Fundamentos:** Balanço Patrimonial, DRE, Fluxo de Caixa, DVA, - Indicadores-chave (P/L, P/VP, ROE, etc) via parâmetro `modules`. - - **Dividendos:** Histórico completo de proventos em dinheiro (dividendos, JCP) - e bonificações. + ### O que a resposta traz - ### Autenticação: + Sempre: `symbol`, `shortName`, `currency`, `regularMarketPrice`, + `regularMarketChange`, `regularMarketChangePercent`, `regularMarketVolume`, + `regularMarketDayHigh`, `regularMarketDayLow`, `fiftyTwoWeekHigh`, + `fiftyTwoWeekLow` e `marketCap`. - Requer token Bearer no header ou como query param. Tickers de teste **PETR4** e - **VALE3** funcionam sem autenticação. + Com `range` e `interval`: `historicalDataPrice` com a série OHLCV. Com + `includeRaw=true` e intervalo diário: os campos `rawOpen`, `rawHigh`, `rawLow` e + `rawClose` quando existirem no banco. Intervalos intradiários não retornam + campos `raw*`. Com `dividends=true`: `dividendsData` com dividendos, JCP e + bonificações. Com `modules`: um objeto por módulo pedido. - ```bash - # Via header (recomendado) - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/PETR4" + ### Parâmetros de histórico - # Via query param - curl "https://brapi.dev/api/quote/PETR4?token=SEU_TOKEN" - ``` + `interval` aceita `1d`, `5d`, `1wk`, `1mo` e `3mo`. `range` aceita `1d`, `5d`, + `1mo`, `3mo`, `6mo`, `1y`, `2y`, `5y`, `10y`, `ytd` e `max`. O quanto de + histórico você enxerga depende do plano. - ### Exemplos de Requisição: + ### Módulos - ```bash - # Simples: apenas cotação atual - curl "https://brapi.dev/api/quote/PETR4?token=SEU_TOKEN" + `modules` aceita uma lista separada por vírgula: - # Múltiplos tickers em uma requisição - curl "https://brapi.dev/api/quote/PETR4,VALE3,ITUB4?token=SEU_TOKEN" + - `summaryProfile` - cadastro da empresa: CNPJ, setor, descrição, site, + funcionários + - `defaultKeyStatistics` - múltiplos nos últimos 12 meses: P/L, P/VP, ROE, + dividend yield + - `financialData` - receita, EBITDA, margens e dívida nos últimos 12 meses + - `balanceSheetHistory` - balanço patrimonial anual + - `incomeStatementHistory` - DRE anual + - `cashflowHistory` - fluxo de caixa anual + - `valueAddedHistory` - DVA anual - # Com dados históricos (últimos 12 meses, diário) - curl "https://brapi.dev/api/quote/PETR4?range=1y&interval=1d&token=SEU_TOKEN" + Cada módulo de histórico tem a versão trimestral com o sufixo `Quarterly`. Os + módulos `defaultKeyStatistics` e `financialData` também aceitam os sufixos + `History` e `HistoryQuarterly`. - # Com módulos de fundamentos (balanço e DRE) - curl "https://brapi.dev/api/quote/PETR4?modules=balanceSheetHistory,incomeStatementHistory&token=SEU_TOKEN" - - # Completo: histórico + dividendos + estatísticas-chave - curl "https://brapi.dev/api/quote/PETR4?range=6mo&interval=1d÷nds=true&modules=balanceSheetHistory,defaultKeyStatistics&token=SEU_TOKEN" + ```bash + curl -H "Authorization: Bearer SEU_TOKEN" \\ + "https://brapi.dev/api/quote/PETR4?range=6mo&interval=1d÷nds=true&modules=defaultKeyStatistics" ``` - ### Módulos Disponíveis: - - - `summaryProfile` — Perfil da empresa (CNPJ, setor, descrição, website, - funcionários) - - `balanceSheetHistory` — Balanço Patrimonial anual - - `balanceSheetHistoryQuarterly` — Balanço Patrimonial trimestral - - `incomeStatementHistory` — DRE anual (Demonstração de Resultado do Exercício) - - `incomeStatementHistoryQuarterly` — DRE trimestral - - `financialData` — Indicadores financeiros atuais (TTM - Trailing Twelve - Months) - - `financialDataHistory` — Histórico anual de indicadores financeiros - - `financialDataHistoryQuarterly` — Histórico trimestral de indicadores - financeiros - - `defaultKeyStatistics` — Estatísticas-chave (P/L, P/VP, ROE, Dividend Yield, - etc) - - `defaultKeyStatisticsHistory` — Histórico anual de estatísticas-chave - - `defaultKeyStatisticsHistoryQuarterly` — Histórico trimestral de - estatísticas-chave - - `cashflowHistory` — Fluxo de Caixa anual - - `cashflowHistoryQuarterly` — Fluxo de Caixa trimestral - - `valueAddedHistory` — DVA anual (Demonstração de Valor Adicionado) - - `valueAddedHistoryQuarterly` — DVA trimestral - - ### Intervalos Válidos (histórico): - - - `1d` — Diário - - `5d` — 5 dias - - `1wk` — Semanal - - `1mo` — Mensal - - `3mo` — Trimestral - - ### Períodos Válidos (range): - - - `1d` — Último dia - - `5d` — Últimos 5 dias - - `1mo` — Último mês - - `3mo` — Últimos 3 meses - - `6mo` — Últimos 6 meses - - `1y` — Último ano - - `2y` — Últimos 2 anos - - `5y` — Últimos 5 anos - - `10y` — Últimos 10 anos - - `ytd` — Ano até hoje - - `max` — Máximo disponível - - ### Campos Principais da Resposta: - - - `symbol` — Ticker do ativo (ex: PETR4) - - `shortName` — Nome curto da empresa - - `currency` — Moeda (BRL) - - `regularMarketPrice` — Preço atual em BRL - - `regularMarketChange` — Variação absoluta - - `regularMarketChangePercent` — Variação percentual (%) - - `regularMarketVolume` — Volume de negociação do dia - - `regularMarketDayHigh` — Máxima do dia - - `regularMarketDayLow` — Mínima do dia - - `fiftyTwoWeekHigh` — Máxima de 52 semanas - - `fiftyTwoWeekLow` — Mínima de 52 semanas - - `marketCap` — Capitalização de mercado - - `historicalDataPrice` — Array de dados OHLCV (quando `range`/`interval` - fornecidos) - - `dividendsData` — Histórico de dividendos (quando `dividends=true`) - - ### Tickers Populares (Teste): - - - `PETR4` — Petrobras (Energia) - - `VALE3` — Vale (Mineração) - - `ITUB4` — Itaú Unibanco (Financeiro) - - `BBDC4` — Bradesco (Financeiro) - - `ABEV3` — Ambev (Consumo) - - `WEGE3` — WEG (Indústria) - - `RENT3` — Localiza (Transporte) - - `BBAS3` — Banco do Brasil (Financeiro) - - `MGLU3` — Magazine Luiza (Varejo) - - ### Fonte dos Dados: - - CVM (Comissão de Valores Mobiliários) - - **Plano Mínimo:** Gratuito (limitado a 1 ticker/requisição e módulos básicos) - **Autenticação:** Necessária para produção (tickers de teste PETR4 e VALE3 - funcionam sem token) + ### Autenticação + + PETR4, MGLU3, VALE3 e ITUB4 respondem sem token, com todos os recursos. Se você + misturar um desses com outro ticker na mesma requisição, a chamada inteira passa + a exigir token. Envie o token no header `Authorization` sempre que a sua + ferramenta permitir. + + Os fundamentos vêm dos documentos que as companhias entregam à CVM. Args: tickers: Ticker(s) de ativos separados por vírgula (ex: PETR4 ou PETR4,VALE3,ITUB4) @@ -565,6 +400,9 @@ async def retrieve( end_date: Data final para dados históricos (formato YYYY-MM-DD) + include_raw: Incluir preços OHLC originais armazenados no banco da brapi para intervalos + diários. Use includeRaw=true. Disponível no plano Pro. + interval: Intervalo/granularidade dos dados históricos modules: Módulos de dados adicionais separados por vírgula @@ -595,6 +433,7 @@ async def retrieve( "token": token, "dividends": dividends, "end_date": end_date, + "include_raw": include_raw, "interval": interval, "modules": modules, "range": range, @@ -616,6 +455,7 @@ async def list( sector: str | Omit = omit, sort_by: Literal["name", "close", "change", "change_abs", "volume", "market_cap_basic"] | Omit = omit, sort_order: Literal["asc", "desc"] | Omit = omit, + subsector: str | Omit = omit, sub_type: Literal["stock", "unit", "fii", "etf", "fi-infra", "fi-agro", "fip", "fidc", "bdr"] | Omit = omit, type: Literal["stock", "fund", "bdr"] | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. @@ -625,60 +465,29 @@ async def list( extra_body: Body | None = None, timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> QuoteListResponse: - """ - Retorna uma lista paginada de todos os ativos disponíveis na API (Ações, FIIs, - BDRs, ETFs, Índices). Use este endpoint para construir screeners, exploradores - de ações ou para descobrir novos ativos. - - ### Funcionalidades: + """Lista paginada de ativos da B3 com a cotação de cada um. - - **Busca por Nome ou Ticker:** Encontre ativos digitando "Petrobras", "PETR4" - ou qualquer termo. - - **Filtros por Tipo:** Ações (stock), Fundos Imobiliários (fund), BDRs (bdr). - - **Filtros por Subtipo:** Units, FIIs, ETFs, FI-Infra, FI-Agro, FIPs, FIDCs e - BDRs via `subType`. - - **Filtros por Setor:** Energia, Financeiro, Tecnologia, Saúde, etc. - - **Ordenação Flexível:** Ordene por volume, preço, market cap ou nome. - - **Paginação:** Controle o número de resultados com `limit` e `page`. + Serve para montar + screener, tabela de mercado ou autocomplete de busca. - ### Autenticação: + Busque por nome ou ticker com `search`, aceitando tanto "Petrobras" quanto + "PETR4". Filtre por `type` (`stock`, `fund`, `bdr`), por `subType` (units, FIIs, + ETFs, FI-Infra, FI-Agro, FIPs, FIDCs, BDRs) e por `sector`. - Requer token Bearer. Obtenha seu token em - [brapi.dev/dashboard](https://brapi.dev/dashboard). + Ordene com `sortBy` usando `volume`, `close`, `market_cap_basic` ou `name`, mais + `sortOrder`. Pagine com `page` e `limit`. O padrão devolve os primeiros 100 + ativos. - ### Exemplos de Requisição: + A resposta também traz `availableSectors` e `availableStockTypes`, então você + monta os filtros da sua interface sem manter uma lista fixa no código. ```bash - # Listar todos os ativos (primeiros 100) - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/list" - - # Buscar por nome ou ticker - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/list?search=petrobras" - - # Filtrar por tipo e ordenar por volume - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/list?type=stock&sortBy=volume&sortOrder=desc&limit=10" - - # Filtrar por subtipo - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/list?subType=fi-agro&limit=10" - - # Listar apenas FIIs de um setor específico - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/list?type=fund§or=Logística&limit=20" + curl -H "Authorization: Bearer SEU_TOKEN" \\ + "https://brapi.dev/api/quote/list?type=stock&sortBy=volume&sortOrder=desc&limit=10" ``` - ### Parâmetros de Ordenação: - - - `volume` — Volume de negociação do dia - - `close` — Preço de fechamento - - `market_cap_basic` — Capitalização de mercado - - `name` — Nome da empresa (alfabético) - - ### Tipos de Ativo: - - - `stock` — Ações (Ações ordinárias e preferenciais) - - `fund` — Fundos Imobiliários (FIIs) e ETFs - - `bdr` — BDRs (Brazilian Depositary Receipts) - - **Plano Mínimo:** Gratuito **Autenticação:** Necessária (Bearer Token) + Exige token, disponível em qualquer plano. Para buscar e validar símbolos sem + carregar cotação, `/api/v2/tickers` é mais leve. Args: token: Token de autenticação (alternativa ao header Authorization) @@ -695,6 +504,8 @@ async def list( sort_order: Ordem de classificação + subsector: Filtrar pelo subsetor B3 + sub_type: Filtrar por classificação aditiva: stock, unit, fii, etf, fi-infra, fi-agro, fip, fidc ou bdr @@ -724,6 +535,7 @@ async def list( "sector": sector, "sort_by": sort_by, "sort_order": sort_order, + "subsector": subsector, "sub_type": sub_type, "type": type, }, diff --git a/src/brapi/resources/v2/crypto.py b/src/brapi/resources/v2/crypto.py index cec2f9a..9e3cb84 100644 --- a/src/brapi/resources/v2/crypto.py +++ b/src/brapi/resources/v2/crypto.py @@ -61,45 +61,21 @@ def retrieve( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> CryptoRetrieveResponse: """ - Retorna cotações atualizadas de uma ou mais criptomoedas, com conversão para - diferentes moedas fiduciárias. + Cotação de uma ou mais criptomoedas, convertida para a moeda que você escolher. - ### Funcionalidades: + Cada moeda traz preço, variação de 24 horas, volume e market cap. O padrão é + `currency=BRL`, e você pode pedir `USD`, `EUR` e outras. - - **Cotação Atual:** Preço, variação 24h, volume, market cap - - **Múltiplas Moedas:** Consulte várias criptos em uma requisição (separadas por - vírgula) - - **Conversão de Moeda:** BRL (padrão), USD, EUR e outras - - **Dados Históricos:** OHLCV via parâmetros `range` e `interval` - - ### Autenticação: - - Bearer token ou query param `token`. Obtenha em brapi.dev/dashboard. - - ### Exemplos de Requisição: + Peça várias de uma vez em `coin=BTC,ETH,SOL`. Para série histórica, passe + `range` e `interval`. ```bash - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/crypto?coin=BTC¤cy=BRL" - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/crypto?coin=BTC,ETH,SOL¤cy=USD" - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/crypto?coin=BTC¤cy=BRL&range=1mo&interval=1d" + curl -H "Authorization: Bearer SEU_TOKEN" \\ + "https://brapi.dev/api/v2/crypto?coin=BTC,ETH¤cy=BRL" ``` - ### Moedas de Conversão: - - BRL (Real), USD (Dólar), EUR (Euro), GBP (Libra) e outras - - ### Campos da Resposta: - - - `coin` — Símbolo da criptomoeda - - `coinName` — Nome completo - - `currency` — Moeda de cotação - - `regularMarketPrice` — Preço atual - - `regularMarketChange` — Variação em valor absoluto - - `regularMarketChangePercent` — Variação percentual (%) - - `regularMarketDayHigh` / `regularMarketDayLow` — Máxima/Mínima do dia - - `regularMarketVolume` — Volume negociado - - **Plano Mínimo:** Startup **Autenticação:** Necessária + Cripto negocia 24 horas por dia. A variação de 24 horas é uma janela móvel, não + o fechamento de um pregão. Args: coin: Sigla(s) das criptomoedas separadas por vírgula @@ -150,36 +126,16 @@ def list_available( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> CryptoListAvailableResponse: """ - Retorna a lista de criptomoedas disponíveis para consulta no endpoint - `/api/v2/crypto`. - - ### Criptomoedas Populares: - - - **BTC** — Bitcoin - - **ETH** — Ethereum - - **BNB** — Binance Coin - - **SOL** — Solana - - **ADA** — Cardano - - **XRP** — Ripple - - **DOGE** — Dogecoin - - **DOT** — Polkadot - - **MATIC** — Polygon - - **LTC** — Litecoin - - E centenas de outras... + As criptomoedas que `/api/v2/crypto` aceita, com centenas de símbolos. - ### Uso: - - Use os símbolos retornados como valor do parâmetro `coin` no endpoint principal. - - ### Exemplos de Requisição: + Use `search` para filtrar. O valor do campo `coin` de cada item é o que você + passa no parâmetro `coin` do endpoint principal. ```bash - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/crypto/available" - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/crypto/available?search=BTC" + curl -H "Authorization: Bearer SEU_TOKEN" \\ + "https://brapi.dev/api/v2/crypto/available?search=BTC" ``` - **Plano Mínimo:** Startup **Autenticação:** Necessária - Args: search: Filtrar criptomoedas por símbolo @@ -243,45 +199,21 @@ async def retrieve( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> CryptoRetrieveResponse: """ - Retorna cotações atualizadas de uma ou mais criptomoedas, com conversão para - diferentes moedas fiduciárias. + Cotação de uma ou mais criptomoedas, convertida para a moeda que você escolher. - ### Funcionalidades: + Cada moeda traz preço, variação de 24 horas, volume e market cap. O padrão é + `currency=BRL`, e você pode pedir `USD`, `EUR` e outras. - - **Cotação Atual:** Preço, variação 24h, volume, market cap - - **Múltiplas Moedas:** Consulte várias criptos em uma requisição (separadas por - vírgula) - - **Conversão de Moeda:** BRL (padrão), USD, EUR e outras - - **Dados Históricos:** OHLCV via parâmetros `range` e `interval` - - ### Autenticação: - - Bearer token ou query param `token`. Obtenha em brapi.dev/dashboard. - - ### Exemplos de Requisição: + Peça várias de uma vez em `coin=BTC,ETH,SOL`. Para série histórica, passe + `range` e `interval`. ```bash - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/crypto?coin=BTC¤cy=BRL" - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/crypto?coin=BTC,ETH,SOL¤cy=USD" - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/crypto?coin=BTC¤cy=BRL&range=1mo&interval=1d" + curl -H "Authorization: Bearer SEU_TOKEN" \\ + "https://brapi.dev/api/v2/crypto?coin=BTC,ETH¤cy=BRL" ``` - ### Moedas de Conversão: - - BRL (Real), USD (Dólar), EUR (Euro), GBP (Libra) e outras - - ### Campos da Resposta: - - - `coin` — Símbolo da criptomoeda - - `coinName` — Nome completo - - `currency` — Moeda de cotação - - `regularMarketPrice` — Preço atual - - `regularMarketChange` — Variação em valor absoluto - - `regularMarketChangePercent` — Variação percentual (%) - - `regularMarketDayHigh` / `regularMarketDayLow` — Máxima/Mínima do dia - - `regularMarketVolume` — Volume negociado - - **Plano Mínimo:** Startup **Autenticação:** Necessária + Cripto negocia 24 horas por dia. A variação de 24 horas é uma janela móvel, não + o fechamento de um pregão. Args: coin: Sigla(s) das criptomoedas separadas por vírgula @@ -332,36 +264,16 @@ async def list_available( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> CryptoListAvailableResponse: """ - Retorna a lista de criptomoedas disponíveis para consulta no endpoint - `/api/v2/crypto`. - - ### Criptomoedas Populares: - - - **BTC** — Bitcoin - - **ETH** — Ethereum - - **BNB** — Binance Coin - - **SOL** — Solana - - **ADA** — Cardano - - **XRP** — Ripple - - **DOGE** — Dogecoin - - **DOT** — Polkadot - - **MATIC** — Polygon - - **LTC** — Litecoin - - E centenas de outras... + As criptomoedas que `/api/v2/crypto` aceita, com centenas de símbolos. - ### Uso: - - Use os símbolos retornados como valor do parâmetro `coin` no endpoint principal. - - ### Exemplos de Requisição: + Use `search` para filtrar. O valor do campo `coin` de cada item é o que você + passa no parâmetro `coin` do endpoint principal. ```bash - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/crypto/available" - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/crypto/available?search=BTC" + curl -H "Authorization: Bearer SEU_TOKEN" \\ + "https://brapi.dev/api/v2/crypto/available?search=BTC" ``` - **Plano Mínimo:** Startup **Autenticação:** Necessária - Args: search: Filtrar criptomoedas por símbolo diff --git a/src/brapi/resources/v2/currency.py b/src/brapi/resources/v2/currency.py index 958e7df..16cf0cc 100644 --- a/src/brapi/resources/v2/currency.py +++ b/src/brapi/resources/v2/currency.py @@ -58,53 +58,15 @@ def retrieve( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> CurrencyRetrieveResponse: """ - Retorna cotações atualizadas de pares de moedas, com preço de compra/venda, - variação e extremos do dia. + Cotação de pares de moedas, no formato `ORIGEM-DESTINO`, como `USD-BRL`. - ### Funcionalidades: + Cada par traz preço de compra (`bid`), de venda (`ask`), máxima, mínima e + variação do dia. - - **Cotação Atual:** Preço de compra (bid), venda (ask), máxima, mínima, - variação - - **Múltiplos Pares:** Consulte vários em uma requisição (separados por vírgula) - - **Formato:** `ORIGEM-DESTINO` (ex: `USD-BRL`) + Peça vários pares na mesma chamada em `currency=USD-BRL,EUR-BRL,GBP-BRL`. - ### Autenticação: - - Bearer token ou query param `token`. Obtenha em brapi.dev/dashboard. - - ### Exemplos de Requisição: - - ```bash - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/currency?currency=USD-BRL" - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/currency?currency=USD-BRL,EUR-BRL,GBP-BRL" - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/currency?currency=BTC-BRL" - ``` - - ### Pares de Moedas Populares: - - - `USD-BRL` — Dólar Americano / Real - - `EUR-BRL` — Euro / Real - - `GBP-BRL` — Libra Esterlina / Real - - `ARS-BRL` — Peso Argentino / Real - - `EUR-USD` — Euro / Dólar - - `BTC-BRL` — Bitcoin / Real - - `ETH-BRL` — Ethereum / Real - - ### Campos da Resposta: - - - `fromCurrency` / `toCurrency` — Par de moedas - - `name` — Nome do par - - `bidPrice` — Preço de compra - - `askPrice` — Preço de venda - - `high` / `low` — Máxima/Mínima do dia - - `bidVariation` — Variação do preço de compra - - `percentageChange` — Variação percentual (%) - - ### Fonte dos Dados: - - Banco Central do Brasil (PTAX) / Yahoo Finance - - **Plano Mínimo:** Startup **Autenticação:** Necessária + A diferença entre `bid` e `ask` é o spread. Casas de câmbio e bancos cobram + spread bem maior que esse, então não use o número como preço de balcão. Args: currency: Par(es) de moedas separados por vírgula (ex: USD-BRL,EUR-BRL) @@ -141,29 +103,12 @@ def list_available( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> CurrencyListAvailableResponse: """ - Retorna a lista de pares de moedas disponíveis para consulta no endpoint - `/api/v2/currency`. - - ### Formato: - - ORIGEM-DESTINO, onde ORIGEM é o código da moeda de origem e DESTINO a moeda de - destino - - ### Pares Disponíveis: - - - **Moedas Fiduciárias:** USD-BRL, EUR-BRL, GBP-BRL, ARS-BRL, CAD-BRL, AUD-BRL, - JPY-BRL, CNY-BRL - - **Cross Rates:** EUR-USD, GBP-USD - - **Criptomoedas:** BTC-BRL, ETH-BRL - - ### Exemplos de Requisição: + Os pares que `/api/v2/currency` aceita, no formato `ORIGEM-DESTINO`. - ```bash - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/currency/available" - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/currency/available?search=USD" - ``` + A cobertura inclui USD, EUR, GBP, JPY, CHF, CAD, AUD, DKK, NOK e SEK contra o + real, mais os cruzamentos entre as moedas PTAX, como `EUR-USD` e `GBP-USD`. - **Plano Mínimo:** Startup **Autenticação:** Necessária + Filtre com `search`. Args: search: Filtrar pares de moedas por nome ou descrição @@ -225,53 +170,15 @@ async def retrieve( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> CurrencyRetrieveResponse: """ - Retorna cotações atualizadas de pares de moedas, com preço de compra/venda, - variação e extremos do dia. + Cotação de pares de moedas, no formato `ORIGEM-DESTINO`, como `USD-BRL`. - ### Funcionalidades: + Cada par traz preço de compra (`bid`), de venda (`ask`), máxima, mínima e + variação do dia. - - **Cotação Atual:** Preço de compra (bid), venda (ask), máxima, mínima, - variação - - **Múltiplos Pares:** Consulte vários em uma requisição (separados por vírgula) - - **Formato:** `ORIGEM-DESTINO` (ex: `USD-BRL`) + Peça vários pares na mesma chamada em `currency=USD-BRL,EUR-BRL,GBP-BRL`. - ### Autenticação: - - Bearer token ou query param `token`. Obtenha em brapi.dev/dashboard. - - ### Exemplos de Requisição: - - ```bash - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/currency?currency=USD-BRL" - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/currency?currency=USD-BRL,EUR-BRL,GBP-BRL" - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/currency?currency=BTC-BRL" - ``` - - ### Pares de Moedas Populares: - - - `USD-BRL` — Dólar Americano / Real - - `EUR-BRL` — Euro / Real - - `GBP-BRL` — Libra Esterlina / Real - - `ARS-BRL` — Peso Argentino / Real - - `EUR-USD` — Euro / Dólar - - `BTC-BRL` — Bitcoin / Real - - `ETH-BRL` — Ethereum / Real - - ### Campos da Resposta: - - - `fromCurrency` / `toCurrency` — Par de moedas - - `name` — Nome do par - - `bidPrice` — Preço de compra - - `askPrice` — Preço de venda - - `high` / `low` — Máxima/Mínima do dia - - `bidVariation` — Variação do preço de compra - - `percentageChange` — Variação percentual (%) - - ### Fonte dos Dados: - - Banco Central do Brasil (PTAX) / Yahoo Finance - - **Plano Mínimo:** Startup **Autenticação:** Necessária + A diferença entre `bid` e `ask` é o spread. Casas de câmbio e bancos cobram + spread bem maior que esse, então não use o número como preço de balcão. Args: currency: Par(es) de moedas separados por vírgula (ex: USD-BRL,EUR-BRL) @@ -310,29 +217,12 @@ async def list_available( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> CurrencyListAvailableResponse: """ - Retorna a lista de pares de moedas disponíveis para consulta no endpoint - `/api/v2/currency`. - - ### Formato: - - ORIGEM-DESTINO, onde ORIGEM é o código da moeda de origem e DESTINO a moeda de - destino - - ### Pares Disponíveis: - - - **Moedas Fiduciárias:** USD-BRL, EUR-BRL, GBP-BRL, ARS-BRL, CAD-BRL, AUD-BRL, - JPY-BRL, CNY-BRL - - **Cross Rates:** EUR-USD, GBP-USD - - **Criptomoedas:** BTC-BRL, ETH-BRL - - ### Exemplos de Requisição: + Os pares que `/api/v2/currency` aceita, no formato `ORIGEM-DESTINO`. - ```bash - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/currency/available" - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/currency/available?search=USD" - ``` + A cobertura inclui USD, EUR, GBP, JPY, CHF, CAD, AUD, DKK, NOK e SEK contra o + real, mais os cruzamentos entre as moedas PTAX, como `EUR-USD` e `GBP-USD`. - **Plano Mínimo:** Startup **Autenticação:** Necessária + Filtre com `search`. Args: search: Filtrar pares de moedas por nome ou descrição diff --git a/src/brapi/resources/v2/inflation.py b/src/brapi/resources/v2/inflation.py index aca120f..2075c53 100644 --- a/src/brapi/resources/v2/inflation.py +++ b/src/brapi/resources/v2/inflation.py @@ -2,12 +2,14 @@ from __future__ import annotations +from typing_extensions import Literal + import httpx from ..._types import Body, Omit, Query, Headers, NotGiven, omit, not_given from ..._utils import maybe_transform, async_maybe_transform from ..._compat import cached_property -from ...types.v2 import inflation_retrieve_params +from ...types.v2 import inflation_retrieve_params, inflation_list_available_params from ..._resource import SyncAPIResource, AsyncAPIResource from ..._response import ( to_raw_response_wrapper, @@ -58,60 +60,19 @@ def retrieve( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> InflationRetrieveResponse: """ - Retorna dados históricos do **IPCA (Índice Nacional de Preços ao Consumidor - Amplo)**, o índice oficial de inflação do Brasil, medido pelo IBGE. - - ### Funcionalidades - - - **Dados Mensais:** Variação percentual mensal do IPCA - - **Histórico Completo:** Dados desde janeiro/2000 até o mês atual - - **Filtros de Período:** Use `start` e `end` para definir período específico - (formato DD/MM/YYYY) - - **Ordenação:** Ordene por data ou valor, crescente ou decrescente - - ### Autenticação - - Bearer token ou query param `token`. Requer plano Startup. - - ### Exemplos de Uso - - ```bash - # Padrão (últimos 12 meses) - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/inflation" - - # Histórico completo - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/inflation?historical=true" - - # Período específico - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/inflation?start=01/01/2023&end=31/12/2023" - - # Ordenado por valor (decrescente) - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/inflation?historical=true&sortBy=value&sortOrder=desc" - ``` - - ### Parâmetros de Ordenação - - - `sortBy`: `date` (padrão) ou `value` - - `sortOrder`: `desc` (padrão) ou `asc` - - ### Campos da Resposta + Série do IPCA, o índice oficial de inflação do Brasil, publicada pelo Banco + Central. - - `date` — Data no formato DD/MM/YYYY - - `value` — Variação percentual do IPCA no mês - - `epochDate` — Data em timestamp Unix (milissegundos) + Os dados são mensais e começam em janeiro de 2000. Cada ponto é a variação + percentual do mês, não o acumulado do ano. - ### Sobre o IPCA + Filtre o período com `start` e `end` no formato `DD/MM/YYYY`. Ordene por data ou + por valor. - O IPCA é o índice oficial de inflação do Brasil, calculado mensalmente pelo - IBGE. Ele mede a variação de preços de uma cesta de produtos e serviços - consumidos pelas famílias brasileiras. + O IPCA sai por volta do dia 10 do mês seguinte. O mês corrente nunca está na + série. - ### Fonte dos Dados - - Banco Central do Brasil (BCB) — indicador IPCA publicado como série temporal - oficial - - **Plano Mínimo:** Startup | **Autenticação:** Necessária + Plano Startup. Args: end: Data de fim (DD/MM/YYYY) @@ -156,6 +117,7 @@ def retrieve( def list_available( self, *, + format: Literal["json"] | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, @@ -164,26 +126,31 @@ def list_available( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> InflationListAvailableResponse: """ - Retorna a lista de países disponíveis para consulta de dados de inflação. + Os países que `/api/v2/inflation` aceita. - ### Países Disponíveis + Hoje só `brazil`, com o IPCA publicado pelo Banco Central. - - **brazil** — Dados do IPCA (IBGE) + Plano Startup. - Use o valor retornado como referência para futuras expansões do endpoint. + Args: + format: Formato da resposta. JSON é o formato suportado. - ### Exemplo de Uso + extra_headers: Send extra headers - ```bash - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/inflation/available" - ``` + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request - **Plano Mínimo:** Startup | **Autenticação:** Necessária + timeout: Override the client-level default timeout for this request, in seconds """ return self._get( "/api/v2/inflation/available", options=make_request_options( - extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + query=maybe_transform({"format": format}, inflation_list_available_params.InflationListAvailableParams), ), cast_to=InflationListAvailableResponse, ) @@ -225,60 +192,19 @@ async def retrieve( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> InflationRetrieveResponse: """ - Retorna dados históricos do **IPCA (Índice Nacional de Preços ao Consumidor - Amplo)**, o índice oficial de inflação do Brasil, medido pelo IBGE. - - ### Funcionalidades + Série do IPCA, o índice oficial de inflação do Brasil, publicada pelo Banco + Central. - - **Dados Mensais:** Variação percentual mensal do IPCA - - **Histórico Completo:** Dados desde janeiro/2000 até o mês atual - - **Filtros de Período:** Use `start` e `end` para definir período específico - (formato DD/MM/YYYY) - - **Ordenação:** Ordene por data ou valor, crescente ou decrescente + Os dados são mensais e começam em janeiro de 2000. Cada ponto é a variação + percentual do mês, não o acumulado do ano. - ### Autenticação + Filtre o período com `start` e `end` no formato `DD/MM/YYYY`. Ordene por data ou + por valor. - Bearer token ou query param `token`. Requer plano Startup. + O IPCA sai por volta do dia 10 do mês seguinte. O mês corrente nunca está na + série. - ### Exemplos de Uso - - ```bash - # Padrão (últimos 12 meses) - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/inflation" - - # Histórico completo - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/inflation?historical=true" - - # Período específico - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/inflation?start=01/01/2023&end=31/12/2023" - - # Ordenado por valor (decrescente) - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/inflation?historical=true&sortBy=value&sortOrder=desc" - ``` - - ### Parâmetros de Ordenação - - - `sortBy`: `date` (padrão) ou `value` - - `sortOrder`: `desc` (padrão) ou `asc` - - ### Campos da Resposta - - - `date` — Data no formato DD/MM/YYYY - - `value` — Variação percentual do IPCA no mês - - `epochDate` — Data em timestamp Unix (milissegundos) - - ### Sobre o IPCA - - O IPCA é o índice oficial de inflação do Brasil, calculado mensalmente pelo - IBGE. Ele mede a variação de preços de uma cesta de produtos e serviços - consumidos pelas famílias brasileiras. - - ### Fonte dos Dados - - Banco Central do Brasil (BCB) — indicador IPCA publicado como série temporal - oficial - - **Plano Mínimo:** Startup | **Autenticação:** Necessária + Plano Startup. Args: end: Data de fim (DD/MM/YYYY) @@ -323,6 +249,7 @@ async def retrieve( async def list_available( self, *, + format: Literal["json"] | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, @@ -331,26 +258,33 @@ async def list_available( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> InflationListAvailableResponse: """ - Retorna a lista de países disponíveis para consulta de dados de inflação. + Os países que `/api/v2/inflation` aceita. - ### Países Disponíveis + Hoje só `brazil`, com o IPCA publicado pelo Banco Central. - - **brazil** — Dados do IPCA (IBGE) + Plano Startup. - Use o valor retornado como referência para futuras expansões do endpoint. + Args: + format: Formato da resposta. JSON é o formato suportado. + + extra_headers: Send extra headers - ### Exemplo de Uso + extra_query: Add additional query parameters to the request - ```bash - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/inflation/available" - ``` + extra_body: Add additional JSON properties to the request - **Plano Mínimo:** Startup | **Autenticação:** Necessária + timeout: Override the client-level default timeout for this request, in seconds """ return await self._get( "/api/v2/inflation/available", options=make_request_options( - extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + query=await async_maybe_transform( + {"format": format}, inflation_list_available_params.InflationListAvailableParams + ), ), cast_to=InflationListAvailableResponse, ) diff --git a/src/brapi/resources/v2/prime_rate.py b/src/brapi/resources/v2/prime_rate.py index c2630aa..76db5ea 100644 --- a/src/brapi/resources/v2/prime_rate.py +++ b/src/brapi/resources/v2/prime_rate.py @@ -2,12 +2,14 @@ from __future__ import annotations +from typing_extensions import Literal + import httpx from ..._types import Body, Omit, Query, Headers, NotGiven, omit, not_given from ..._utils import maybe_transform, async_maybe_transform from ..._compat import cached_property -from ...types.v2 import prime_rate_retrieve_params +from ...types.v2 import prime_rate_retrieve_params, prime_rate_list_available_params from ..._resource import SyncAPIResource, AsyncAPIResource from ..._response import ( to_raw_response_wrapper, @@ -58,60 +60,19 @@ def retrieve( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> PrimeRateRetrieveResponse: """ - Retorna dados históricos da **Taxa SELIC (Sistema Especial de Liquidação e de - Custódia)**, a taxa básica de juros da economia brasileira, definida pelo COPOM - (Comitê de Política Monetária) do Banco Central. - - ### Funcionalidades - - - **Dados Diários:** Taxa SELIC diária (meta anualizada, % a.a.) - - **Histórico Completo:** Dados desde janeiro/2000 até a data atual - - **Filtros de Período:** Use `start` e `end` (formato DD/MM/YYYY) - - **Ordenação:** Por data ou valor, crescente ou decrescente - - ### Autenticação - - Bearer token ou query param `token`. Requer plano Startup. - - ### Exemplos de Uso - - ```bash - # Padrão (últimos 12 meses) - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/prime-rate" - - # Histórico completo - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/prime-rate?historical=true" - - # Período específico - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/prime-rate?start=01/01/2023&end=31/12/2023" - - # Ordenado por valor (decrescente) - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/prime-rate?historical=true&sortBy=value&sortOrder=desc" - ``` - - ### Parâmetros de Ordenação - - - `sortBy`: `date` (padrão) ou `value` - - `sortOrder`: `desc` (padrão) ou `asc` - - ### Campos da Resposta - - - `date` — Data no formato DD/MM/YYYY - - `value` — Taxa SELIC meta anualizada (% a.a.) - - `epochDate` — Data em timestamp Unix (milissegundos) + Série da taxa SELIC, a taxa básica de juros da economia brasileira, definida + pelo COPOM. - ### Sobre a SELIC + Os dados são diários e começam em janeiro de 2000. O valor é a meta anualizada, + em porcentagem ao ano. - A SELIC é a taxa básica de juros da economia brasileira e influencia todas as - demais taxas de juros do país (empréstimos, financiamentos, aplicações - financeiras). Ela é definida pelo COPOM a cada 45 dias e serve como referência - para o CDI. + Filtre o período com `start` e `end` no formato `DD/MM/YYYY`. Ordene por data ou + por valor. - ### Fonte dos Dados + A meta muda só nas reuniões do COPOM, a cada 45 dias. Entre uma reunião e outra, + a série repete o mesmo valor todo dia útil. - Banco Central do Brasil (BCB) — meta SELIC publicada como série temporal oficial - - **Plano Mínimo:** Startup | **Autenticação:** Necessária + Plano Startup. Args: end: Data de fim (DD/MM/YYYY) @@ -156,6 +117,7 @@ def retrieve( def list_available( self, *, + format: Literal["json"] | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, @@ -164,26 +126,33 @@ def list_available( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> PrimeRateListAvailableResponse: """ - Retorna a lista de países disponíveis para consulta de dados de taxa de juros. + Os países que `/api/v2/prime-rate` aceita. - ### Países Disponíveis + Hoje só `brazil`, com a SELIC do Banco Central. - - **brazil** — Taxa SELIC (Banco Central) + Plano Startup. - Use o valor retornado como referência para futuras expansões do endpoint. + Args: + format: Formato da resposta. JSON é o formato suportado. - ### Exemplo de Uso + extra_headers: Send extra headers - ```bash - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/prime-rate/available" - ``` + extra_query: Add additional query parameters to the request - **Plano Mínimo:** Startup | **Autenticação:** Necessária + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds """ return self._get( "/api/v2/prime-rate/available", options=make_request_options( - extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + query=maybe_transform( + {"format": format}, prime_rate_list_available_params.PrimeRateListAvailableParams + ), ), cast_to=PrimeRateListAvailableResponse, ) @@ -225,60 +194,19 @@ async def retrieve( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> PrimeRateRetrieveResponse: """ - Retorna dados históricos da **Taxa SELIC (Sistema Especial de Liquidação e de - Custódia)**, a taxa básica de juros da economia brasileira, definida pelo COPOM - (Comitê de Política Monetária) do Banco Central. + Série da taxa SELIC, a taxa básica de juros da economia brasileira, definida + pelo COPOM. - ### Funcionalidades + Os dados são diários e começam em janeiro de 2000. O valor é a meta anualizada, + em porcentagem ao ano. - - **Dados Diários:** Taxa SELIC diária (meta anualizada, % a.a.) - - **Histórico Completo:** Dados desde janeiro/2000 até a data atual - - **Filtros de Período:** Use `start` e `end` (formato DD/MM/YYYY) - - **Ordenação:** Por data ou valor, crescente ou decrescente + Filtre o período com `start` e `end` no formato `DD/MM/YYYY`. Ordene por data ou + por valor. - ### Autenticação + A meta muda só nas reuniões do COPOM, a cada 45 dias. Entre uma reunião e outra, + a série repete o mesmo valor todo dia útil. - Bearer token ou query param `token`. Requer plano Startup. - - ### Exemplos de Uso - - ```bash - # Padrão (últimos 12 meses) - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/prime-rate" - - # Histórico completo - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/prime-rate?historical=true" - - # Período específico - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/prime-rate?start=01/01/2023&end=31/12/2023" - - # Ordenado por valor (decrescente) - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/prime-rate?historical=true&sortBy=value&sortOrder=desc" - ``` - - ### Parâmetros de Ordenação - - - `sortBy`: `date` (padrão) ou `value` - - `sortOrder`: `desc` (padrão) ou `asc` - - ### Campos da Resposta - - - `date` — Data no formato DD/MM/YYYY - - `value` — Taxa SELIC meta anualizada (% a.a.) - - `epochDate` — Data em timestamp Unix (milissegundos) - - ### Sobre a SELIC - - A SELIC é a taxa básica de juros da economia brasileira e influencia todas as - demais taxas de juros do país (empréstimos, financiamentos, aplicações - financeiras). Ela é definida pelo COPOM a cada 45 dias e serve como referência - para o CDI. - - ### Fonte dos Dados - - Banco Central do Brasil (BCB) — meta SELIC publicada como série temporal oficial - - **Plano Mínimo:** Startup | **Autenticação:** Necessária + Plano Startup. Args: end: Data de fim (DD/MM/YYYY) @@ -323,6 +251,7 @@ async def retrieve( async def list_available( self, *, + format: Literal["json"] | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. # The extra values given here take precedence over values defined on the client or passed to this method. extra_headers: Headers | None = None, @@ -331,26 +260,33 @@ async def list_available( timeout: float | httpx.Timeout | None | NotGiven = not_given, ) -> PrimeRateListAvailableResponse: """ - Retorna a lista de países disponíveis para consulta de dados de taxa de juros. + Os países que `/api/v2/prime-rate` aceita. - ### Países Disponíveis + Hoje só `brazil`, com a SELIC do Banco Central. - - **brazil** — Taxa SELIC (Banco Central) + Plano Startup. - Use o valor retornado como referência para futuras expansões do endpoint. + Args: + format: Formato da resposta. JSON é o formato suportado. - ### Exemplo de Uso + extra_headers: Send extra headers - ```bash - curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/prime-rate/available" - ``` + extra_query: Add additional query parameters to the request - **Plano Mínimo:** Startup | **Autenticação:** Necessária + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds """ return await self._get( "/api/v2/prime-rate/available", options=make_request_options( - extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + query=await async_maybe_transform( + {"format": format}, prime_rate_list_available_params.PrimeRateListAvailableParams + ), ), cast_to=PrimeRateListAvailableResponse, ) diff --git a/src/brapi/types/financial_data_entry.py b/src/brapi/types/financial_data_entry.py index 5599712..b7b2d18 100644 --- a/src/brapi/types/financial_data_entry.py +++ b/src/brapi/types/financial_data_entry.py @@ -23,7 +23,7 @@ class FinancialDataEntry(BaseModel): earnings_growth: Optional[float] = FieldInfo(alias="earningsGrowth", default=None) """ - Crescimento do lucro do controlador (TTM) — variação dos últimos 4 trimestres em + Crescimento do lucro do controlador (TTM) - variação dos últimos 4 trimestres em relação aos 4 trimestres imediatamente anteriores, usando Lucro Líquido Atribuível aos Controladores. Para crescimento anual (DRE de exercício vs. exercício anterior), use earningsGrowthAnnual. @@ -31,7 +31,7 @@ class FinancialDataEntry(BaseModel): earnings_growth_annual: Optional[float] = FieldInfo(alias="earningsGrowthAnnual", default=None) """ - Crescimento anual do lucro do controlador — variação do Lucro Líquido Atribuível + Crescimento anual do lucro do controlador - variação do Lucro Líquido Atribuível aos Controladores do último exercício social completo em relação ao exercício anterior. """ @@ -74,14 +74,14 @@ class FinancialDataEntry(BaseModel): revenue_growth: Optional[float] = FieldInfo(alias="revenueGrowth", default=None) """ - Crescimento da receita (TTM) — variação da receita dos últimos 4 trimestres em + Crescimento da receita (TTM) - variação da receita dos últimos 4 trimestres em relação aos 4 trimestres imediatamente anteriores. Para crescimento anual (DRE de exercício vs. exercício anterior), use revenueGrowthAnnual. """ revenue_growth_annual: Optional[float] = FieldInfo(alias="revenueGrowthAnnual", default=None) """ - Crescimento anual da receita — variação da Receita Líquida do último exercício + Crescimento anual da receita - variação da Receita Líquida do último exercício social completo em relação ao exercício anterior. """ diff --git a/src/brapi/types/quote_list_params.py b/src/brapi/types/quote_list_params.py index e8bc904..702a6a4 100644 --- a/src/brapi/types/quote_list_params.py +++ b/src/brapi/types/quote_list_params.py @@ -33,6 +33,9 @@ class QuoteListParams(TypedDict, total=False): sort_order: Annotated[Literal["asc", "desc"], PropertyInfo(alias="sortOrder")] """Ordem de classificação""" + subsector: str + """Filtrar pelo subsetor B3""" + sub_type: Annotated[ Literal["stock", "unit", "fii", "etf", "fi-infra", "fi-agro", "fip", "fidc", "bdr"], PropertyInfo(alias="subType"), diff --git a/src/brapi/types/quote_list_response.py b/src/brapi/types/quote_list_response.py index bd976e0..62d1d7f 100644 --- a/src/brapi/types/quote_list_response.py +++ b/src/brapi/types/quote_list_response.py @@ -37,6 +37,9 @@ class Stock(BaseModel): stock: str """Ticker do ativo""" + subsector: Optional[str] = None + """Subsetor B3""" + sub_type: Optional[str] = FieldInfo(alias="subType", default=None) """ Classificação aditiva do ativo: stock, unit, fii, etf, fi-infra, fi-agro, fip, @@ -55,6 +58,8 @@ class QuoteListResponse(BaseModel): available_stock_types: List[str] = FieldInfo(alias="availableStockTypes") + available_subsectors: List[str] = FieldInfo(alias="availableSubsectors") + available_sub_type_types: List[str] = FieldInfo(alias="availableSubTypeTypes") indexes: List[Index] diff --git a/src/brapi/types/quote_retrieve_params.py b/src/brapi/types/quote_retrieve_params.py index 27edbb1..ee2f0a6 100644 --- a/src/brapi/types/quote_retrieve_params.py +++ b/src/brapi/types/quote_retrieve_params.py @@ -19,6 +19,12 @@ class QuoteRetrieveParams(TypedDict, total=False): end_date: Annotated[str, PropertyInfo(alias="endDate")] """Data final para dados históricos (formato YYYY-MM-DD)""" + include_raw: Annotated[Literal["true", "false"], PropertyInfo(alias="includeRaw")] + """ + Incluir preços OHLC originais armazenados no banco da brapi para intervalos + diários. Use includeRaw=true. Disponível no plano Pro. + """ + interval: Literal["1m", "2m", "5m", "15m", "30m", "60m", "90m", "1h", "1d", "5d", "1wk", "1mo", "3mo"] """Intervalo/granularidade dos dados históricos""" diff --git a/src/brapi/types/quote_retrieve_response.py b/src/brapi/types/quote_retrieve_response.py index bc13bb6..79c8e1e 100644 --- a/src/brapi/types/quote_retrieve_response.py +++ b/src/brapi/types/quote_retrieve_response.py @@ -29,6 +29,9 @@ class ResultDividendsDataCashDividend(BaseModel): asset_issued: str = FieldInfo(alias="assetIssued") """Código ISIN do ativo emissor""" + ex_date: Optional[str] = FieldInfo(alias="exDate", default=None) + """Data ex (primeiro dia sem direito ao provento)""" + isin_code: str = FieldInfo(alias="isinCode") """Código ISIN""" @@ -50,6 +53,12 @@ class ResultDividendsDataCashDividend(BaseModel): remarks: str """Observações""" + raw_rate: Optional[float] = FieldInfo(alias="rawRate", default=None) + """Valor por ação convertido para a escala dos preços brutos com base histórica. + + Retornado com includeRaw=true. + """ + class ResultDividendsDataStockDividend(BaseModel): approved_on: Optional[str] = FieldInfo(alias="approvedOn", default=None) @@ -61,6 +70,9 @@ class ResultDividendsDataStockDividend(BaseModel): complete_factor: str = FieldInfo(alias="completeFactor") """Fator completo (ex: 2 para 1)""" + ex_date: Optional[str] = FieldInfo(alias="exDate", default=None) + """Data ex do evento corporativo""" + factor: float """Fator do desdobramento/grupamento""" @@ -118,6 +130,34 @@ class ResultHistoricalDataPrice(BaseModel): volume: int """Volume financeiro negociado no intervalo.""" + raw_close: Optional[float] = FieldInfo(alias="rawClose", default=None) + """Preço de fechamento original armazenado no banco da brapi. + + Retornado com includeRaw=true em intervalos diários no plano Pro. Pode ser nulo + quando não houver valor no banco. + """ + + raw_high: Optional[float] = FieldInfo(alias="rawHigh", default=None) + """Preço máximo original armazenado no banco da brapi. + + Retornado com includeRaw=true em intervalos diários no plano Pro. Pode ser nulo + quando não houver valor no banco. + """ + + raw_low: Optional[float] = FieldInfo(alias="rawLow", default=None) + """Preço mínimo original armazenado no banco da brapi. + + Retornado com includeRaw=true em intervalos diários no plano Pro. Pode ser nulo + quando não houver valor no banco. + """ + + raw_open: Optional[float] = FieldInfo(alias="rawOpen", default=None) + """Preço de abertura original armazenado no banco da brapi. + + Retornado com includeRaw=true em intervalos diários no plano Pro. Pode ser nulo + quando não houver valor no banco. + """ + class ResultSummaryProfile(BaseModel): """Perfil da empresa (quando modules inclui summaryProfile)""" diff --git a/src/brapi/types/v2/__init__.py b/src/brapi/types/v2/__init__.py index 6fe0126..febc9e5 100644 --- a/src/brapi/types/v2/__init__.py +++ b/src/brapi/types/v2/__init__.py @@ -13,6 +13,8 @@ from .prime_rate_retrieve_response import PrimeRateRetrieveResponse as PrimeRateRetrieveResponse from .crypto_list_available_response import CryptoListAvailableResponse as CryptoListAvailableResponse from .currency_list_available_params import CurrencyListAvailableParams as CurrencyListAvailableParams +from .inflation_list_available_params import InflationListAvailableParams as InflationListAvailableParams from .currency_list_available_response import CurrencyListAvailableResponse as CurrencyListAvailableResponse +from .prime_rate_list_available_params import PrimeRateListAvailableParams as PrimeRateListAvailableParams from .inflation_list_available_response import InflationListAvailableResponse as InflationListAvailableResponse from .prime_rate_list_available_response import PrimeRateListAvailableResponse as PrimeRateListAvailableResponse diff --git a/src/brapi/types/v2/inflation_list_available_params.py b/src/brapi/types/v2/inflation_list_available_params.py new file mode 100644 index 0000000..0d83ada --- /dev/null +++ b/src/brapi/types/v2/inflation_list_available_params.py @@ -0,0 +1,12 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, TypedDict + +__all__ = ["InflationListAvailableParams"] + + +class InflationListAvailableParams(TypedDict, total=False): + format: Literal["json"] + """Formato da resposta. JSON é o formato suportado.""" diff --git a/src/brapi/types/v2/prime_rate_list_available_params.py b/src/brapi/types/v2/prime_rate_list_available_params.py new file mode 100644 index 0000000..984c055 --- /dev/null +++ b/src/brapi/types/v2/prime_rate_list_available_params.py @@ -0,0 +1,12 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, TypedDict + +__all__ = ["PrimeRateListAvailableParams"] + + +class PrimeRateListAvailableParams(TypedDict, total=False): + format: Literal["json"] + """Formato da resposta. JSON é o formato suportado.""" diff --git a/tests/api_resources/test_quote.py b/tests/api_resources/test_quote.py index aa77cbe..b789328 100644 --- a/tests/api_resources/test_quote.py +++ b/tests/api_resources/test_quote.py @@ -33,6 +33,7 @@ def test_method_retrieve_with_all_params(self, client: Brapi) -> None: token="token", dividends="true", end_date="2024-12-31", + include_raw="true", interval="1m", modules="summaryProfile,balanceSheetHistory,financialData", range="1d", @@ -91,6 +92,7 @@ def test_method_list_with_all_params(self, client: Brapi) -> None: sector="sector", sort_by="name", sort_order="asc", + subsector="subsector", sub_type="stock", type="stock", ) @@ -140,6 +142,7 @@ async def test_method_retrieve_with_all_params(self, async_client: AsyncBrapi) - token="token", dividends="true", end_date="2024-12-31", + include_raw="true", interval="1m", modules="summaryProfile,balanceSheetHistory,financialData", range="1d", @@ -198,6 +201,7 @@ async def test_method_list_with_all_params(self, async_client: AsyncBrapi) -> No sector="sector", sort_by="name", sort_order="asc", + subsector="subsector", sub_type="stock", type="stock", ) diff --git a/tests/api_resources/v2/test_inflation.py b/tests/api_resources/v2/test_inflation.py index 34b18a2..62c7ec4 100644 --- a/tests/api_resources/v2/test_inflation.py +++ b/tests/api_resources/v2/test_inflation.py @@ -9,7 +9,10 @@ from brapi import Brapi, AsyncBrapi from tests.utils import assert_matches_type -from brapi.types.v2 import InflationRetrieveResponse, InflationListAvailableResponse +from brapi.types.v2 import ( + InflationRetrieveResponse, + InflationListAvailableResponse, +) base_url = os.environ.get("TEST_API_BASE_URL", "http://127.0.0.1:4010") @@ -63,6 +66,14 @@ def test_method_list_available(self, client: Brapi) -> None: inflation = client.v2.inflation.list_available() assert_matches_type(InflationListAvailableResponse, inflation, path=["response"]) + @pytest.mark.skip(reason="Mock server tests are disabled") + @parametrize + def test_method_list_available_with_all_params(self, client: Brapi) -> None: + inflation = client.v2.inflation.list_available( + format="json", + ) + assert_matches_type(InflationListAvailableResponse, inflation, path=["response"]) + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_raw_response_list_available(self, client: Brapi) -> None: @@ -137,6 +148,14 @@ async def test_method_list_available(self, async_client: AsyncBrapi) -> None: inflation = await async_client.v2.inflation.list_available() assert_matches_type(InflationListAvailableResponse, inflation, path=["response"]) + @pytest.mark.skip(reason="Mock server tests are disabled") + @parametrize + async def test_method_list_available_with_all_params(self, async_client: AsyncBrapi) -> None: + inflation = await async_client.v2.inflation.list_available( + format="json", + ) + assert_matches_type(InflationListAvailableResponse, inflation, path=["response"]) + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_raw_response_list_available(self, async_client: AsyncBrapi) -> None: diff --git a/tests/api_resources/v2/test_prime_rate.py b/tests/api_resources/v2/test_prime_rate.py index fc3819b..c240acf 100644 --- a/tests/api_resources/v2/test_prime_rate.py +++ b/tests/api_resources/v2/test_prime_rate.py @@ -9,7 +9,10 @@ from brapi import Brapi, AsyncBrapi from tests.utils import assert_matches_type -from brapi.types.v2 import PrimeRateRetrieveResponse, PrimeRateListAvailableResponse +from brapi.types.v2 import ( + PrimeRateRetrieveResponse, + PrimeRateListAvailableResponse, +) base_url = os.environ.get("TEST_API_BASE_URL", "http://127.0.0.1:4010") @@ -63,6 +66,14 @@ def test_method_list_available(self, client: Brapi) -> None: prime_rate = client.v2.prime_rate.list_available() assert_matches_type(PrimeRateListAvailableResponse, prime_rate, path=["response"]) + @pytest.mark.skip(reason="Mock server tests are disabled") + @parametrize + def test_method_list_available_with_all_params(self, client: Brapi) -> None: + prime_rate = client.v2.prime_rate.list_available( + format="json", + ) + assert_matches_type(PrimeRateListAvailableResponse, prime_rate, path=["response"]) + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize def test_raw_response_list_available(self, client: Brapi) -> None: @@ -137,6 +148,14 @@ async def test_method_list_available(self, async_client: AsyncBrapi) -> None: prime_rate = await async_client.v2.prime_rate.list_available() assert_matches_type(PrimeRateListAvailableResponse, prime_rate, path=["response"]) + @pytest.mark.skip(reason="Mock server tests are disabled") + @parametrize + async def test_method_list_available_with_all_params(self, async_client: AsyncBrapi) -> None: + prime_rate = await async_client.v2.prime_rate.list_available( + format="json", + ) + assert_matches_type(PrimeRateListAvailableResponse, prime_rate, path=["response"]) + @pytest.mark.skip(reason="Mock server tests are disabled") @parametrize async def test_raw_response_list_available(self, async_client: AsyncBrapi) -> None: