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

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).
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.
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

Item	Detalhe
Licença	R$ 197 / mês
Adquirir licença	Abrir WhatsApp — quero adquirir uma licença do módulo WAppLogin
Teste gratuito	7 dias — deve ser solicitado pelo WhatsApp
Solicitar teste	Abrir WhatsApp — quero fazer um teste gratuito do módulo WAppLogin

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).

Grupo	Campos importantes
Geral	Habilitar Login via WhatsApp — quando desligado, as operações GraphQL abaixo recusam o pedido para essa vista de loja.
Código de verificação (OTP)	Validade em segundos (ex.: 60), texto da mensagem com `{{code}}`, máximo de envios por janela e duração da janela (anti-abuso).
Credenciais	Base URL da API, API Key (obtida com o suporte).
Conexão WhatsApp	Painel de instância: criar/ligar a instância que envia as mensagens (fluxo administrativo do módulo).

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)

Nome	Tipo	Significado
`WappLoginWhatsAppYesNo`	enum	`YES` — número com WhatsApp; `NO` — caso contrário.
`WappLoginSendCodeStatus`	enum	`SENT` — código gerado e pedido de envio feito; `RATE_LIMITED` — limite de envios por número/loja na janela configurada.
`IsWhatsAppNumber`	tipo	`is_whatsapp: WappLoginWhatsAppYesNo!`
`WappLoginSendCodeResult`	tipo	`status`, `expires_in_seconds` (segundos até expirar o OTP em `SENT`, ou contexto da janela em `RATE_LIMITED`).
`WappLoginSendCodeInput`	input	`phone` (obrigatório), `store` (opcional).
`WappLoginWithWhatsAppInput`	input	`phone`, `code`, `store` (opcional).
`CustomerToken`	tipo (core)	`token: String` — usar como Bearer nas chamadas seguintes.

Query: `wappLoginIsWhatsAppNumber`

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

Argumentos

Argumento	Tipo	Obrigatório	Descrição
`phone`	`String!`	Sim	Telefone com código do país; espaços e pontuação são ignorados na normalização (ficam só dígitos).

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

Campo	Tipo	Obrigatório	Descrição
`phone`	`String!`	Sim	Mesmo formato que na query: dígitos com país.
`store`	`String`	Não	Código da store view; se enviado, tem de ser o mesmo que o header `Store` do pedido.

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

Campo	Tipo	Obrigatório	Descrição
`phone`	`String!`	Sim	O mesmo número usado no envio do código.
`code`	`String!`	Sim	Ex.: `123456` ou `123-456` — apenas os dígitos são considerados.
`store`	`String`	Não	Mesma regra de consistência com o header `Store`.

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)

Opcional: wappLoginIsWhatsAppNumber → se NO, avisar o utilizador.
wappLoginSendVerificationCode → mostrar countdown com expires_in_seconds; tratar RATE_LIMITED com mensagem clara.
Utilizador insere o código recebido no WhatsApp.
wappLoginWithWhatsApp → guardar token (memória segura / storage da app).
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.

fhsconsulting / module-wapp-login

Maintainers

Package info

Statistics

Security

README

O que o módulo faz

API Key e serviço remoto

Licença e teste gratuito

Requisitos

Instalação

Configuração no Admin

GraphQL e arquitetura headless

Tipos e enums (resumo)

Query: `wappLoginIsWhatsAppNumber`

Mutation: `wappLoginSendVerificationCode`

Mutation: `wappLoginWithWhatsApp`

Fluxo recomendado no frontend (headless)

Notas técnicas

Suporte

Licença do software (código)

fhsconsulting / module-wapp-login

Maintainers

Package info

Statistics

Security

README

O que o módulo faz

API Key e serviço remoto

Licença e teste gratuito

Requisitos

Instalação

Configuração no Admin

GraphQL e arquitetura headless

Tipos e enums (resumo)

Query: wappLoginIsWhatsAppNumber

Mutation: wappLoginSendVerificationCode

Mutation: wappLoginWithWhatsApp

Fluxo recomendado no frontend (headless)

Notas técnicas

Suporte

Licença do software (código)

Query: `wappLoginIsWhatsAppNumber`

Mutation: `wappLoginSendVerificationCode`

Mutation: `wappLoginWithWhatsApp`