# Analistas.com.br — Documentação Completa do Portal

Este arquivo contém a descrição detalhada das seções, rotas, tipos de dados de mercado e APIs disponíveis no portal Analistas. É otimizado para o consumo por LLMs e agentes de IA que necessitam entender a arquitetura de conteúdo do site.

---

## 1. Arquitetura de Conteúdo e Rotas

O site está estruturado nas seguintes seções públicas:

### Ações e BDRs
- `/acoes` — Painel principal com a listagem das 50 principais ações da B3 ordenadas por padrão.
- `/acao/[ticker]` — Página de detalhes de uma ação individual (ex: `/acao/petr4`). Contém:
  - Cotação em tempo real (com delay da API BRAPI).
  - Indicadores fundamentalistas (P/L, P/VP, ROE, LPA, VPA, Margem Líquida, Dívida Bruta/Patrimônio).
  - Gráfico de preços histórico com seletores de período (1M, 3M, 6M, 1A, 5A).
  - Tabela de Dividendos pagos (Data com, Data de pagamento, Tipo e Valor).
  - Perfil da empresa (Setor, indústria, descrição e número de funcionários).
- `/bdrs/[ticker]` — Página de detalhes de Brazilian Depositary Receipts (ex: `/bdrs/aapl34`).
- `/etfs/[ticker]` — Página de detalhes de Exchange Traded Funds (ex: `/etfs/bova11`).

### Fundos Imobiliários (FIIs)
- `/fiis` — Painel principal com a cotação dos 20 principais FIIs do mercado brasileiro.
- `/fiis/[ticker]` — Página de detalhes de um FII individual (ex: `/fiis/hglg11`). Contém:
  - Valor patrimonial da cota e patrimônio líquido total.
  - Indicadores específicos: P/VP, Dividend Yield (último mês, 12 meses e CAGR 3/5 anos).
  - Vacância física e financeira, quantidade de ativos do fundo.
  - Histórico de rendimentos/dividendos distribuídos.

### Rankings da Bolsa
- `/rankings` — Painel geral de rankings dinâmicos de ativos da B3. Suporta os query parameters:
  - `tipo` (`acao`, `fii`, `bdr`, `etf` ou `todos` para listar a categoria desejada).
  - `setor` (filtrar ações por setor específico da B3).
  - Rankings disponibilizados em abas de 10 posições:
    - **Maiores Altas**: Ativos com maior valorização percentual no dia.
    - **Maiores Baixas**: Ativos com maior desvalorização percentual no dia.
    - **Maior Volume**: Ativos com maior volume financeiro transacionado hoje.
    - **Maior Valor de Mercado**: Ativos de maior valor patrimonial de mercado (market cap).

### Câmbio e Moedas
- `/dolar-hoje` — Cotação comercial do Dólar americano frente ao Real (USD-BRL) em tempo real, com conversor de moedas integrado.
- `/euro-hoje` — Cotação do Euro frente ao Real (EUR-BRL).
- `/dolar/index` — Página descritiva abrangente sobre as variações históricas da moeda americana.

### Renda Fixa e Macroeconomia
- `/tesouro-direto` — Listagem de todos os títulos do Tesouro Direto ativos, incluindo:
  - Taxas de rendimento anual (ex: IPCA + 6%, Selic + 0.1%).
  - Preços mínimos de investimento.
  - Preços de resgate.
  - Exibição de indicadores macroeconômicos oficiais (SELIC atual e inflação acumulada IPCA 12m).

### Calculadoras de Investimento
- `/calculadoras` — Hub centralizador das ferramentas de simulação.
- `/calculadoras/juros-compostos` — Simulador de evolução patrimonial com base em aportes mensais, taxa de juros e prazo.
- `/calculadoras/preco-teto` — Cálculo de preço teto de ações utilizando o modelo de dividendos de Décio Bazin (exige Dividend Yield desejado).
- `/calculadoras/independencia-financeira` — Cálculo de prazo/aportes necessários para viver de renda passiva na aposentadoria.
- `/calculadoras/rendimento/[ticker]` — Simulador que calcula o rendimento histórico real que o investidor teria obtido se tivesse comprado determinado ativo no passado (ex: `/calculadoras/rendimento/petr4`).

---

## 2. APIs do Sistema (Endpoints Internos)

O portal disponibiliza alguns endpoints de proxy/API para carregamento de dados em tempo real no client-side:

- `GET /api/search?q=[termo]` — Retorna até 5 ativos correspondentes ao termo digitado no autocomplete da barra de busca. Formato: `[{ "stock": "PETR4", "name": "Petrobras", "close": 38.5, ... }]`.
- `GET /api/quotes?tickers=PETR4,VALE3` — Proxy para cotações batch da BRAPI.
- `GET /api/cripto?coins=BTC,ETH` — Proxy para preços de criptomoedas.
- `GET /api/moedas?pairs=USD-BRL` — Proxy para taxas de câmbio atuais.

---

## 3. Formato de Dados de Mercado

Os dados do site utilizam a biblioteca interna `format` com as seguintes convenções de exibição:
- **Moeda**: R$ no padrão brasileiro (`pt-BR`), ex: `R$ 1.250,50` ou `US$ 65.300,00`.
- **Porcentagem**: Duas casas decimais com vírgula e símbolo `%`, ex: `1,25%` ou `-0,48%`.
- **Formatos Compactos**: Valores em milhões, bilhões ou trilhões são compactados para maior legibilidade, ex: `2,14 B` (Bilhões), `557,86 M` (Milhões), `1,10 T` (Trilhões).