Referência e Solução de Problemas

Recomendações de Integração

Ver como Markdown

Use essas recomendações como uma linha de base de prontidão para produção. Elas complementam a referência do endpoint e ajudam integrações a se recuperarem com segurança de timeouts, reconexões, solicitações duplicadas e incidentes de credenciais.

Autenticação e segredos

  • Preferência API Key assinatura para programas de negociação do lado do servidor e JWT para ações frontend orientadas pelo usuário.
  • Mantenha apiSecret no gerenciamento de segredos do backend. Ele é exibido apenas uma vez e nunca deve ser enviado para um navegador ou cliente móvel.
  • Aplicar as permissões mínimas exigidas API Key e restringir IPs de origem quando o ambiente de integração suportar endereços de saída estáveis.
  • Desabilitar ou excluir imediatamente uma chave vazada, depois revisar os registros de solicitação antes de emitir uma substituição.

Validação de solicitação e idempotência

  • Antes de fazer ordens, consultar /v1/public/market/symbols e validar tickSize, stepSize, valor nocional mínimo e quantidade máxima localmente.
  • Gerar um clientOrderId único para cada escrita de ordem para que as solicitações possam ser conciliadas após uma desconexão.
  • Preserve o identificador original quando um resultado HTTP estiver incerto. Consulte a ordem existente antes de criar uma solicitação de substituição.
  • Tratar valores e preços decimais como cadeias ou tipos decimais, não como valores binários de ponto flutuante.

Ordem e WebSocket estado

  • Determinar o estado final após cancelar, cancelar tudo ou alterar operações de eventos privados de WebSocket ou de uma consulta REST .
  • Tratar toda reconexão como uma nova sessão WebSocket e restaurar todas as assinaturas necessárias.
  • Verifique a continuidade do livro de ordens com endVersion. Se surgir uma lacuna na versão, descarte o livro local e assine novamente para um novo snapshot.
  • Deduplicar eventos privados de ordens e contas antes de aplicá-los a saldos, posições ou registros de parceiros.

Registro, monitoramento e tentativas de reação

  • Registrar ID de solicitação, ID de pedido do cliente, status HTTP , código API negócio, latência e contagem de tentativas sem registrar segredos ou tokens completos.
  • Operações de retentativa apenas documentadas como seguras, usando recuo exponencial limitado e jitter.
  • Alerta sobre falhas de autenticação, erros de assinatura, respostas de limite de taxa WebSocket loops de reconexão, lacunas de sequência e diferenças de conciliação de ordem.
  • Mantenha os clocks do servidor sincronizados porque autenticação e assinatura dependem de carimbos de tempo.

Antes da produção

  • Exercício de timeout, solicitação duplicada, reconexão, rotação de chaves e cenários de retentativa de webhook em um ambiente não de produção.
  • Atribuir proprietários para rotação de credenciais, incidentes de negociação, falhas de webhooks e reconciliação.
  • Complete a checklist de lançamento em produção e use o template de solicitação de suporte quando for necessária a escalonamento.