Modelos de Integração

Versão: 1.0
Owner: Engenharia SOFIA
Última revisão: 2026
Aplicável a: Dev Integradores, Arquitetura, Produto\

A SOFIA oferece quatro modelos oficiais de integração. A escolha depende de:

• Latência desejada
• Nível de robustez
• Local de processamento (browser vs backend)
• Volume de eventos

Guia de Decisão Rápida

Comparativo Técnico

Iframe

Modelo de embed visual.

• Mantém o usuário dentro da SOFIA (/@partner_slug)
• Ideal para validação rápida
• Não substitui integração backend

Limitações:

• Dependente de políticas do provedor
• Não possui retry
• Não garante entrega de eventos

👉 Ver documentação Iframe

postMessage (Tempo real via iframe)

Complementa o Iframe para troca de eventos no browser.

• Comunicação cross-window
• Baixa latência
• Validação de origin obrigatória
• Assinatura HMAC opcional (recomendada)

Não é confiável para persistência.

👉 Ver documentação postMessage

Webhook (Recomendado para Produção)

Modelo server-to-server.

• Entrega assíncrona
• Retry automático
• Idempotência obrigatória
• Melhor para automação e trilha de auditoria

Padrão recomendado para integrações críticas.

👉 Ver documentação Webhook

API Pull (Enterprise)

Modelo ativo (polling).

• Controle total pelo parceiro
• Ideal para ambientes restritivos
• Requer deduplicação e cursor local

Cuidado com:

• Rate limit
• Custo por volume
• Polling agressivo

👉 Ver documentação API Pull

Recomendações Arquiteturais

Para produção madura:

• Iframe + Webhook → equilíbrio entre experiência visual e robustez backend.
• Webhook isolado → automação pura.
• API Pull + Cache → ambientes corporativos restritivos.

Evite depender exclusivamente de:

• Iframe
• postMessage

Eles são canais de experiência, não de confiabilidade.