# Diário Operebem

> O Diário Operebem é um diário de trades e análise de performance. A API pública v1 é somente leitura e consulta exclusivamente a conta vinculada à API Key.

## Produto

- [Diário Operebem](https://diario.operebem.com.br/): registro e análise de operações.
- [API](https://diario.operebem.com.br/api): apresentação da integração.
- [Documentação](https://diario.operebem.com.br/docs/api): contrato público.
- [Contrato Markdown](https://diario.operebem.com.br/docs/api.md): referência completa.

Operações, contas, finanças e sessões são privadas. Este índice não concede acesso a elas.

## Fontes canônicas
- Documentação visual: https://diario.operebem.com.br/docs/api
- Contrato Markdown completo, incluindo exemplos JSON: https://diario.operebem.com.br/docs/api.md
- Este índice para agentes e LLMs: https://diario.operebem.com.br/llms.txt
- Base URL: https://diario.operebem.com.br/api/v1

## Regras da API
- Métodos: GET para os endpoints abaixo; OPTIONS é usado para preflight CORS.
- Autenticação: Authorization: Bearer <API_KEY> ou X-API-Key: <API_KEY>.
- Formatos de chave aceitos: opb_<64 hex> e diario_live_<64 hex>.
- A API exige conta com plano PRO e nunca aceita chave em query string.
- Limites: 4 requisições/minuto e 50 requisições/dia UTC por chave.
- Respostas de sucesso: JSON com success=true e data. Datas: ISO 8601/RFC 3339.
- Headers de limite: X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-RateLimit-Limit-Day e X-RateLimit-Remaining-Day.

## Endpoints
### GET /account
- Retorna a conta vinculada à chave, as estatísticas básicas e o primeiro e o último registro de atividade.
- Parâmetros: nenhum.
- Exemplo de requisição: GET /account
- Campos: account.id, name, broker, brokerLogo, platform, currency, accountNumber, server, isDemo, isActive, initialBalance, createdAt; stats.totalTrades, winningTrades, losingTrades, winRate, netProfit, currentBalance, currency; activity.firstTradeAt, lastTradeAt
### GET /trades
- Lista as operações da conta com paginação, filtros de ativo, tipo, resultado, período e ordenação.
- Parâmetros:
  - `page`: Inteiro positivo entre 1 e 1.000.000. Padrão: 1.
  - `limit`: Inteiro positivo entre 1 e 100. Padrão: 50.
  - `symbol`: Ativo exato, por exemplo WINQ26 ou EURUSD.
  - `type`: Tipo da operação, por exemplo BUY ou SELL.
  - `result`: Resultado exato: win, loss ou breakeven.
  - `startDate`: Início pela abertura do trade: YYYY-MM-DD em UTC ou timestamp RFC 3339 com segundos e fuso. Datas impossíveis são rejeitadas.
  - `endDate`: Fim pela abertura do trade: YYYY-MM-DD inclui o dia UTC inteiro; timestamp RFC 3339 com segundos e fuso mantém o instante exato.
  - `sortBy`: Campo: openTime, closeTime, profit, volume ou symbol. Padrão: openTime.
  - `sortOrder`: Ordem: asc ou desc. Padrão: desc.
- Exemplo de requisição: GET /trades?limit=10&result=loss&sortBy=profit&sortOrder=asc
- Campos: trades[].id, ticket, symbol, type, volume, openPrice, closePrice, openTime, closeTime, profit, commission, swap, sl, tp, durationSeconds, profitPercent, strategy; pagination.page, limit, total, totalPages, hasNext, hasPrev
### GET /stats
- Retorna métricas de trades (profit bruto), sequências, duração e visão financeira da conta. Campos permanecem presentes na conta vazia. profitFactor pode ser o texto Infinity quando há ganho sem perda; currentBalance inclui custos e lançamentos confirmados.
- Parâmetros: nenhum.
- Exemplo de requisição: GET /stats
- Campos: currency, totalTrades, winningTrades, losingTrades, winRate, profitFactor, totalProfit, averageWin, averageLoss; maxWinStreak, maxLossStreak, averageTradeDuration (alias em segundos), averageTradeDurationSeconds, averageTradeDurationMinutes, bestDay, worstDay; totalDeposits, totalWithdrawals, currentBalance, netFlow
### GET /analytics/summary
- Consolida métricas básicas, risco, saldo, atividade e, por padrão, performance por dimensão.
- Parâmetros:
  - `startDate`: Início pela abertura do trade: YYYY-MM-DD em UTC ou timestamp RFC 3339 com segundos e fuso. Datas impossíveis são rejeitadas.
  - `endDate`: Fim pela abertura do trade: YYYY-MM-DD inclui o dia UTC inteiro; timestamp RFC 3339 com segundos e fuso mantém o instante exato.
  - `includePerformance`: Booleano true ou false. Padrão: true; quando false, omite data.performance e evita seu cálculo.
- Exemplo de requisição: GET /analytics/summary?startDate=2026-09-01&endDate=2026-09-30
- Campos: account.id, name, broker, brokerLogo, platform, currency; basic.totalTrades, winningTrades, losingTrades, breakEvenTrades, winRate, totalProfit, totalLoss, netProfit, averageProfit, averageLoss, averageTrade, profitFactor, bestTrade, worstTrade, expectancy; risk.sharpeRatio, sortinoRatio, maxDrawdown, maxDrawdownPercent, recoveryFactor, calmarRatio, consecutiveWins, consecutiveLosses, currentStreak; balance.initial, current, netProfit, grossTradingResult, tradeCharges, netTradingResult, contributedCapital, capitalReturnPercent, growthPercent, twrPercent, annualizedReturn, annualizedTwrPercent, currency; activity.totalTrades, tradingDays, firstTradeAt, lastTradeAt; performance.symbol, dayOfWeek, hour, session, month (quando includePerformance=true)
### GET /analytics/equity-curve
- Retorna patrimônio, resultado operacional líquido, TWR e seus drawdowns por operação ou período agregado.
- Parâmetros:
  - `startDate`: Início pela abertura do trade: YYYY-MM-DD em UTC ou timestamp RFC 3339 com segundos e fuso. Datas impossíveis são rejeitadas.
  - `endDate`: Fim pela abertura do trade: YYYY-MM-DD inclui o dia UTC inteiro; timestamp RFC 3339 com segundos e fuso mantém o instante exato.
  - `granularity`: Agregação em UTC: trade, day, week (segunda a domingo) ou month. Padrão: trade; a curva também contém eventos financeiros.
- Exemplo de requisição: GET /analytics/equity-curve?granularity=week
- Campos: equityCurve[].date, equity, drawdown, operationalResult, operationalDrawdown, returnPercent, drawdownPercent, profit; summary.initialBalance, finalBalance, peak, trough, maxDrawdown, maxDrawdownPercent, grossTradingResult, tradeCharges, netTradingResult, contributedCapital, capitalReturnPercent, twrPercent, annualizedTwrPercent, totalPoints, granularity, currency
### GET /analytics/performance
- Agrupa o resultado por ativo, dia da semana, hora, sessão ou mês. Sem dimension, retorna todas as dimensões e meta; com dimension, retorna somente a dimensão escolhida.
- Parâmetros:
  - `startDate`: Início pela abertura do trade: YYYY-MM-DD em UTC ou timestamp RFC 3339 com segundos e fuso. Datas impossíveis são rejeitadas.
  - `endDate`: Fim pela abertura do trade: YYYY-MM-DD inclui o dia UTC inteiro; timestamp RFC 3339 com segundos e fuso mantém o instante exato.
  - `dimension`: Filtro opcional: symbol, dayOfWeek, hour, session ou month.
- Exemplo de requisição: GET /analytics/performance?dimension=hour
- Campos: data.symbol, dayOfWeek, hour, session, month (cada chave contém trades, wins, losses, winRate, profit e avgProfit); meta.tradesAnalyzed, meta.dateRange.from, meta.dateRange.to (quando dimension não é informado; datas null se vazio)

## Erros
- 400: INVALID_QUERY: parâmetro ausente, inválido ou fora das opções aceitas.
- 401: MISSING_API_KEY, INVALID_API_KEY_FORMAT, INVALID_API_KEY, API_KEY_REVOKED ou API_KEY_EXPIRED.
- 403: TIER_DOWNGRADED: conta sem plano PRO. O preflight sem Origin também é recusado.
- 404: ACCOUNT_NOT_FOUND: conta vinculada não encontrada.
- 429: RATE_LIMIT_EXCEEDED: limite por minuto ou por dia excedido.
- 500: INTERNAL_ERROR: falha interna ao consultar ou calcular os dados.
- 503: ENTITLEMENT_UNAVAILABLE: não foi possível revalidar o plano; Retry-After informa a espera.

Use o contrato Markdown para os exemplos completos e não invente endpoints, parâmetros ou campos além dos descritos nas fontes canônicas.