O que verificar ao avaliar corretores com API

Defina “corretor com API” e o que muda quando você usa um

Um corretor com API é um serviço de acesso ao mercado ou de execução de negociações no qual você se conecta programaticamente (por meio de uma interface de programação de aplicações) em vez de usar uma interface de negociação manual. A principal diferença é que o seu sistema se torna responsável por transformar sua intenção (instruções de ordem) em solicitações reais, processar respostas e reagir a erros.

Para avaliar corretores com API objetivamente, trate o problema como duas camadas:

Mecânica de integração (estável e testável): como a autenticação funciona, como você envia solicitações, como são as respostas e como você interpreta os estados de ordens e execuções.
Condições de mercado e do provedor (variáveis): o que acontece durante preços voláteis, liquidez parcial, atrasos de rede e regras e custos de execução do lado do provedor.

Se você focar apenas na parte de “API”, pode perder as incertezas mais importantes—qualidade de execução e comportamento operacional sob estresse.

Checklist: mecânica de integração que você pode verificar

Use uma abordagem baseada em evidências: solicite ou inspecione a documentação e depois teste com exemplos controlados.

Autenticação e escopo da conta: Confirme quais credenciais são usadas, como o acesso é autorizado e se as chaves de API podem ser restritas por permissões (por exemplo, somente leitura vs. negociação).
Modelo de solicitação/resposta: Verifique como a API representa ordens—tipos de ordem, time-in-force, campos obrigatórios e a estrutura exata das respostas. Defina em quais status você pode confiar e quais campos podem estar ausentes durante falhas transitórias.
Idempotência e controle de duplicação: Determine como a API previne ou resolve envios repetidos (por exemplo, novas tentativas após timeouts). Seu sistema deve ser capaz de evitar ordens duplicadas acidentais.
Mapeamento do ciclo de vida de ordens e execuções: Verifique o que significam “aceita”, “preenchida”, “rejeitada”, “cancelada” ou estados equivalentes. Um risco material é a inconsistência de status—seu sistema pode acreditar que uma ordem está ativa enquanto o corretor já a rejeitou.
Limites de taxa e comportamento de throttling: Verifique os limites documentados e quais respostas indicam throttling. Planeje como seu código se comporta ao receber sinais de limite ou backpressure.
Produtos de dados e timestamps: Se a API fornecer cotações, negociações ou eventos de conta, esclareça o significado do timestamp (horário do servidor vs. horário local) e as premissas de frequência de atualização. Sem isso, você não consegue separar latência de movimento de mercado.
Tratamento de erros e estratégia de nova tentativa: Confirme como a API comunica erros (HTTP/rede vs. nível de aplicação). Seus testes devem classificar falhas em “seguro tentar novamente”, “tentar novamente com idempotência” e “não tentar novamente”.

Evidências e exemplos: como testar sem assumir resultados

Como os resultados variam com as condições, use testes que meçam o comportamento do seu sistema.

Teste de integração caixa-preta: Envie um pequeno número de ordens bem definidas e confirme se sua máquina de estados interna corresponde ao ciclo de vida relatado pela API.
Simulação de timeout e nova tentativa (premissa declarada): Assuma que sua chamada de rede pode expirar após um determinado limite (escolha um limite para seu ambiente). Depois, verifique se tentar novamente causa duplicatas ou se chaves de idempotência (se suportadas) previnem repetições.
Cenário de preenchimento parcial (premissa declarada): Assuma que o mercado pode não satisfazer totalmente o seu tamanho. Teste como você detecta a quantidade restante e como as atualizações subsequentes são entregues.
Verificações de ordenação de eventos: Registre a sequência de callbacks/eventos da API e compare-a com o que seu código espera. Um modo de falha é a atualização fora de ordem, que pode corromper premissas no seu rastreamento de ordens.

Para cada teste, registre: IDs de solicitação, timestamps (com fuso horário/fonte), payloads de resposta e resultados finais de conciliação.

Limitações e riscos: pelo menos um modo de falha material

Limitações importantes se aplicam mesmo quando a documentação parece clara:

Falhas operacionais: Indisponibilidades de rede, quedas de API ou degradação do serviço podem causar respostas ausentes ou atualizações de status atrasadas. Sua automação deve continuar operando com segurança durante a incerteza.
Preenchimentos parciais e variabilidade de execução: Mesmo com integração correta, os preenchimentos reais dependem da liquidez disponível e da mecânica de execução naquele momento.
Divergência de status (modo de falha material): Seu sistema pode mostrar ordens “em andamento” enquanto o corretor as rejeitou ou cancelou. Isso pode acontecer após timeouts, novas tentativas ou entrega inconsistente de eventos.
Incerteza de custos e slippage: Os resultados de execução podem diferir de relações históricas, porque custos e qualidade de execução variam com as condições.

Portanto, o objetivo da avaliação não é previsão, mas a capacidade de conciliar o que aconteceu e detectar divergências.

Verificação e próximas perguntas antes da automação

Antes de depender da automação via API, exija uma resposta clara e verificável de forma independente para estas perguntas: