Documentação da API REST

# Cotações Hoje API — Catálogo e Especificação de Endpoints

> **Guia de Referência para Desenvolvedores e Agentes de IA (LLMs)**  
> Este documento contém a especificação completa de todos os endpoints REST (API v1) e rotas da plataforma **Cotações Hoje API**. Desenvolvido em formato otimizado para ser injetado em prompts de contexto para LLMs e agentes autônomos.

---

## 1. Visão Geral e Autenticação

- **Base URL Oficial:** `https://api.cotacoeshoje.com`
- **Prefixo da API REST:** `/v1`
- **Formato dos Dados:** `application/json` (UTF-8)

### Mecanismo de Autenticação da API REST (`/v1/*`)
Todas as rotas sob o prefixo `/v1` requerem autenticação por chave de API (`APIKey`), exceto quando indicado.

A chave pode ser enviada de duas formas:
1. **Header HTTP (Recomendado):** `X-API-Key: ch_live_suachaveaqui`
2. **Query Parameter:** `?api_key=ch_live_suachaveaqui`

### Rate Limiting e Headers de Resposta
O controle de taxa de requisições (*rate limit*) é gerido dinamicamente com base no plano ativo do usuário (`Free`, `Pro`, `Enterprise`):
- `X-RateLimit-Limit`: Limite mensal total de requisições do plano.
- `X-RateLimit-Remaining`: Requisições restantes no ciclo mensal atual.
- `X-RateLimit-Reset`: Timestamp Unix indicando quando o ciclo será reiniciado.

Em caso de excesso de limite, a API retorna HTTP `429 Too Many Requests`:
```json
{
  "status": "rate_limit_exceeded",
  "message": "Limite de requisições excedido para o seu plano.",
  "limit": 1000,
  "reset_at": 1735689600
}
```

### Alta Disponibilidade e Baixa Latência
A infraestrutura da **Cotações Hoje API** foi projetada para garantir máxima confiabilidade e performance aos desenvolvedores:
- **Respostas Ultrarrápidas:** Consultas com latência típica inferior a 50ms para cotações e séries consolidadas.
- **Tolerância a Falhas:** Camadas redundantes e resilientes asseguram disponibilidade contínua (99.9% de uptime), mantendo a integridade das respostas mesmo sob cenários de alta volatilidade no mercado.
- **Consistência:** Dados sincronizados e atualizados em tempo real durante o pregão da B3 e sessões globais.

---

## 2. Tabela Resumo dos Endpoints REST (`/v1`)

| Método | Endpoint | Tags | Descrição Resumida |
| :--- | :--- | :--- | :--- |
| `GET` | `/v1/list` | quotes | Lista completa de ativos negociados na B3. |
| `GET` | `/v1/quote/{tickers}` | quotes | Cotações em tempo real de ativos B3 (ações, FIIs, BDRs, ETFs). |
| `GET` | `/v1/asset/{ticker}` | quotes | Detalhes cadastrais, perfil, indicadores fundamentalistas e dividendos. |
| `GET` | `/v1/search?q={termo}` | quotes | Busca incremental de ativos por código ou nome. |
| `GET` | `/v1/asset/{ticker}/history` | quotes | Histórico de cotações e candles (aliases: `/history/{ticker}`, `/quotes/{ticker}/history`). |
| `GET` | `/v1/assets/{ticker}/logo` | quotes | Logotipo oficial do ativo da B3 com cache local em disco (alias: `/asset/{ticker}/logo`). |
| `GET` | `/v1/dividends/{ticker}` | dividends | Histórico detalhado de dividendos e JCP de um ativo. |
| `GET` | `/v1/dividends/calendar` | dividends | Calendário de dividendos com datas COM e pagamentos do mês. |
| `GET` | `/v1/crypto` | crypto | Cotações de criptomoedas em BRL ou USD (alias: `/criptomoedas`). |
| `GET` | `/v1/crypto/{coin}/logo` | crypto | Logotipo oficial da criptomoeda com cache local em disco (alias: `/cripto/{coin}/logo`). |
| `GET` | `/v1/crypto/list` | crypto | Lista de todas as criptomoedas suportadas. |
| `GET` | `/v1/crypto/{coin}/history` | crypto | Série histórica de preços de uma criptomoeda. |
| `GET` | `/v1/currency/available` | currency | Catálogo de moedas e pares cambiais suportados (aliases: `/v1/currency/avaiable`, `/v1/currency/list`). |
| `GET` | `/v1/currency/{pairs}` | currency | Cotação de pares de moedas (ex: `USD-BRL,EUR-BRL`). |
| `GET` | `/v1/currency/convert` | currency | Conversão monetária em tempo real entre moedas. |
| `GET` | `/v1/currency/{pair}/history` | currency | Histórico de taxas de câmbio de um par de moedas. |
| `GET` | `/v1/treasury` | treasury | Lista de títulos do Tesouro Direto com preços e taxas (alias: `/tesouro`). |
| `GET` | `/v1/treasury/{symbol}` | treasury | Detalhes, taxas vigentes e simulação de título público (alias: `/tesouro/{symbol}`). |
| `GET` | `/v1/treasury/indicators` | treasury | Indicadores e taxas atuais de títulos do Tesouro Direto (alias: `/tesouro/indicators`). |
| `GET` | `/v1/treasury/{symbol}/history` | treasury | Histórico de taxas e preços de título público (alias: `/tesouro/{symbol}/history`). |
| `GET` | `/v1/macro` | macro | Indicadores macroeconômicos (Selic, IPCA, CDI, Câmbio). |
| `GET` | `/v1/macro/latest` | macro | Valores mais recentes de séries macro (Selic, CDI, IPCA, TR, IGPM). |
| `GET` | `/v1/macro/{symbols}` | macro | Série histórica de indicadores macroeconômicos. |
| `GET` | `/v1/funds/list` | funds | Listagem de fundos de investimento (FIAGRO, FI-Infra, FIDC, FIPs). |
| `GET` | `/v1/funds/portfolio/{symbols}` | funds | Portfólio completo de fundos de investimento. |
| `GET` | `/v1/funds/indicators` | funds | Indicadores CVM consolidados de fundos (NAV, P/VP, patrimônio líquido). |
| `GET` | `/v1/fii/properties/{symbols}` | fii | Propriedades físicas, ABL e vacância de fundos imobiliários. |
| `GET` | `/v1/fii/portfolio/{symbols}` | fii | Portfólio detalhado de ativos financeiros de FIIs. |
| `GET` | `/v1/fii/reports/{symbols}` | fii | Informes mensais CVM de FIIs (patrimônio, cotistas, etc). |
| `GET` | `/v1/fii/indicators/{symbols}` | fii | Indicadores consolidados de FIIs (NAV, P/VP, cotistas, DY). |
| `GET` | `/v1/options/{underlying}` | options | Opções e derivativos B3 (Calls, Puts, Gregas, Volatilidade). |
| `GET` | `/v1/tickers/resolve/{symbols}` | tickers | Resolução e normalização de tickers antigos/renomeados da B3. |
| `GET` | `/v1/dictionary` | dictionary | Dicionário da API com explicações e fórmulas de indicadores. |
| `GET` | `/v1/market/summary` | market | Panorama geral de mercado: IBOV, maiores altas, maiores baixas e câmbio. |
| `GET` | `/v1/indices/{slug}/composition`| market | Carteira teórica e peso de composição de índices B3 (ex: `ibovespa`, `ifix`). |
| `GET` | `/v1/screener` | screener | Filtros fundamentalistas avançados (P/L, P/VP, DY, Liquidez). Requer plano Pro+. |
| `GET` | `/health` | system | Health check do serviço e status da aplicação (sem auth). |

---

## 3. Especificação Detalhada dos Endpoints REST

### 3.1. Cotações e Ativos B3 (`quotes`)

#### `GET /v1/quote/{tickers}` (ou `/v1/quotes/{tickers}`, `/v1/quotes?tickers=...`)
Retorna cotações de um ou mais ativos listados na B3.
- **Path Params:**
  - `tickers` (string, obrigatório): Lista de tickers separados por vírgula. Ex: `PETR4,VALE3,ITUB4,HGLG11,IVVB11`.
- **Query Params:**
  - `range` (string, opcional, default: `1d`): Intervalo histórico (`1d`, `5d`, `1mo`, `1y`).
  - `interval` (string, opcional, default: `1d`): Periodicidade (`1d`, `1wk`, `1mo`).
  - `fundamental` (bool, opcional, default: `false`): Inclui dados de balanço e demonstrações contábeis.
  - `dividends` (bool, opcional, default: `false`): Inclui histórico completo de proventos.
  - `modules` (string, opcional): Módulos adicionais separados por vírgula (ex: `summaryProfile,balanceSheetHistory,financialData`).
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "results": [
    {
      "symbol": "PETR4",
      "shortName": "PETROBRAS PN",
      "currency": "BRL",
      "regularMarketPrice": 38.45,
      "regularMarketDayHigh": 38.90,
      "regularMarketDayLow": 37.80,
      "regularMarketChange": 0.65,
      "regularMarketChangePercent": 1.72,
      "regularMarketVolume": 45200000,
      "logourl": "https://api.cotacoeshoje.com/v1/assets/PETR4/logo"
    }
  ]
}
```

#### `GET /v1/asset/{ticker}`
Retorna dados cadastrais profundos, perfil da empresa, estatísticas financeiras e indicadores fundamentalistas.
- **Path Params:**
  - `ticker` (string, obrigatório): Símbolo do ativo. Ex: `VALE3`.
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "asset": {
    "symbol": "VALE3",
    "longName": "Vale S.A.",
    "summaryProfile": {
      "sector": "Materiais Básicos",
      "industry": "Mineração",
      "website": "https://vale.com"
    },
    "defaultKeyStatistics": {
      "enterpriseValue": 250000000000,
      "forwardPE": 5.4,
      "priceToBook": 1.15
    },
    "dividendsData": { ... }
  }
}
```

