Resposta direta
Ao avaliar uma API de ordens, concentre-se no que a API realmente faz com as ordens, em como você pode confirmar os resultados e em onde o comportamento pode diferir das suas expectativas. Mantenha o checklist objetivo: separe a mecânica estável (estrutura de solicitação/resposta, semântica do ciclo de vida) das condições variáveis (movimento do mercado, custos, qualidade de execução e regras locais). Como os resultados dependem de fatores externos, trate os exemplos como premissas, não como previsões.
Como funciona uma API de ordens (mecanismo e definição)
Uma API de ordens é uma interface de programa usada para enviar, modificar e cancelar ordens de negociação e para recuperar informações sobre o status do ciclo de vida delas. Na prática, você normalmente trabalha com:
- Solicitação de ordem: os dados que você envia (por exemplo, tipo de ordem, lado, quantidade, time-in-force e quaisquer identificadores necessários).
- Execução e confirmação: as respostas que você recebe (aceitação, rejeição ou erros).
- Atualizações de estado da ordem: como o provedor relata mudanças ao longo do tempo (aberta, parcialmente preenchida, preenchida, cancelada, expirada, rejeitada).
- Identificadores de reconciliação: campos que permitem corresponder sua intenção aos resultados relatados pelo provedor (como IDs de ordem do cliente e IDs de ordem do provedor, se houver suporte).
Uma etapa fundamental da avaliação é traduzir a documentação em um modelo de estado explícito para o seu sistema: quais status existem, como ocorrem as transições e quais garantias (se houver) a API oferece em relação a ordenação, novas tentativas e atualizações. Mecânica estável é aquela sobre a qual você pode raciocinar a partir da especificação; condições variáveis são tudo o que pode mudar entre a solicitação e a confirmação.
Checklist de due diligence (pontos de verificação)
Use os itens abaixo para construir um processo de verificação repetível.
1) Entrada e semântica (o que você envia)
- Confirme os campos obrigatórios e as restrições de dados (tipos de ordem permitidos, tamanhos mínimo/máximo, valores válidos de time-in-force).
- Documente como a API interpreta unidades e regras de arredondamento. Declare suas próprias premissas para quantidade, precisão e como os valores de “base” vs. “cotação” são tratados.
2) Idempotência e proteção contra duplicatas (evita divergências de estado)
- Verifique se a API oferece suporte a solicitações idempotentes ou a uma estratégia documentada para novas tentativas após timeouts.
- Verifique como as duplicatas são tratadas quando a mesma solicitação é enviada novamente (mesmo ID do cliente vs. nova solicitação). Isso é importante porque a lógica de nova tentativa é comum em sistemas automatizados.
3) Ciclo de vida da ordem e reconciliação (evidência ou documentação)
- Verifique o ciclo de vida completo da ordem: quais status podem ocorrer e como as transições são relatadas.
- Confirme os campos necessários para reconciliação (IDs de ordem, carimbos de data/hora, quantidades preenchidas, quantidade restante e motivos de rejeição).
- Defina seus critérios de “concluído” (por exemplo, você considera uma ordem encerrada quando recebe um estado terminal, como preenchida/cancelada/rejeitada/expirada—com base na semântica documentada do provedor).
4) Atualizações e modelo de entrega (o que você pode observar)
- Determine se as informações de status vêm por polling, streaming/webhooks ou ambos.
- Se as atualizações forem assíncronas, verifique as garantias sobre ordenação de eventos e integridade dos eventos. Sua lógica de reconciliação deve tratar atualizações ausentes ou atrasadas como um cenário explícito.
5) Custos e premissas de execução (o que pode mudar)
- Identifique quais custos e efeitos de execução podem alterar os resultados entre a solicitação e o status final: taxas, spreads, slippage, execuções parciais e latência.
- Ao ilustrar um exemplo, declare as premissas (por exemplo, “suponha que as taxas sejam X e que as execuções ocorram em uma única etapa”) e depois observe que as condições reais podem divergir.
6) Modos de falha (bandeiras vermelhas)
Procure e teste estes modos de falha comuns:
- Ordens rejeitadas (erros de validação, permissões insuficientes ou parâmetros inválidos).
- Timeouts e erros transitórios (seu cliente pode tentar novamente enquanto o provedor já pode ter processado a solicitação).
- Execuções parciais (a ordem se torna parcialmente executada, exigindo lógica para a quantidade “restante”).
- Estado inconsistente (seu sistema vê uma fonte de status enquanto a outra fonte está defasada).
Se a documentação não especificar claramente como esses comportamentos funcionam, trate isso como uma bandeira vermelha e planeje uma reconciliação e um monitoramento conservadores.
Limitações e riscos (o que pode dar errado)
A execução de ordens e os resultados do estado das ordens dependem das condições de mercado e do comportamento do provedor, que não são totalmente controláveis. Relações históricas não garantem resultados futuros, e mesmo especificações cuidadosas podem falhar sob estresse (alta volatilidade, problemas de rede ou manutenção no lado do provedor). Limitações materiais que devem ser explicitamente reconhecidas incluem:
- Incerteza entre intenção e execução: a confirmação não significa necessariamente execução final.
- Resultados não atômicos: execuções parciais e cancelamentos subsequentes podem criar múltiplos estados para uma única instrução.
- Lacunas de observabilidade: atrasos ou atualizações perdidas podem fazer com que seu sistema interprete incorretamente o status atual.