Migração de /api/quote para /api/v2/stocks

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

Use /api/v2/tickers para buscar, filtrar e validar símbolos.
Use /api/v2/tickers/resolve quando o usuário informar um ticker antigo.
Use /api/v2/tickers/renames para mostrar histórico de mudanças de código.
Use /api/v2/tickers/coverage para decidir qual endpoint consultar.
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.