README

Módulo para Adobe Commerce, Magento Open Source e ecossistemas compatíveis (ex.: Mage-OS) que permite login e registo de clientes via WhatsApp, usando código OTP enviado pela API do serviço WApp Login.

O módulo foi pensado para arquitetura headless: o storefront pode ser PWA, app móvel, Next.js, Vue, React ou qualquer cliente HTTP — a loja expõe operações GraphQL documentadas abaixo, sem depender do tema Luma ou de blocos PHP no frontend.

Repositório: github.com/fhsconsulting/magento-whatsapp-login

O que o módulo faz

1. Verificação de número — pergunta ao serviço remoto se o telefone está registado no WhatsApp (útil para validar o input antes de pedir OTP).
2. Envio de OTP — gera um código de seis dígitos (formato 000-000), envia a mensagem pela instância WhatsApp; só após o envio ser aceite pela API o módulo cria o customer no Magento (se ainda não existir), grava o OTP em cache com TTL configurável e conta o rate limit.
3. Login — após o cliente introduzir o código correto, o módulo valida o OTP (uso único, expiração), associa o número a um customer no Magento (criação automática se ainda não existir no website) e devolve um CustomerToken igual ao fluxo clássico de token de cliente — o frontend usa Authorization: Bearer <token> nas queries/mutations GraphQL do customer.

No Admin, configura-se Base URL, API Key, OTP (validade, texto da mensagem com {{code}}, rate limit), ligar/desligar o login por loja e o painel de instância WhatsApp (pareamento da instância que envia as mensagens).

API Key e serviço remoto

É obrigatório possuir uma chave API (API Key) fornecida pela FHSConsulting / suporte do módulo. Sem chave válida e Base URL corretas, as chamadas ao servidor da API WApp Login falham e o envio de mensagens não funciona.

A API Key é guardada encriptada no Magento (Stores → Configuration → WApp Login → Credenciais → API Key) e é enviada no header apikey nas integrações HTTP do módulo.

Licença e teste gratuito

Requisitos

• PHP ^8.1
• Módulos Magento (referência no composer.json do pacote): Magento_GraphQl, Magento_StoreGraphQl, Magento_CustomerGraphQl, framework, customer, config, store, backend, integration, authorization, etc.

Instalação

O pacote pode ser instalado facilmente via Composer, na raiz do projeto Magento:

composer require fhsconsulting/module-wapp-login

Depois, ative o módulo e aplique as alterações de esquema / DI:

bin/magento module:enable FHSConsulting_WAppLogin
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Instalação manual (alternativa): copie o código para app/code/FHSConsulting/WAppLogin e execute os mesmos comandos bin/magento acima.

Configuração no Admin

Stores → Configuration → General → WApp Login (separador Service; recurso ACL FHSConsulting_WAppLogin::instance).

Use o scope (Default / Website / Store View) no topo da página para multi-loja; o GraphQL respeita a loja indicada pelo header Store e, opcionalmente, o campo store nos inputs (deve coincidir com esse header).

GraphQL e arquitetura headless

O endpoint padrão do Magento é:

POST /graphql
Content-Type: application/json
Store: <codigo_da_store_view>

• Store — código da store view (ex.: default, pt_br). Todas as operações deste módulo usam o contexto de loja para configuração, website do cliente e ligação à instância.
• Authorization — não é necessário para enviar OTP ou verificar número; após wappLoginWithWhatsApp, envie Authorization: Bearer <token> para APIs de cliente.

O schema adiciona uma query e duas mutations (ver etc/schema.graphqls). Os tipos CustomerToken, String, Int, etc. seguem o schema nativo do Magento_CustomerGraphQl onde aplicável.

Tipos e enums (resumo)

Query: wappLoginIsWhatsAppNumber

Objetivo: saber se o número está registado no WhatsApp, antes de pedir OTP (melhora UX e reduz pedidos inúteis).

Argumentos

Regras

• Login via WhatsApp tem de estar habilitado na loja do pedido.
• Telefone normalizado: 8 a 15 dígitos (número internacional). Caso contrário: erro de input GraphQL.

Exemplo

query CheckWhatsApp($phone: String!) {
  wappLoginIsWhatsAppNumber(phone: $phone) {
    is_whatsapp
  }
}

