Solução de Problemas

Enfrentando problemas? Não se preocupe - a maioria tem soluções simples! Encontre seu problema abaixo e siga a solução.

Verificação do Webhook Falha

Erro: "The callback URL or verify token couldn't be validated."

Possíveis Causas e Soluções:

#	Causa	Solução
1	URL não é HTTPS	Instale um certificado SSL no seu servidor
2	Erro de digitação na URL de callback	Copie e cole diretamente das configurações do módulo
3	Erro de digitação no verify token	Copie e cole diretamente das configurações do módulo
4	Servidor está bloqueando requisições	Verifique seu firewall / plugins de segurança
5	Problemas de redirecionamento .htaccess	Certifique-se de que a URL não redireciona (sem problemas de www ↔ non-www)
6	Selecionou "User" em vez de "Page"	Altere o dropdown para "Page" nos webhooks do Facebook

Como Depurar:

1. Abra seu navegador e visite sua URL do webhook diretamente:

   https://yourcrm.com/facebookleadsintegration/webhook?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=test123

2. Se funcionando corretamente, você deve ver test123 exibido na página
3. Se você vir uma página de erro, o problema está no seu servidor

dica

Ainda não funciona? Verifique os logs de erro do servidor em /path/to/your/crm/application/logs/

Erro "Invalid Scopes" Durante Login no Facebook

Erro: "Invalid Scopes: pages_manage_metadata"

Solução:

Isso significa que o módulo está solicitando uma permissão obsoleta. Certifique-se de usar a versão mais recente do módulo (v2.0.0+), que usa as permissões corretas:

• pages_show_list
• pages_read_engagement
• leads_retrieval
• pages_manage_ads
• ads_management

Atualize seu módulo para a versão mais recente.

"Error Accessing App" / "App Not Active"

Erro: Ao tentar conectar com o Facebook, você vê "Error Accessing App" ou "The app is not active."

Possíveis Causas e Soluções:

#	Causa	Solução
1	App ID errado nas configurações do módulo	Verifique se o App ID corresponde ao seu Meta App
2	App foi excluído ou desativado	Verifique seu app em developers.facebook.com/apps
3	Você não é admin/desenvolvedor do app	Adicione-se em App Roles → Roles
4	Restrições do app	Verifique App Settings → Basic → App Restrictions

Lead de Teste Funciona mas Leads Reais Não Chegam

O botão "Send Test Lead" do módulo funciona, mas leads reais do Facebook não aparecem.

Verifique Estes Itens:

#	Verificação	Como
1	Sua Page está inscrita?	Settings → Connected Pages → Deve mostrar "Monitoring"
2	O webhook está verificado?	Settings → Connection Status → Webhook deve estar verde
3	"leadgen" está inscrito?	Meta App → Webhooks → Page → "leadgen" deve estar marcado
4	O anúncio usa a Page correta?	Ads Manager → Ad Set → Certifique-se de que usa a Page inscrita
5	O anúncio está rodando?	Ads Manager → Status da campanha deve ser "Active"

Teste com a Ferramenta do Facebook:

Use o Lead Ads Testing Tool para enviar um lead de teste real do webhook. Se isso funcionar mas os anúncios reais não, o problema provavelmente está na configuração da sua campanha de anúncios.

Erro 500 nas Páginas do Módulo

Sintoma: As páginas do módulo mostram uma página em branco ou "500 Internal Server Error"

Soluções:

1. Verifique os logs de erro do PHP:

   /path/to/your/crm/application/logs/log-YYYY-MM-DD.php

2. Causas comuns:

   • Versão PHP muito antiga (precisa 7.4+)
   • Extensões PHP faltando (cURL, JSON)
   • Permissões de arquivo incorretas
   • Arquivos do módulo corrompidos durante o upload

3. Corrija as permissões dos arquivos:

   find /path/to/modules/facebookleadsintegration -type f -exec chmod 644 {} \;
   find /path/to/modules/facebookleadsintegration -type d -exec chmod 755 {} \;

4. Re-envie o módulo se os arquivos podem estar corrompidos

Botão Copy Não Funciona