#### `GET /v1/search`
Busca incremental de ativos disponíveis na B3 por ticker ou razão social.
- **Query Params:**
  - `q` (string, obrigatório, min_length=1): Termo pesquisado. Ex: `petro` ou `VALE`.
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "query": "petro",
  "total": 2,
  "results": [
    {
      "symbol": "PETR4",
      "name": "PETROBRAS PN",
      "type": "stock",
      "close": 38.45,
      "change": 1.72,
      "volume": 45200000,
      "market_cap": 500000000000,
      "logo": "https://..."
    }
  ]
}
```

#### `GET /v1/asset/{ticker}/history`
*(Aliases disponíveis: `/v1/history/{ticker}`, `/v1/quotes/{ticker}/history`)*  
Retorna a série histórica de preços, candles e volume do ativo.
- **Path Params:**
  - `ticker` (string, obrigatório): Ex: `ITUB4`.
- **Query Params:**
  - `range` (string, opcional, default: `1y`): `1d`, `5d`, `1mo`, `3mo`, `6mo`, `1y`, `2y`, `5y`, `max`.
  - `interval` (string, opcional, default: `1d`): `1d`, `1wk`, `1mo`.
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "ticker": "ITUB4",
  "range": "1y",
  "interval": "1d",
  "history": [
    {
      "date": 1704067200,
      "open": 33.20,
      "high": 33.80,
      "low": 33.10,
      "close": 33.65,
      "volume": 18200000
    }
  ]
}
```

#### `GET /v1/list`
Lista completa de todos os ativos (ações, FIIs, BDRs, ETFs) negociados na B3.
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "total": 450,
  "results": [
    {
      "symbol": "PETR4",
      "name": "PETROBRAS PN",
      "type": "stock"
    }
  ]
}
```

#### `GET /v1/assets/{ticker}/logo`
*(Alias disponível: `/v1/asset/{ticker}/logo`)*  
Retorna o logotipo oficial do ativo da B3 (Ação, FII, BDR ou ETF) com cabeçalhos de cache agressivo (`Cache-Control: public, max-age=2592000, immutable`). Em caso de ativo sem logotipo cadastrado, entrega automaticamente um avatar vetorial SVG elegante com as iniciais do ticker.
- **Path Params:**
  - `ticker` (string, obrigatório): Símbolo do ativo (ex: `PETR4`, `VALE3`, `HGLG11`).
- **Resposta Sucesso (200):**
  - Retorna o arquivo binário da imagem (`image/png`, `image/svg+xml`, `image/webp`).

---

### 3.2. Proventos e Dividendos (`dividends`)

#### `GET /v1/dividends/{ticker}`
Retorna todo o histórico de proventos (dividendos, JCP, rendimentos) pagos ou anunciados por um ativo.
- **Path Params:**
  - `ticker` (string, obrigatório): Ex: `BBAS3`.
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "ticker": "BBAS3",
  "dividends": [
    {
      "assetIssued": "BBAS3",
      "paymentDate": "2024-03-15T00:00:00.000Z",
      "rate": 0.4102,
      "relatedTo": "JCP",
      "approvedOn": "2024-02-08T00:00:00.000Z",
      "lastDatePrior": "2024-02-21T00:00:00.000Z"
    }
  ]
}
```

#### `GET /v1/dividends/calendar`
Retorna os eventos da agenda de proventos da B3 (datas COM e datas de pagamento).
- **Query Params:**
  - `year` (int, opcional): Ano de referência (ex: `2024`). Padrão: ano corrente.
  - `month` (int, opcional): Mês de referência (`1-12`). Padrão: mês corrente.
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "year": 2024,
  "month": 10,
  "events": [
    {
      "ticker": "PETR4",
      "type": "Dividendo",
      "value": 1.253,
      "date_com": "2024-10-15",
      "payment_date": "2024-11-20"
    }
  ]
}
```

---

### 3.3. Criptomoedas (`crypto`)

#### `GET /v1/crypto`
*(Alias disponível: `/v1/criptomoedas`)*  
Cotação instantânea de criptomoedas em moeda fiduciária.
- **Query Params:**
  - `coins` (string, opcional, default: `BTC,ETH,SOL,BNB`): Criptomoedas separadas por vírgula.
  - `currency` (string, opcional, default: `BRL`): Moeda base (`BRL` ou `USD`).
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "coins": [
    {
      "coin": "BTC",
      "currency": "BRL",
      "regularMarketPrice": 350000.0,
      "regularMarketChangePercent": 2.45,
      "regularMarketDayHigh": 355000.0,
      "regularMarketDayLow": 348000.0,
      "marketCap": 6800000000000
    }
  ]
}
```

