API Pull (Enterprise)

Versão: 1.0
Owner: Engenharia SOFIA
Última revisão: 2026
Aplicável a: Dev Integradores, Backend Enterprise

O modelo API Pull permite que o parceiro consulte ativamente a API da SOFIA por meio de polling controlado.

É indicado quando o parceiro possui backend próprio, infraestrutura restritiva (firewall) ou necessidade de fluxo determinístico.

1. Quando Utilizar

Utilize API Pull quando:

• Não for possível receber webhooks.
• O ambiente exigir controle total sobre ritmo de consumo.
• A integração rodar via jobs/cron.
• Houver necessidade de backfill controlado.

Não utilize quando:

• For necessária latência mínima.
• O volume de eventos for alto.
• Houver necessidade de atualização sub-segundo.

Nesses casos, prefira WebSocket ou Webhook.

2. Base da API

https://api.v1sofia.com/api

3. Endpoints Compatíveis

Sinais

• GET /signals/recent
• GET /signals-history

Roleta

• GET /roulette-history
• GET /roulette-status
• GET /tables-status

Metadados

• GET /signal-attributes
• GET /available-options

Autenticação pode ser exigida dependendo do endpoint.

4. Autenticação

Para endpoints protegidos:

curl "https://api.v1sofia.com/api/signals/recent?limit=20" \
  -H "Authorization: Bearer <JWT>"

Alternativa:

x-supabase-auth: <JWT>

Regras:

• Nunca chamar API diretamente do frontend.
• Nunca logar token.
• Renovar sessão antes de retry após 401.

5. Frequência Recomendada

Produção:

6. Deduplicação

Obrigatório:

• Tratar id do sinal como identificador único.
• Persistir último created_at + id.
• Ignorar itens já processados.

Não confiar apenas em timestamp.

7. Timeout e Retry

Timeout recomendado

• 5–8 segundos por request.

Retry permitido apenas para:

• Erro de rede
• 429
• 502
• 503
• 504

Nunca fazer retry automático para:

• 400
• 401
• 403

8. Estratégia de Fallback

Em caso de indisponibilidade:

1. Manter cache local.
2. Aplicar backoff exponencial com jitter.
3. Realizar backfill com /roulette-history.
4. Considerar migração para Webhook ou WebSocket se a carga aumentar.

9. Paginação e Parâmetros

/signals/recent

Parâmetros:

• limit (1–1000)
• table_id (opcional)

Retorno típico:

[
  {
    "id": "sig_123",
    "table_id": "mesa1",
    "strategy_name": "default",
    "numbers": [],
    "confidence": 0.8,
    "status": "active",
    "created_at": "2026-02-21T13:45:12.123Z"
  }
]

/roulette-history

Parâmetros obrigatórios:

• table_id
• limit
• offset

/signals-history

Filtros suportados:

• strategy_name
• table_id
• status
• confidence_min
• confidence_max
• limit (máx. 100)
• offset

Retorno:

{
  "data": [],
  "pagination": {},
  "filters": {}
}

10. Requisitos para Produção

Para uso enterprise, o parceiro deve:

• Implementar deduplicação persistente.
• Implementar timeout controlado.
• Implementar retry com backoff.
• Monitorar taxa de erro.
• Separar ambientes (sandbox/produção).
• Documentar política de retenção local.

11. Limitações

API Pull:

• Não garante entrega em tempo real.
• Pode sofrer rate limiting.
• Depende da disciplina de polling do parceiro.
• Não substitui webhook para confiabilidade assíncrona.