Configuração Básica (Iframe)

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

O modelo Iframe permite que o parceiro exiba a mesa/jogo dentro do contexto da SOFIA, utilizando embed controlado por table_id.

Este modelo é focado em integração visual e navegação no browser.

1. Quando Utilizar

Use Iframe quando:

• O provedor disponibiliza URL pública embeddable.
• A integração ocorre no navegador.
• A prioridade é velocidade de implementação.
• A SOFIA é usada como camada de contexto ao redor do jogo.

Não use quando:

• O provedor bloqueia embed (X-Frame-Options ou CSP frame-ancestors).
• A integração precisa rodar 24/7 sem navegador.
• Há necessidade de automação backend ou persistência robusta.

Nestes casos, use Webhook ou API Pull.

2. Limitações Técnicas

O modelo depende das regras do navegador e do provedor.

Restrições comuns:

• Bloqueio por X-Frame-Options: DENY ou SAMEORIGIN
• CSP com frame-ancestors restritivo
• Cookies de terceiro bloqueados (Safari / iOS)
• Isolamento cross-origin (não há acesso ao DOM do iframe)
• Autenticação pode ocorrer dentro do iframe

A SOFIA não contorna restrições impostas pelo provedor.

3. Fluxo de Integração

3.1 Partner Slug

A aplicação é acessada via:

https://app.v1sofia.com/@<partner_slug>

Regras:

• Apenas minúsculas, números e hífen
• 3–30 caracteres
• Imutável após publicação

3.2 Configuração por Mesa (table_id)

Cada mesa deve possuir um iframe_url associado.

Configuração é armazenada por:

• partner_slug
• table_id

3.3 Resolução do Link (Backend SOFIA)

Quando o usuário seleciona uma mesa:

GET /api/partners/public/<partner_slug>/table-links?table_id=<table_id>

Se não existir link ativo, a mesa não será exibida.

4. Configuração via API

Atualizar múltiplas mesas

curl -X PUT "https://api.v1sofia.com/api/partners/me/table-links" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "table_id": "evolution-roulette",
        "iframe_url": "https://provedor.example.com/roulette/evolution-roulette"
      },
      {
        "table_id": "pragmatic-mega-roulette",
        "iframe_url": "https://provedor.example.com/roulette/pragmatic-mega-roulette"
      }
    ]
  }'

Regras:

• URLs devem usar HTTPS.
• Não são aceitos protocolos inseguros.
• A validação ocorre no backend.

5. Validação Pública

curl "https://api.v1sofia.com/api/partners/public/meu-parceiro/table-links?table_id=evolution-roulette"

Resposta:

{
  "partner_slug": "meu-parceiro",
  "table_id": "evolution-roulette",
  "iframe_url": "https://provedor.example.com/roulette/evolution-roulette",
  "updated_at": "2026-02-21T13:45:12.123Z"
}

6. Renderização do Iframe

Exemplo mínimo:

<iframe
  src="https://provedor.example.com/roulette/evolution-roulette"
  style="width: 100%; height: 100%; border: 0;"
  allow="autoplay; fullscreen"
  allowfullscreen
></iframe>

Boas práticas:

• Proporção recomendada: 16:9
• Usar container responsivo
• Não injetar scripts no iframe
• Não confiar no conteúdo embutido

7. Comunicação via postMessage (Opcional)

Se o provedor permitir, eventos podem ser trocados via window.postMessage.

Exemplo de listener seguro:

const allowedOrigins = new Set([
  'https://provedor.example.com'
]);
 
window.addEventListener('message', (event) => {
  if (!allowedOrigins.has(event.origin)) return;
  if (!event.data || typeof event.data !== 'object') return;
 
  const { type, data } = event.data;
 
  if (type === 'balance_update') {
    console.log('Saldo atualizado:', data);
  }
});

Regras obrigatórias:

• Validar origin
• Não usar '*' como destino em produção
• Não processar mensagens sem type

8. Segurança

O parceiro é responsável por:

• Garantir que a URL configurada pertence ao provedor correto
• Validar origem em qualquer comunicação cross-window
• Não confiar em dados recebidos via browser
• Não armazenar credenciais no frontend

9. Ambientes

Produção e Sandbox devem possuir:

• URLs distintas
• Credenciais distintas
• Slugs distintos (quando aplicável)

Nunca misturar ambientes.

10. Considerações Arquiteturais

Iframe é:

• Simples
• Rápido de implementar
• Visual

Não é:

• Canal confiável de backend
• Substituto de webhook
• Mecanismo de automação

Para operação robusta, combine Iframe + Webhook.