#### `GET /v1/crypto/{coin}/logo`
*(Alias disponível: `/v1/cripto/{coin}/logo`)*  
Retorna o logotipo oficial da criptomoeda com cabeçalhos de cache agressivo (`Cache-Control: public, max-age=2592000, immutable`). Em caso de moeda sem logotipo cadastrado, entrega automaticamente um avatar vetorial SVG dinâmico com o símbolo da moeda.
- **Path Params:**
  - `coin` (string, obrigatório): Código da criptomoeda (ex: `BTC`, `ETH`, `SOL`).
- **Resposta Sucesso (200):**
  - Retorna o arquivo binário da imagem (`image/png`, `image/svg+xml`, `image/webp`).

#### `GET /v1/crypto/list`
Lista todas as moedas e tokens cripto disponíveis para consulta na plataforma.
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "coins": [
    {"coin": "BTC", "name": "Bitcoin"},
    {"coin": "ETH", "name": "Ethereum"},
    {"coin": "SOL", "name": "Solana"}
  ]
}
```

#### `GET /v1/crypto/{coin}/history`
Série histórica de preços de uma criptomoeda.
- **Path Params:**
  - `coin` (string, obrigatório): Código da criptomoeda. Ex: `BTC`, `ETH`.
- **Query Params:**
  - `range` (string, opcional, default: `1y`): `1d`, `5d`, `1mo`, `1y`, `2y`.
  - `currency` (string, opcional, default: `BRL`): `BRL` ou `USD`.
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "coin": "BTC",
  "currency": "BRL",
  "range": "1y",
  "data": {
    "historicalDataPrice": [ ... ]
  }
}
```

---

### 3.4. Câmbio e Conversão de Moedas (`currency`)

#### `GET /v1/currency/available`
Catálogo de moedas e pares de câmbio disponíveis no sistema para consulta e conversão monetária.
- **Aliases:** `/v1/currency/avaiable`, `/v1/currency/list`
- **Headers:** `X-API-Key: ch_live_...`
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "total": 540,
  "currencies": [
    {
      "name": "USD-BRL",
      "currency": "Dólar Americano/Real Brasileiro"
    },
    {
      "name": "EUR-BRL",
      "currency": "Euro/Real Brasileiro"
    },
    {
      "name": "GBP-BRL",
      "currency": "Libra Esterlina/Real Brasileiro"
    }
  ]
}
```

#### `GET /v1/currency/{pairs}`
Cotações em tempo real de taxas de câmbio.
- **Path Params:**
  - `pairs` (string, obrigatório): Pares separados por vírgula. Ex: `USD-BRL,EUR-BRL,GBP-BRL,BTC-BRL`.
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "currency": [
    {
      "fromCurrency": "USD",
      "toCurrency": "BRL",
      "name": "Dólar Americano/Real Brasileiro",
      "bidPrice": 5.4215,
      "askPrice": 5.4230,
      "updatedAtTimestamp": 1728392400
    }
  ]
}
```

#### `GET /v1/currency/convert`
Calculadora de conversão de câmbio instantânea com base no mercado atual.
- **Query Params:**
  - `from` (string, opcional, default: `USD`): Moeda de origem.
  - `to` (string, opcional, default: `BRL`): Moeda de destino.
  - `amount` (float, opcional, default: `1.0`, gt=0): Montante a ser convertido.
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "from_currency": "USD",
  "to_currency": "BRL",
  "amount": 100.0,
  "rate": 5.4215,
  "converted_amount": 542.15
}
```

#### `GET /v1/currency/{pair}/history`
Histórico de taxas de câmbio de um par específico (ex: `EUR-BRL`, `USD-BRL`, `GBP-BRL`, `BTC-BRL`).
- **Path Params:**
  - `pair` (string, obrigatório): Par de moedas. Suporta formatos `EUR-BRL`, `EUR/BRL`, `EURBRL=X`, `EUR` (converte para BRL por padrão) ou cripto como `BTC-BRL`.
- **Query Params:**
  - `range` (string, opcional, default: `1y`): Intervalo textual (`1d`, `5d`, `1mo`, `3mo`, `6mo`, `1y`, `5y`).
  - `days` (int, opcional): Número de dias de histórico (ex: `30`, `90`, `365`). Se fornecido, possui precedência sobre `range`.
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "pair": "EUR-BRL",
  "from_currency": "EUR",
  "to_currency": "BRL",
  "range": "1y",
  "days": 365,
  "history": [
    {
      "date": 1700000000,
      "close": 6.1234,
      "adjustedClose": 6.1234,
      "high": 6.1520,
      "low": 6.0980
    }
  ],
  "results": [
    {
      "symbol": "EUR-BRL",
      "historicalDataPrice": [ ... ]
    }
  ],
  "currency": [
    {
      "symbol": "EUR-BRL",
      "historicalDataPrice": [ ... ]
    }
  ]
}
```

