Proibição de Polling

Visão Geral

A API Selectwin proíbe explicitamente o uso de polling (consultas recorrentes e frequentes) como método para obter atualizações de status de recursos. Esta política foi implementada para garantir a estabilidade, eficiência e escalabilidade da plataforma, bem como para proporcionar uma experiência consistente para todos os integradores.

O que é Polling?

Polling é a prática de verificar repetidamente o status de um recurso em intervalos regulares através de requisições consecutivas à API. Por exemplo:

// Exemplo de polling (PRÁTICA PROIBIDA)
async function verificarStatusTransacao(transactionId) {
  let status = 'processing';
  
  while (status === 'processing') {
    // Espera 1 segundo
    await new Promise(resolve => setTimeout(resolve, 1000));
    
    // Faz uma nova requisição para verificar o status
    const response = await fetch(`https://api.selectwin.io/v1/transactions/${transactionId}`, {
      headers: { 'SelectKey': 'sua_chave_api' }
    });
    
    const data = await response.json();
    status = data.status;
  }
  
  return status;
}

Por que o Polling é Proibido?

1. Consumo Excessivo de Recursos

O polling gera um volume significativo de requisições, muitas das quais não produzem alterações no estado do recurso. Este padrão:

Sobrecarrega os servidores com requisições desnecessárias
Reduz a capacidade de atendimento para outras solicitações legítimas
Aumenta os custos de infraestrutura sem benefício proporcional

2. Escalabilidade Comprometida

À medida que o número de usuários e transações cresce, o impacto negativo do polling se multiplica:

Cada cliente que utiliza polling pode gerar centenas de requisições desnecessárias
Em horários de pico, o efeito cumulativo pode degradar a performance para todos os usuários
Torna-se insustentável manter a qualidade de serviço sob volume elevado

3. Rate Limiting Inevitável

O uso de polling frequentemente resulta em:

Atingir rapidamente os limites de taxa (rate limits) impostos pela API
Aumento das requisições rejeitadas com código de status HTTP 429 (Too Many Requests)
Degradação da experiência para o usuário final

4. Ineficiência Operacional

O polling é inerentemente ineficiente pois:

Consome largura de banda desnecessariamente
Aumenta a latência da aplicação
Desperdiça ciclos de CPU tanto no cliente quanto no servidor
Eleva o consumo de energia, tornando-se menos sustentável

Alternativas Recomendadas

A Selectwin oferece alternativas mais eficientes para monitorar mudanças de estado:

1. Webhooks (Método Recomendado)

Os webhooks permitem receber notificações em tempo real quando ocorrem alterações no estado de um recurso:

// Exemplo de rota Express para receber webhooks
const express = require('express');
const app = express();

app.post('/webhook/transactions', express.json(), (req, res) => {
  const event = req.body;
  
  // Verifica a assinatura do webhook (importante para segurança)
  // O header é enviado no formato: X-Selectwin-Signature: sha256=<hex>
  if (!isValidSignature(req.headers['x-selectwin-signature'], event, webhookSecret)) {
    return res.status(401).send('Assinatura inválida');
  }
  
  // Processa o evento com base no tipo
  switch (event.type) {
    case 'transaction.approved':
      // Lógica para transação aprovada
      break;
    case 'transaction.dispute':
      // Lógica para transação em disputa
      break;
    case 'transaction.refunded':
      // Lógica para transação estornada
      break;
  }
  
  // Sempre retorne 200 para confirmar o recebimento
  res.status(200).send('Webhook recebido com sucesso');
});

Configuração de Webhooks

Para configurar um endpoint de webhook:

curl -X POST "https://api.selectwin.io/v1/webhooks/endpoints" \
     -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Facebook Integration",
       "endpoint": "https://webhooks.mydomain.com/selectwin",
       "forceActivities": true,
       "authorization": {
           "type": "basic",
           "value": "YOUR_KEY_HERE"
       },
       "events": ["transaction.approved", "customer.updated"]
     }'

2. Notificação por E-mail ou SMS (Para Baixo Volume)

Para casos de baixo volume de operações ou notificações críticas:

Configure notificações por e-mail ou SMS através do painel administrativo
Utilize essas notificações como gatilho para verificação pontual da API
Não dependa exclusivamente deste método para processamento automático