Integração WhatsApp com Provedor Zapster API & Controle de Energia
O ecossistema multi-tenant suporta múltiplos provedores de mensageria WhatsApp sob a mesma interface unificada no modal WhatsappInstanceQrModal. Este documento detalha as nuances de integração com o segundo provedor (Zapster API), incluindo o protocolo de ativação prévia de instâncias (power-on), captura de matriz óptica binária e salvaguardas de isolamento em relação à Evolution API.
1. Desafios Arquiteturais do Provedor Zapster API
Diferentemente de instâncias auto-hospedadas ou sempre ativas (como instâncias Baileys locais na Evolution API), a infraestrutura gerenciada da Zapster API opera sob uma política de economia de recursos:
1. Desligamento Automático por Inatividade (Power Down): Instâncias não conectadas que permanecem ociosas por determinado período transitam automaticamente para o estado offline (desligadas).
2. Dependência Mandatória de Ativação (Power-On Requirement): Requisitar a geração de QR Code para uma instância offline resulta em erro ou falha de conectividade. É indispensável acionar o endpoint de controle de energia antes de solicitar a matriz de conexão.
3. Entrega em Stream Binário PNG: O endpoint de QR Code retorna a imagem como payload binário image/png com Content-Type: image/png, exigindo conversão direta pelo BFF para Data URL Base64 (data:image/png;base64,…) para renderização direta em elementos <img> no navegador sem exposição de tokens em query strings.
3. Garantia de Isolamento e Blast Radius Zero
A coexistência harmoniosa entre provedores distintos é garantida pela segregação rígida de papéis:
* EvolutionApiAdapter: Mantido estritamente agnóstico a qualquer comportamento ou lógica da Zapster API. Nenhuma rota, cabeçalho ou tratamento de erro afeta as instâncias evolution.
* ZapsterApiAdapter: Encapsula todo o protocolo REST próprio da Zapster API (/v1/wa/instances/…), garantindo que chamadas power-on, qrcode binário e webhooks com assinatura x-zapster-signature operem isoladamente.
* WhatsappProviderFactory: Instancia e seleciona o adapter apropriado em tempo de execução com base no campo provider_type persistido no schema connect.whatsapp_instances.