---

### 3.5. Renda Fixa e Tesouro Direto (`treasury`)

#### `GET /v1/treasury`
*(Alias disponível: `/v1/tesouro`)*  
Lista completa de títulos públicos do Tesouro Direto (Prefixados, Selic, IPCA+, RendA+, Educa+), contendo taxas de rendimento anual (%) e preços unitários de compra/resgate.
- **Query Params:**
  - `indexer` (string, opcional): Filtrar por indexador (`selic`, `prefixado`, `ipca`, `igpm`).
  - `coupon_type` (string, opcional): Filtrar por cupom (`semestral`, `none`).
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "treasury": [
    {
      "symbol": "tesouro-selic-01032029",
      "bondType": "Tesouro Selic",
      "indexer": "selic",
      "maturityDate": "2029-03-01",
      "buyRate": 0.05,
      "sellRate": 0.00,
      "buyPrice": 14500.20,
      "sellPrice": 14500.20
    }
  ],
  "results": [
    {
      "symbol": "tesouro-selic-01032029",
      "bondType": "Tesouro Selic",
      "indexer": "selic",
      "maturityDate": "2029-03-01",
      "buyRate": 0.05,
      "sellRate": 0.00,
      "buyPrice": 14500.20,
      "sellPrice": 14500.20
    }
  ]
}
```

#### `GET /v1/treasury/indicators`
*(Alias disponível: `/v1/tesouro/indicators`)*  
Recupera os indicadores, taxas vigentes e dados consolidados de um ou mais títulos públicos.
- **Query Params:**
  - `symbols` (string, obrigatório): Símbolo ou lista de símbolos separados por vírgula (ex: `tesouro-ipca-15082032`).
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "results": [
    {
      "symbol": "tesouro-ipca-15082032",
      "bondType": "Tesouro IPCA+",
      "indexer": "ipca",
      "maturityDate": "2032-08-15",
      "buyRate": 6.82,
      "buyPrice": 3350.25,
      "simulation": {
        "effective_rate": 11.33,
        "effective_rate_formatted": "11,33%",
        "tiers": [
          {
            "amount": 1000.0,
            "amount_formatted": "R$ 1.000,00",
            "net_gain": 93.47,
            "net_amount": 1093.47,
            "net_amount_formatted": "R$ 1.093,47"
          }
        ]
      }
    }
  ],
  "treasury": [ ... ]
}
```

#### `GET /v1/treasury/{symbol}`
*(Alias disponível: `/v1/tesouro/{symbol}`)*  
Recupera os detalhes completos, taxas de compra e venda e tabela de projeção de rendimento com alíquotas regressivas de IR para um título específico.
- **Path Params:**
  - `symbol` (string, obrigatório): Símbolo do título (ex: `tesouro-ipca-15082032` ou `tesouro ipca 15082032`).
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "symbol": "tesouro-ipca-15082032",
  "item": {
    "symbol": "tesouro-ipca-15082032",
    "bondType": "Tesouro IPCA+",
    "indexer": "ipca",
    "maturityDate": "2032-08-15",
    "buyRate": 6.82,
    "sellRate": 6.94,
    "buyPrice": 3350.25,
    "sellPrice": 3326.85,
    "simulation": {
      "effective_rate": 11.33,
      "effective_rate_formatted": "11,33%",
      "tiers": [ ... ]
    }
  },
  "results": [ ... ],
  "treasury": [ ... ]
}
```

#### `GET /v1/treasury/{symbol}/history`
*(Alias disponível: `/v1/tesouro/{symbol}/history`)*  
Histórico de flutuação de taxas e PU (Preço Unitário) de um título do Tesouro Direto para análise de marcação a mercado.
- **Path Params:**
  - `symbol` (string, obrigatório): Identificador ou nome do título (ex: `tesouro-ipca-15082032`).
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "symbol": "tesouro-ipca-15082032",
  "history": [
    {
      "baseDate": "2026-10-06",
      "buyRate": 6.80,
      "buyPrice": 3345.10
    },
    {
      "baseDate": "2026-10-07",
      "buyRate": 6.82,
      "buyPrice": 3350.25
    }
  ],
  "results": [
    {
      "symbol": "tesouro-ipca-15082032",
      "bondType": "Tesouro IPCA+",
      "indexer": "ipca",
      "buyRate": 6.82,
      "buyPrice": 3350.25,
      "history": [ ... ]
    }
  ]
}
```

---

### 3.6. Indicadores Macroeconômicos (`macro`)