Variáveis:

{ "phone": "5551987654321" }

Resposta típica

{
  "data": {
    "wappLoginIsWhatsAppNumber": {
      "is_whatsapp": "YES"
    }
  }
}

Mutation: wappLoginSendVerificationCode

Objetivo: gerar OTP, pedir o envio da mensagem pela instância WhatsApp e, somente se o envio for bem-sucedido, criar o customer no website (se necessário, com email sintético), gravar o OTP em cache e aplicar o rate limit. Se a API falhar (rede, número inválido, etc.), não é criado customer nem OTP válido no cache.

Input: WappLoginSendCodeInput

Comportamento de status

• SENT — código válido foi gerado; expires_in_seconds reflete o TTL configurado (ex.: 60).
• RATE_LIMITED — excedeu o máximo de envios por número e loja na janela configurada; expires_in_seconds está alinhado à janela (ex.: 3600 s). Não gera novo OTP nesse pedido.

Exemplo

mutation SendCode($input: WappLoginSendCodeInput!) {
  wappLoginSendVerificationCode(input: $input) {
    status
    expires_in_seconds
  }
}

Variáveis:

{
  "input": {
    "phone": "5551987654321"
  }
}

Resposta típica

{
  "data": {
    "wappLoginSendVerificationCode": {
      "status": "SENT",
      "expires_in_seconds": 60
    }
  }
}

Erros comuns: loja com login desativado, telefone inválido, falha de API/remota (mensagem localizada no GraphQL).

Mutation: wappLoginWithWhatsApp

Objetivo: validar o código recebido por WhatsApp (6 dígitos, com ou sem hífen), consumir o OTP (uso único) e devolver o token de sessão do customer, equivalente ao obtido com generateCustomerToken no schema padrão.

Input: WappLoginWithWhatsAppInput

Resposta: CustomerToken! com campo token.

Exemplo

mutation LoginWithWapp($input: WappLoginWithWhatsAppInput!) {
  wappLoginWithWhatsApp(input: $input) {
    token
  }
}

Variáveis:

{
  "input": {
    "phone": "5551987654321",
    "code": "123-456"
  }
}

Uso do token (headless)

POST /graphql
Authorization: Bearer <token>
Store: default
Content-Type: application/json

Depois disso, o cliente pode chamar customer, cart, wishlist, etc., conforme as permissões do schema GraphQL da sua instalação.

Erros: código incorreto ou expirado, login desativado, falhas de autenticação — o resolver traduz para exceções GraphQL adequadas (GraphQlAuthenticationException / GraphQlInputException).

Fluxo recomendado no frontend (headless)

1. Opcional: wappLoginIsWhatsAppNumber → se NO, avisar o utilizador.
2. wappLoginSendVerificationCode → mostrar countdown com expires_in_seconds; tratar RATE_LIMITED com mensagem clara.
3. Utilizador insere o código recebido no WhatsApp.
4. wappLoginWithWhatsApp → guardar token (memória segura / storage da app).
5. Incluir Authorization: Bearer em todos os pedidos GraphQL autenticados.

Notas técnicas

• Provisionamento de cliente: o módulo identifica o utilizador por um email sintético derivado do website + número; o customer é criado apenas depois de o WhatsApp/API confirmarem o envio do OTP com sucesso (com dados mínimos configurados no código).
• Cache: OTP e rate limit usam o cache do Magento; em ambientes com vários nós, o cache deve ser partilhado (Redis, etc.) para comportamento consistente.
• GraphQL e escalares: o módulo inclui integração com o registo de tipos GraphQL do Magento (compatibilidade com versões que expõem escalares built-in via TypeRegistry).

Suporte

• Email / licenças / API Key: contacto indicado no composer.json do pacote e links WhatsApp acima.
• Código-fonte e issues: github.com/fhsconsulting/magento-whatsapp-login

Licença do software (código)

O pacote declara OSL-3.0 e AFL-3.0 no composer.json. A licença comercial de uso do serviço (R$ 197/mês) é independente e contratada junto da FHSConsulting.

Documentação alinhada ao módulo FHSConsulting_WAppLogin — WApp Login.