# Migração de /api/quote para /api/v2/stocks
URL: /docs/acoes/migracao-v2.mdx

Guia para migrar integrações do endpoint legado de cotação para endpoints v2 composáveis.

***

title: Migração de /api/quote para /api/v2/stocks
description: Guia para migrar integrações do endpoint legado de cotação para endpoints v2 composáveis.
full: true
keywords: brapi, api, ações, migração, quote, stocks, v2
lang: pt-BR
-----------

O endpoint legado `/api/quote/{tickers}` continua funcionando. Para novas
integrações, prefira os endpoints v2 por preocupação: descoberta de ticker,
cotação, histórico, dividendos e fundamentos ficam separados.

## Fluxo recomendado

1. Use `/api/v2/tickers` para buscar, filtrar e validar símbolos.
2. Use `/api/v2/tickers/resolve` quando o usuário informar um ticker antigo.
3. Use `/api/v2/tickers/renames` para mostrar histórico de mudanças de código.
4. Use `/api/v2/tickers/coverage` para decidir qual endpoint consultar.
5. Chame o endpoint v2 específico para o dado que você precisa.

## Mapeamento de endpoints

| Legado                                                     | V2 recomendado                                                                    |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `/api/quote/list`                                          | `/api/v2/tickers`                                                                 |
| `/api/quote/PETR4`                                         | `/api/v2/stocks/quote?symbols=PETR4`                                              |
| `/api/quote/PETR4,VALE3`                                   | `/api/v2/stocks/quote?symbols=PETR4,VALE3`                                        |
| `/api/quote/PETR4?range=1y&interval=1d`                    | `/api/v2/stocks/historical?symbols=PETR4&range=1y&interval=1d`                    |
| `/api/quote/PETR4?startDate=2024-01-01&endDate=2024-12-31` | `/api/v2/stocks/historical?symbols=PETR4&startDate=2024-01-01&endDate=2024-12-31` |
| `/api/quote/PETR4?dividends=true`                          | `/api/v2/stocks/dividends?symbols=PETR4`                                          |

Dividendos/rendimentos de FIIs continuam em `/api/v2/fii/dividends`. Não use
`/api/v2/stocks/dividends` para FIIs quando você precisa da semântica dedicada
de rendimentos de fundos imobiliários.

## Diferenças na resposta

Os endpoints v2 mantêm o envelope `{ results, requestedAt, took }`, mas cada
endpoint retorna apenas o dado daquele domínio:

| V2                                | Campo principal                                                                                              |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `/api/v2/stocks/quote`            | `results[].data.regularMarketPrice`, `results[].data.regularMarketChangePercent`, `results[].data.marketCap` |
| `/api/v2/stocks/historical`       | `results[].data.historicalDataPrice`                                                                         |
| `/api/v2/stocks/dividends`        | `results[].data.cashDividends`, `results[].data.stockDividends`, `results[].data.subscriptions`              |
| `/api/v2/stocks/profile`          | `results[].data`                                                                                             |
| `/api/v2/stocks/statistics`       | `results[].data`                                                                                             |
| `/api/v2/stocks/financial-data`   | `results[].data`                                                                                             |
| `/api/v2/stocks/balance-sheet`    | `results[].data`                                                                                             |
| `/api/v2/stocks/income-statement` | `results[].data`                                                                                             |
| `/api/v2/stocks/cash-flow`        | `results[].data`                                                                                             |
| `/api/v2/stocks/value-added`      | `results[].data`                                                                                             |

Quando um ticker antigo é resolvido, os itens retornam `requestedSymbol`,
`symbol` e `changed`, permitindo mostrar ao usuário que o código foi atualizado.

## Mapeamento de módulos

| Módulo legado                          | V2 recomendado                                                              |
| -------------------------------------- | --------------------------------------------------------------------------- |
| `summaryProfile`                       | `/api/v2/stocks/profile?symbols=PETR4`                                      |
| `defaultKeyStatistics`                 | `/api/v2/stocks/statistics?symbols=PETR4&mode=current`                      |
| `defaultKeyStatisticsHistory`          | `/api/v2/stocks/statistics?symbols=PETR4&mode=history&period=annual`        |
| `defaultKeyStatisticsHistoryQuarterly` | `/api/v2/stocks/statistics?symbols=PETR4&mode=history&period=quarterly`     |
| `financialData`                        | `/api/v2/stocks/financial-data?symbols=PETR4&mode=current`                  |
| `financialDataHistory`                 | `/api/v2/stocks/financial-data?symbols=PETR4&mode=history&period=annual`    |
| `financialDataHistoryQuarterly`        | `/api/v2/stocks/financial-data?symbols=PETR4&mode=history&period=quarterly` |
| `balanceSheetHistory`                  | `/api/v2/stocks/balance-sheet?symbols=PETR4&period=annual`                  |
| `balanceSheetHistoryQuarterly`         | `/api/v2/stocks/balance-sheet?symbols=PETR4&period=quarterly`               |
| `incomeStatementHistory`               | `/api/v2/stocks/income-statement?symbols=PETR4&period=annual`               |
| `incomeStatementHistoryQuarterly`      | `/api/v2/stocks/income-statement?symbols=PETR4&period=quarterly`            |
| `cashflowHistory`                      | `/api/v2/stocks/cash-flow?symbols=PETR4&period=annual`                      |
| `cashflowHistoryQuarterly`             | `/api/v2/stocks/cash-flow?symbols=PETR4&period=quarterly`                   |
| `valueAddedHistory`                    | `/api/v2/stocks/value-added?symbols=PETR4&period=annual`                    |
| `valueAddedHistoryQuarterly`           | `/api/v2/stocks/value-added?symbols=PETR4&period=quarterly`                 |

## Compatibilidade

Use `/api/quote/{tickers}` quando você precisa manter uma integração antiga
sem alterar contrato. Use `/api/v2/stocks/*` quando estiver construindo uma
integração nova, um agente de IA, uma tela de produto ou um pipeline em que
cada chamada deve buscar apenas um tipo de dado.