#### `GET /v1/macro`
Visão consolidada dos principais balizadores macroeconômicos do Brasil.
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "prime_rate_selic": {
    "value": "10.75",
    "date": "2024-09-18"
  },
  "inflation_ipca": {
    "value": "4.12",
    "date": "2024-09-01"
  },
  "currencies": [
    {
      "fromCurrency": "USD",
      "toCurrency": "BRL",
      "bidPrice": 5.42
    }
  ]
}
```

#### `GET /v1/macro/latest` (ou `/v1/macro/latest/{symbols}`)
Retorna os valores mais recentes das principais séries macroeconômicas (Selic, Selic Overnight, CDI, IPCA, IPCA 12m, IGP-M, TR).
- **Path / Query Params:**
  - `symbols` (string, opcional): Símbolos macro separados por vírgula (ex: `selic,cdi,ipca,igpm,tr`).
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "results": [
    {
      "series": {
        "slug": "selic",
        "name": "Taxa Selic Meta",
        "unit": "% a.a."
      },
      "latest": {
        "value": 10.75,
        "date": "2024-09-18"
      }
    },
    {
      "series": {
        "slug": "cdi",
        "name": "Taxa CDI",
        "unit": "% a.a."
      },
      "latest": {
        "value": 10.65,
        "date": "2024-09-18"
      }
    }
  ]
}
```

#### `GET /v1/macro/{symbols}`
Série histórica de indicadores macroeconômicos.
- **Path Params:**
  - `symbols` (string, obrigatório): Símbolos separados por vírgula (ex: `selic`, `cdi`, `ipca`).
- **Query Params:**
  - `start_date` (string, opcional): Data de início nos formatos `YYYY-MM-DD` ou `DD/MM/YYYY`.
  - `end_date` (string, opcional): Data de fim nos formatos `YYYY-MM-DD` ou `DD/MM/YYYY`.
  - `limit` (int, opcional, padrão: `500` para séries diárias como `selic` e `cdi`): Limite de observações retornadas (1 a 1000).
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "results": [
    {
      "date": "2024-09-18",
      "value": 10.75
    }
  ]
}
```

---

### 3.7. Fundos de Investimento (`funds`)

#### `GET /v1/funds/list`
Listagem de fundos de investimento (FIAGRO, FI-Infra, FIDC, FIPs).
- **Query Params:**
  - `symbols` (string, opcional): Filtra por símbolos.
  - `search` (string, opcional): Busca por nome.
  - `page` (int, opcional, default: `1`): Página da paginação.
  - `limit` (int, opcional, default: `50`): Quantidade de registros por página.
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "results": [
    {
      "symbol": "XPCA11",
      "name": "XP CREDITO AGRICOLA FIAGRO",
      "segment": "FIAGRO"
    }
  ]
}
```

#### `GET /v1/funds/portfolio/{symbols}`
Portfólio de fundos de investimento detalhando debêntures, CRIs, LCIs, etc.
- **Path Params:**
  - `symbols` (string, obrigatório): Símbolos separados por vírgula.
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "portfolio": [
    {
      "holding": "Debênture XPTO",
      "percentage": 5.4
    }
  ]
}
```

#### `GET /v1/funds/indicators` (ou `/v1/funds/indicators/{symbols}`)
Retorna indicadores CVM consolidados de fundos de investimento (NAV, P/VP, patrimônio líquido, cotistas).
- **Path Params:**
  - `symbols` (string, opcional): Tickers dos fundos separados por vírgula (ex: `XPCA11,VGIA11`).
- **Query Params:**
  - `cnpjs` (string, opcional): Filtra por CNPJs separados por vírgula.
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "results": [
    {
      "symbol": "XPCA11",
      "navPerShare": 9.5,
      "equity": 540000000,
      "pvp": 0.98
    }
  ]
}
```

---

### 3.8. Fundo de Investimento Imobiliário - FII (`fii`)

#### `GET /v1/fii/properties/{symbols}`
Propriedades físicas, ABL (Área Bruta Locável) e vacância de fundos imobiliários.
- **Path Params:**
  - `symbols` (string, obrigatório): Símbolos dos FIIs separados por vírgula.
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "properties": [
    {
      "name": "Galpão Cajamar",
      "area": 50000,
      "vacancy_percent": 2.5
    }
  ]
}
```

#### `GET /v1/fii/portfolio/{symbols}`
Portfólio financeiro de FIIs detalhando CRIs, cotas de outros fundos, LCI, etc.
- **Path Params:**
  - `symbols` (string, obrigatório): Símbolos separados por vírgula.
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "portfolio": [
    {
      "asset": "CRI HGLG",
      "percentage": 10.5
    }
  ]
}
```

#### `GET /v1/fii/reports/{symbols}`
Retorna os Informes Mensais CVM de Fundos Imobiliários (patrimônio líquido, passivos, cotistas, etc).
- **Path Params:**
  - `symbols` (string, obrigatório): Tickers dos FIIs separados por vírgula (ex: `HGLG11,KNIP11`).
