Utilização de APIs de cotação com base na etapa: da conexão à construção do sistema

Nos sistemas de negociação financeira, um problema comum não é falhar ao conectar à API, mas sim um projeto de sistema ineficiente. A questão central é utilizar a interface correta no momento correto, de acordo com as necessidades de cada fase da aplicação.

Problemas comuns de projeto

• Consultar o endpoint de velas (candles) a cada segundo para obter o preço mais recente em uma página de listagem.
• Estabelceer conexões WebSocket em todas as páginas para tentar uma atualização "em tempo real".
• Iniciar uma assinatura WebSocket na inicialização sem antes obter a lista de ativos disponíveis.
• Não fechar a conexão WebSocket anterior ao mudar de página, desperdiçando recursos.

A essência: dados em camadas

Uma API de cotação é um sistema de dados em camadas. As necessidades do aplicativo mudam drasticamente dependendo da fase de operação:

Fases de uso dos dados

• Inicialização: Obter a lista de símbolos ou ativos negociáveis.
• Exibição: Apresentar o preço atual nas páginas.
• Tempo Real: Receber notificações proativas quando o preço mudar.

Tipos de dados

• Snapshot (Ticker): Preço e variação no instante atual. Ideal para listas e visões gerais.
• Histórico (K-lines): Preços ao longo do tempo. Ideal para gráficos e backtesting.
• Fluxo contínuo: Atualizações enviadas proativamente. Ideal para monitoramento em tempo real e execução de ordens.

Complexidade e tecnologia

• API REST: Simples, estável, fácil de manter, mas requer consulta periódica (polling).
• WebSocket: Eficiente e em tempo real, mas exige gestão de conexão, reconexão e heartbeat.

Camada 1: Símbolos ou Ativos Disponíveis

A primeira tarefa ao iniciar o sistema é buscar a lista de ativos que podem ser negociados. Codificar essa lista diretamente no aplicativo (hardcode) leva a problemas, como não remover ativos descontinuídos ou não incluir novas listagens.

Recomendação: Chame o endpoint de símbolos durante a inicialização e armazene o resultado em cache. O cache pode ser atualizado periodicamente, por exemplo, uma vez ao dia. Evite chamar esta API antes de cada consulta de preço.

GET /api/v1/ativos/lista?mercado=BR&limite=50

Camada 2: Ticker (Snapshot)

O endpoint Ticker é adequado para a maioria dos cenários de exibição de preço atual, como a página principal, listas e painéis de monitoramento. Usar o endpoint de velas (K-lines) para isso é inadequado, pois sua estrutura é mais complexa e não foi projetado para consultas em tempo real de múltiplos ativos de uma só vez.

Vantagens do Ticker: Dados leves, suporta consulta de múltiplos ativos (ex.: até 50) em uma única requisição.

GET /api/v1/mercado/ticker?symbols=PETR4.SA,VALE3.SA

Resposta Exemplo

{
  "status": "sucesso",
  "dados": [
    {
      "ativo": "PETR4.SA",
      "ultimo_preco": "32.50",
      "variacao_24h": "1.25%",
      "volume_24h": "45000000",
      "maxima_24h": "33.00",
      "minima_24h": "31.80"
    }
  ]
}

Uso recomendado: Combine com uma atualização periódica (polling) a cada 5 a 10 segundos. Intervalos mais curtos sobrecarregam o servidor; intervalos mais longos sacrificam a atualidade dos dados.

Camada 3: K-lines (Dados Históricos)

O parâmetro essencial é o intervalo (interval), que define a granularidade dos dados.

• 1m (1 minuto): Ideal para gráficos de curto prazo e escalpe. Gera grande volume de dados.
• 1h (1 hora): Para análise intraday.
• 1d (1 dia): Para análise de médio/longo prazo e backtesting. Volume de dados gerenciável.

GET /api/v1/mercado/velas?ativo=VALE3.SA&intervalo=1d&limite=90

Uso recomendado: Utilize o parâmetro limite para carregar uma quantidade específica de períodos (ex.: últimos 90 dias). Para backtesting, use parâmetros de data de início e fim.

Camada 4: WebSocket (Fluxo em Tempo Real)

Utilizar WebSocket implica assumir custos operacionais: gerenciar conexões persistentes, implementar lógica de heartbeat, reconexão automática e filas de mensagens.

Cenários ideais: Monitoramento de preços com latência mínima (ex.: escalpe), alertas de preço imediatos, sistemas de negociação de alta frequência.

Cenários não recomendados: Listas de cotação, gráficos históricos, monitoramento de baixa frequência. Nestes casos, use API REST com polling.

// Conexão e assinatura usando o cliente nativo do navegador
const conexaoWS = new WebSocket('wss://api.exemplo.com.br/v1/tempo-real');
conexaoWS.onopen = () => {
  conexaoWS.send(JSON.stringify({
    comando: 'assinar',
    dados: { canal: 'ticker', ativos: ['PETR4.SA'] }
  }));
};

Limitação de Projeto: Alguns mercados, como câmbio (Forex), podem suportar apenas o canal ticker devido à sua natureza descentralizada (OTC), não oferecendo profundidade ou negociações reais.

Caminho Completo de Uso: Exemplo Prático

Considerando um sistema de monitoramento do mercado brasileiro (B3):

Etapa 1: Inicialização

GET /api/v1/ativos/lista?mercado=BR
// Armazena o resultado em um cache local (ex.: Redis, ou no estado do aplicativo).

Etapa 2: Exibição

Para a lista principal:

GET /api/v1/mercado/ticker?symbols=PETR4.SA,VALE3.SA,ITUB4.SA
// Executar esta chamada a cada 5-10 segundos usando setInterval ou um mecanismo semelhante.

Para o gráfico de um ativo específico:

GET /api/v1/mercado/velas?ativo=PETR4.SA&intervalo=1d&limite=60
// Carregar apenas quando o usuário abrir a visualização do gráfico.

Etapa 3: Módulo Específico em Tempo Real

Apenas para a janela de negociação ativa ou de alertas:

// Iniciar a conexão WebSocket e assinar o ativo específico
// Essencial: implementar lógica para DESASSINAR e FECHAR a conexão ao sair da página/componente.
conexaoWS.send(JSON.stringify({
  comando: 'desassinar',
  dados: { canal: 'ticker', ativos: ['PETR4.SA'] }
}));
conexaoWS.close();

Erros Comuns e Correções

1. Abuso de WebSocket: Conectar e assinar todos os ativos no início.
   Correção: Usar REST + polling para listagens. Reservar WebSocket apenas para telas que exigem baixíssima latência.
2. Uso indevido do endpoint de K-lines: Chamá-lo repetidamente para o preço atual.
   Correção: Usar o endpoint Ticker para preço atual. Usar K-lines apenas para dados históricos.
3. Não cachear símbolos: Chamar a API de lista de ativos antes de cada consulta.
   Correção: Buscar na inicialização e atualizar o cache periodicamente.
4. Escolha errada de intervalo: Usar dados de 1 minuto para um gráfico mensal.
   Correção: Selecionar o intervalo (1m, 1h, 1d) de acordo com a análise pretendida para otimizar performance.
5. Confundir APIs de cotação e de negociação: Usar dados de cotação para decisões de execução de ordens.
   Correção: APIs de cotação são para display e análise. A execução de operações (compra/venda) deve usar a API de negociação correspondente.