O que as pessoas entendem errado sobre uma API de Corretora
Uma API de Corretora é uma interface (geralmente programática) que permite que o software envie solicitações a uma corretora/plataforma de execução e receba respostas, como confirmações de pedidos, execuções e atualizações relacionadas à conta. Erros comuns acontecem quando os desenvolvedores tratam essa interface como um pipeline único e totalmente confiável, em vez de um sistema com estados explícitos, temporização e possíveis resultados de falha.
Os principais mal-entendidos a observar:
- Confundir “solicitação aceita” com “negociação executada”. Uma API pode confirmar que sua mensagem foi recebida enquanto o resultado final depende das regras de execução.
- Assumir que carimbos de data/hora e preços estão sincronizados. Sistemas diferentes podem usar relógios, ciclos de atualização ou representações diferentes.
- Ignorar a diferença entre os dados de mercado que você vê e os dados de mercado que importaram para a execução. A execução pode depender de spreads, liquidez e mudanças no livro de ofertas no momento em que a corretora processa seu pedido.
- Esquecer que os custos existem e podem variar: comissões, efeitos de financiamento/pernoite e outras taxas podem alterar os resultados líquidos.
- Tratar erros como exceções raras. Na prática, as APIs podem retornar timeouts, pedidos rejeitados, execuções parciais ou atualizações ausentes.
A mecânica: onde os erros se originam
As APIs de Corretoras normalmente envolvem estas partes móveis:
- Criação da solicitação: você gera pedidos e escolhe parâmetros (instrumento, quantidade, tipo, time-in-force e identificadores).
- Transporte e processamento: sua solicitação viaja por uma rede, é autenticada e processada pelos serviços da corretora.
- Atualizações de estado: a corretora responde com confirmações e posteriormente publica mudanças de status (por exemplo, aberto → parcialmente executado → executado/cancelado/rejeitado).
- Relatórios de execução: execuções e detalhes contábeis relacionados são entregues quando a execução ocorre.
Erros comuns de implementação dentro dessas partes:
- Não usar identificadores estáveis (ou usá-los de forma inconsistente). Sem um id claro no lado do cliente e regras consistentes de replay, novas tentativas podem criar duplicatas.
- Ignorar as expectativas de idempotência. Se você tentar novamente após um timeout, pode não saber se a corretora já agiu.
- Codificar suposições fixas sobre ciclos de vida de pedidos. Alguns pedidos podem ser rejeitados após a aceitação, parcialmente executados várias vezes ou cancelados com base nas regras da plataforma.
- Misturar valores “estimados” e “confirmados”. Se o seu sistema registra um cálculo baseado em um snapshot e depois o compara com execuções realizadas, discrepâncias são esperadas.
Evidências e exemplos de verificações que você pode fazer
Como os resultados variam e nenhum dado em tempo real é assumido aqui, a abordagem mais segura é verificar o comportamento usando verificações controladas:
- Auditoria da máquina de estados: Para uma amostra de pedidos de teste, registre cada mensagem/evento e garanta que seu aplicativo faça a transição por todos os estados que você observar (aceito, aberto, execução parcial, estado final). Se um estado observado estiver faltando na sua lógica, você encontrou um provável bug.
- Teste de nova tentativa e duplicação: Simule um timeout de rede imediatamente após enviar uma solicitação de pedido. Em seguida, verifique se a corretora criou um pedido ou vários e confirme como seus identificadores de cliente se comportam na nova tentativa.
- Verificação de consistência contábil: Para cada evento de execução recebido, compare suas suposições de bruto/taxas com o que sua corretora relata como resultados realizados. Se a API fornecer campos separados para taxas ou saldos, use esses valores confirmados em vez de estimativas.
- Verificação de tempo e sequenciamento: Registre a hora local quando você envia solicitações e os carimbos de data/hora relatados pela corretora (se fornecidos). Procure diferenças de ordenação: você pode precisar classificar pelo horário do evento em vez do horário de chegada.
Essas verificações não garantem desempenho futuro, mas testam diretamente se as suposições do seu software correspondem ao comportamento observável da API da corretora.
Limitações, modos de falha materiais e riscos
Uma limitação importante é que as APIs de Corretoras operam em condições do mundo real: atrasos de rede, congestionamento de serviços, regras da plataforma e liquidez variável. Mesmo o código correto pode produzir resultados diferentes de execuções anteriores.
Pelo menos um modo de falha material para planejar:
- Execuções parciais e finalidade atrasada: Seu sistema pode assumir que um pedido é concluído imediatamente. Na realidade, as execuções podem ser divididas ao longo do tempo, e o status final pode chegar mais tarde.
Outros modos de falha que comumente causam danos:
- Pedidos rejeitados com contexto ausente: Se você tratar rejeições como falhas genéricas, pode perder a categoria do motivo necessária para corrigir problemas de parâmetros.
- Atualizações desatualizadas ou incompletas: Você pode receber atualizações de conta/pedido fora de sequência. Sem uma reconciliação cuidadosa, você pode calcular posições incorretamente.
- Cálculos incorretos de resultado líquido: Se você ignorar taxas, regras de arredondamento ou convenções de contrato/margem, seu “P&L esperado” interno pode divergir do que a corretora relata.