- **Query Params:**
  - `start_date` (string, opcional): Data inicial de referência (`YYYY-MM-DD`).
  - `end_date` (string, opcional): Data final de referência (`YYYY-MM-DD`).
  - `sort_by` (string, opcional, default: `referenceDate`): Campo de ordenação.
  - `sort_order` (string, opcional, default: `desc`): Ordem `asc` ou `desc`.
  - `page` (int, opcional, default: `1`): Número da página.
  - `limit` (int, opcional, default: `12`): Quantidade de relatórios retornados.
  - `all_versions` (bool, opcional): Incluir todas as versões dos informes.
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "reports": [
    {
      "symbol": "HGLG11",
      "referenceDate": "2026-01-31",
      "equity": 5200000000,
      "shareholders": 380000
    }
  ],
  "total": 1
}
```

#### `GET /v1/fii/indicators/{symbols}`
Retorna indicadores fundamentalistas consolidados de Fundos Imobiliários (Preço, NAV/Cota, P/VP, Patrimônio Líquido, Cotistas e Dividend Yield).
- **Path Params:**
  - `symbols` (string, obrigatório): Tickers dos FIIs separados por vírgula (ex: `HGLG11,XPLG11`).
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "fiis": [
    {
      "symbol": "HGLG11",
      "price": 160.50,
      "navPerShare": 155.00,
      "priceToNav": 1.035,
      "equity": 5200000000,
      "totalInvestors": 380000,
      "dividendYield12m": 0.082
    }
  ],
  "results": [ ... ]
}
```

---

### 3.9. Dicionário da API (`dictionary`)

#### `GET /v1/dictionary`
Retorna as explicações e fórmulas dos indicadores financeiros utilizados na API.
- **Query Params:**
  - `search` (string, opcional): Termo de busca textual.
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "dictionary": [
    {
      "term": "P/L",
      "name": "Preço sobre Lucro",
      "description": "Indica quantos anos seriam necessários para reaver o capital investido...",
      "formula": "Preço Atual / Lucro por Ação (LPA)"
    }
  ]
}
```
---

### 3.7. Panorama de Mercado e Índices B3 (`market`)

#### `GET /v1/market/summary`
Snapshot completo do mercado financeiro em tempo real para dashboards e relatórios.
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "ibovespa": {
    "symbol": "^BVSP",
    "regularMarketPrice": 131500.0,
    "regularMarketChangePercent": 0.85
  },
  "gainers": [
    {"symbol": "MGLU3", "change": 5.82, "close": 9.45}
  ],
  "losers": [
    {"symbol": "AZUL4", "change": -4.10, "close": 7.20}
  ],
  "currencies": [ ... ]
}
```

#### `GET /v1/indices/{slug}/composition`
Retorna a carteira teórica e os pesos de ponderação dos ativos nos índices oficiais da B3.
- **Path Params:**
  - `slug` (string, obrigatório): Código do índice em minúsculas (ex: `ibovespa`, `ifix`).
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "composition": {
    "index": "IBOVESPA",
    "total_weight": 100.0,
    "assets": [
      {"ticker": "VALE3", "name": "VALE ON", "weight_percent": 11.25},
      {"ticker": "PETR4", "name": "PETROBRAS PN", "weight_percent": 8.40}
    ]
  }
}
```

---

### 3.8. Screener Fundamentalista Avançado (`screener`)

#### `GET /v1/screener`
Executa filtragem multidimensional sobre ações e fundos imobiliários (FIIs) listados na B3.  
*(Requer plano com permissão `has_screener=True` habilitada — caso contrário retorna HTTP 403 Forbidden)*.
- **Query Params:**
  - `asset_type` (string, opcional, default: `stocks`): Tipo de ativo: `stocks` ou `fiis`.
  - `min_dy` (float, opcional): Dividend Yield mínimo acumulado em % (ex: `6.0`).
  - `max_pl` (float, opcional): P/L (Preço / Lucro) máximo (ex: `15.0`).
  - `min_pvp` (float, opcional): P/VP (Preço / Valor Patrimonial) mínimo (ex: `0.5`).
  - `max_pvp` (float, opcional): P/VP máximo (ex: `1.5`).
  - `min_liquidity` (float, opcional): Liquidez média diária mínima em R$ (ex: `1000000`).
  - `limit` (int, opcional, default: `50`, min: 1, max: 200): Número máximo de ativos retornados.
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "asset_type": "stocks",
  "total": 12,
  "results": [
    {
      "ticker": "BBAS3",
      "name": "BANCO DO BRASIL ON",
      "price": 27.80,
      "dividend_yield": 9.85,
      "pl": 4.15,
      "pvp": 0.82,
      "volume_diario": 35000000
    }
  ]
}
```

---

### 3.10. Opções e Derivativos B3 (`options`)