Sintoma: Clicar no botão "Copy" ao lado da URL do webhook ou verify token não faz nada.

Solução:

• Certifique-se de que seu CRM é acessado via HTTPS - a API de clipboard requer um contexto seguro
• Tente selecionar manualmente o texto e pressionar Ctrl+C
• Verifique o console do navegador para erros JavaScript (F12 → aba Console)

Leads Presos em "Pending Retry"

Sintoma: O Sync History mostra leads com status "Pending" que não estão sendo processados.

Soluções:

1. Processar manualmente: Vá para Sync History → Clique em "Process Retry Queue"
2. Verifique o cron: A retry queue processa automaticamente via o cron job do Perfex CRM
   • Certifique-se de que seu cron job está rodando: Setup → Settings → Cron Job
   • A URL do cron deve ser chamada a cada 5 minutos
3. Verifique a mensagem de erro no Sync History para saber por que o lead falhou inicialmente

Access Token Expirado

Sintoma: O teste de conexão falha com "Token expired" ou os leads param de chegar.

Solução:

O módulo troca tokens de curta duração por tokens de longa duração (válidos por ~60 dias). Para atualizar:

1. Vá para Meta Leads → Settings
2. Role até Connected Pages
3. Clique em "Connect with Facebook" novamente
4. Faça login e conceda permissões
5. O token é automaticamente atualizado

dica

Defina um lembrete para reconectar a cada 50 dias para manter o token atualizado!

Campos Não Mapeando Corretamente

Sintoma: Os dados do lead aparecem nos campos errados ou estão faltando.

Passos de Debug:

1. Vá para Sync History → Clique em um registro de lead para ver os dados brutos
2. Verifique quais nomes de campos o Facebook está enviando
3. Vá para Field Mapping → Certifique-se de que o nome do campo do Facebook corresponde
4. Lembre-se: Campos padrão (email, full_name, phone_number) mapeiam automaticamente

Problemas Comuns de Nome de Campo:

O que Você Espera	O que o Facebook Envia	Solução
name	full_name	Já mapeado automaticamente
phone	phone_number	Já mapeado automaticamente
company	company_name	Já mapeado automaticamente
budget	custom_question_1	Crie um mapeamento personalizado

Módulo Não Aparece Após Instalação

Soluções:

1. Verifique a localização dos arquivos: A pasta do módulo deve estar em modules/facebookleadsintegration/
2. Verifique o nome do arquivo: O arquivo principal deve ser facebookleadsintegration.php (tudo minúsculo)
3. Ative o módulo: Vá para Setup → Modules → Clique em Activate
4. Verifique as permissões: Os arquivos devem ser legíveis pelo servidor web (644 para arquivos, 755 para diretórios)

Problemas Específicos do Servidor

Usuários Cloudflare

Se usar Cloudflare, libere os IPs do webhook do Facebook:

1. Vá para Cloudflare → WAF (Web Application Firewall)
2. Crie uma regra para Permitir requisições do Facebook
3. Ou adicione estes à sua whitelist do firewall:
   • Os IPs do webhook do Facebook podem ser encontrados em: https://developers.facebook.com/docs/sharing/webmasters/getting-started/webhooks/

Usuários Nginx

Certifique-se de que sua configuração do Nginx permite requisições POST para a URL do webhook e não bloqueia o User-Agent do Facebook.

Hospedagem Compartilhada

A maioria das hospedagens compartilhadas funciona bem. Se tiver problemas:

• Verifique se allow_url_fopen está habilitado no PHP
• Verifique se a extensão cURL está instalada
• Verifique se seu host bloqueia webhooks recebidos (alguns hosts focados em segurança fazem isso)

Ainda Precisa de Ajuda?

Se nenhuma das soluções acima resolver seu problema:

1. Verifique os logs de erro do Perfex CRM
2. Verifique o Sync History do módulo para mensagens de erro
3. Tire um screenshot de qualquer mensagem de erro
4. Entre em contato em [email protected] com:
   • Sua versão do Perfex CRM
   • Versão do PHP
   • A mensagem de erro
   • Passos para reproduzir o problema

Verifique a FAQ para mais respostas FAQ