#### `GET /v1/options/{underlying}` (ou `/v1/options/analytics/{underlying}`)
Retorna a cadeia de opções e derivativos (Calls, Puts, Gregas, Volatilidade Implícita e Preço Spot) de um ativo negociado na B3.
- **Path Params:**
  - `underlying` (string, obrigatório): Ticker do ativo base na B3 (ex: `PETR4`, `VALE3`).
- **Query Params:**
  - `expiration` (string, opcional): Filtra por data de vencimento específica (`YYYY-MM-DD`).
  - `side` (string, opcional): Tipo da opção: `call` ou `put`.
  - `min_strike` (float, opcional): Strike mínimo para filtragem.
  - `max_strike` (float, opcional): Strike máximo para filtragem.
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "underlying": "PETR4",
  "spotPrice": 38.50,
  "options": [
    {
      "symbol": "PETRD385",
      "strike": 38.50,
      "type": "CALL",
      "expiration": "2026-04-17",
      "impliedVolatility": 24.5
    }
  ]
}
```

---

### 3.11. Resolução e Normalização de Tickers (`tickers`)

#### `GET /v1/tickers/resolve/{symbols}` (ou `/v1/tickers/resolve?symbols=...`)
Resolve e normaliza tickers antigos ou renomeados para o símbolo canônico atual da B3 (ex: VVAR3 -> BHIA3).
- **Path / Query Params:**
  - `symbols` (string, obrigatório): Tickers a resolver separados por vírgula (ex: `VVAR3,PCAR4`).
- **Resposta Sucesso (200):**
```json
{
  "status": "success",
  "results": [
    {
      "symbol": "BHIA3",
      "previousSymbol": "VVAR3",
      "changed": true
    }
  ]
}
```

---

### 3.12. Monitoramento de Sistema (`system`)

#### `GET /health`
Verificação de integridade e liveness da aplicação. Não requer autenticação.
- **Resposta Sucesso (200):**
```json
{
  "status": "healthy",
  "timestamp": "2026-10-08T13:10:00.000000+00:00",
  "app": "cotacoes-hoje-api"
}
```

---

## 4. Recursos para Desenvolvedores e Gestão de Chaves

- **Painel do Desenvolvedor:** Acesse `https://api.cotacoeshoje.com/dashboard` para acompanhar métricas de consumo em tempo real, limites do plano e cotas restantes.
- **Gerenciamento de API Keys:** Crie ou revogue suas chaves `ch_live_*` diretamente no painel em `https://api.cotacoeshoje.com/dashboard/keys`.
- **Documentação Interativa:** Acesse `https://api.cotacoeshoje.com/api-docs` para testar chamadas diretamente pelo navegador.
- **Planos e Preços:** Conheça os planos e consulte limites em `https://api.cotacoeshoje.com/pricing`.
- **Status do Serviço:** Monitore a disponibilidade da API via `GET https://api.cotacoeshoje.com/health`.

---

## 5. Exemplos Práticos de Integração (cURL & Python)

### cURL
```bash
# Consultar cotação em tempo real de ativos na B3
curl -X GET "https://api.cotacoeshoje.com/v1/quote/PETR4,VALE3" \
  -H "X-API-Key: ch_live_suachaveaqui"

# Consultar cotações com balanço e módulos fundamentalistas
curl -X GET "https://api.cotacoeshoje.com/v1/quote/PETR4?fundamental=true&dividends=true" \
  -H "X-API-Key: ch_live_suachaveaqui"

# Converter moeda em tempo real (100 USD para BRL)
curl -X GET "https://api.cotacoeshoje.com/v1/currency/convert?from=USD&to=BRL&amount=100" \
  -H "X-API-Key: ch_live_suachaveaqui"

# Consultar valores mais recentes de indicadores macroeconômicos
curl -X GET "https://api.cotacoeshoje.com/v1/macro/latest?symbols=selic,cdi,ipca" \
  -H "X-API-Key: ch_live_suachaveaqui"

# Executar Screener de ações com DY > 6% e P/L < 10
curl -X GET "https://api.cotacoeshoje.com/v1/screener?asset_type=stocks&min_dy=6&max_pl=10&limit=10" \
  -H "X-API-Key: ch_live_suachaveaqui"
```

### Python (httpx)
```python
import httpx

API_KEY = "ch_live_suachaveaqui"
BASE_URL = "https://api.cotacoeshoje.com/v1"

headers = {"X-API-Key": API_KEY}

with httpx.Client(base_url=BASE_URL, headers=headers) as client:
    # 1. Cotações B3 em tempo real
    response = client.get("/quote/PETR4,VALE3")
    print("Cotações:", response.json())

    # 2. Indicadores Macro mais recentes
    macro = client.get("/macro/latest?symbols=selic,cdi,ipca")
    print("Macro:", macro.json())

    # 3. Indicadores de Fundos Imobiliários
    fii = client.get("/fii/indicators/HGLG11")
    print("FII:", fii.json())
```