Troubleshooting e logs

O plugin tem 3 ferramentas de diagnóstico que cobrem 95% dos problemas:

1. Dashboard de saúde — contadores 7 dias + últimas 10 entradas (admin)
2. Logs em arquivo — wp-content/uploads/smart2-logs/smart2-debug-*.log
3. Teste de conexão — botão na página de settings

Antes de abrir o log: a lista de eventos

A seção Eventos que este site envia costuma responder a dúvida em cinco segundos, sem ler log nenhum.

Ela lista cada tipo de conversão que já saiu deste site, com quantas vezes saiu e quando foi a última. Três leituras rápidas:

O evento não está na lista. Então nunca saiu daqui. O problema é de captura — formulário não reconhecido, fallback desligado, consentimento exigido e não marcado.

Está na lista, mas a última vez foi há muito tempo. Alguma coisa parou de funcionar num dia específico. Compare com a data de alguma mudança no site.

Está na lista, com contagem subindo, e mesmo assim não aparece no CRM. Aí sim é envio: confira se o evento não está marcado como Não aceitar, e depois vá ao log.

Dashboard de saúde

Na página Configurações → app.smart CRM, abaixo dos campos de configuração, há um painel Saúde mostrando:

• Envios OK (últimos 7 dias): quantas submissões viraram lead com sucesso
• Erros (últimos 7 dias): quantas falharam
• Últimas 10 entradas do log: nível (INFO/ERROR/DEBUG), timestamp e mensagem

É a primeira tela a olhar quando algo está estranho.

Logs em arquivo

Localização

wp-content/uploads/smart2-logs/smart2-debug-{16 hex chars}.log

O nome do arquivo é randomizado por segurança (mitigação pra servidor nginx que ignora .htaccess).

Proteção

O diretório vem protegido por:

• .htaccess (Apache: Deny from all)
• index.html vazio (evita listagem)
• web.config (IIS: deny)
• Nome de arquivo randomizado (não-guessable)

Formato

[2026-06-02 14:30:00] [INFO] Envio OK {"account_id":1,"contact_id":7821}
[2026-06-02 14:30:05] [ERROR] Submission failed {"http_code":401,"body":"..."}
[2026-06-02 14:30:10] [INFO] Envio falhou; na fila {"conversion_identifier":"cf7-12","erro":"cURL error 28"}

• Timestamp em UTC
• Nível: INFO / ERROR / DEBUG
• Mensagem livre + JSON opcional com contexto

Rotação

Quando o arquivo atinge 5 MB, é renomeado pra .log.1 (backup anterior é descartado). Mantém só 1 backup — total de até 10 MB consumidos.

Acessar pelo painel

Em Configurações → app.smart CRM, há um botão Ver últimas 200 linhas do log que abre as últimas 200 entradas sem precisar acessar via FTP.

Ler via FTP/SSH

ssh seu-servidor
cat /caminho/wp-content/uploads/smart2-logs/smart2-debug-*.log | tail -100

Erros mais comuns

HTTP 401 — Token inválido ou expirado

Sintoma: todas as submissões falham. Dashboard mostra “0 envios OK, X erros”.

Causa:

• Token de API errado, expirou, foi revogado
• Salts do WordPress foram rotacionadas (token criptografado ficou ilegível)

Solução:

1. Configurações → app.smart CRM.
2. Em Token de Acesso, cole o token novamente (ou gere um novo no app.smart).
3. Clique em Salvar e depois em Testar conexão.

HTTP 422 — Validation failed

Sintoma: algumas submissões falham, outras passam.

Causa: campo obrigatório do CRM ausente ou inválido (email malformado, telefone fora do padrão).

Solução:

1. Veja no log o JSON do body retornado — ele detalha o campo problemático.
2. No CRM, Forms → seu form → Mapear atributos e ajuste se necessário.

Plugin not configured

Sintoma: badge amarelo no admin: “Plugin não configurado”.

Causa: account_id ou api_token vazios.

Solução: preencha os 2 campos em Configurações → app.smart CRM e teste a conexão.

Rate limited (429)

Sintoma: log mostra HTTP 429 repetido.

Causa: pode vir de dois lugares.

• Do plugin: mais de 30 chamadas por minuto do mesmo IP no endereço do plugin (formulário, WhatsApp e pré-coleta somados). O IP é o real do visitante, lido do cabeçalho da Cloudflare quando o site passa por ela.
• Do CRM: o site cadastrado tem cota de 10.000 conversões por hora (a pré-coleta conta nela). Nesse caso o plugin não perde o lead: o envio vai pra fila e tenta de novo em 3 min, 30 min e 2 h.

Cooldowns por feature:

Feature	Limite
Qualquer chamada ao plugin	30 por minuto por IP
Mesmo formulário + mesmo contato	1 a cada 5 segundos
Geo lookup	Cache de 6 horas por IP

Solução: geralmente é bot atacando. Verifique a origem do IP nos logs. Se for tráfego real legítimo (raro), abra ticket no suporte.

No email or phone found in submission

Sintoma: submissão de form pelo fallback JS é rejeitada com esse erro.

Causa: o JS fallback só envia se algum campo tem e-mail ou telefone. Forms de busca, filtros, login etc. são ignorados de propósito.

Solução:

• Se o form deveria ser capturado, certifique-se de ter um campo type="email" ou pelo menos um valor com formato email
• Se o form NÃO deveria ser capturado, adicione classe .smart2-skip no form (em roadmap)

Submissão chega no CRM mas sem UTMs

Sintoma: o lead aparece no CRM mas utm_source, gclid etc estão vazios.

Causas possíveis:

• Visitante chegou direto (sem clicar em anúncio) — sem UTMs na URL, nada pra capturar
• Cookie smart2_utm foi bloqueado pelo navegador (privacy mode extremo)
• Visitante limpou cookies entre a visita do anúncio e a conversão

Solução: garanta que as campanhas estão com tagging UTM correto nas plataformas (Google Ads auto-tagging ligado, Meta com UTMs no parametro URL).

Clique em WhatsApp não dispara nada

Sintoma: botão de WhatsApp funciona (abre o WA), mas nada aparece no log nem no CRM.

Causas:

1. JS bloqueado no navegador do visitante (raro)
2. Adblock bloqueando o admin-ajax.php
3. Rate limit atingido (3 cliques em 5s)

Diagnóstico:

1. Abra DevTools → Network.
2. Clique no link WhatsApp.
3. Procure por admin-ajax.php?action=smart2_track_whatsapp.
4. Se aparece 200 → tracking funciona, problema é no CRM
5. Se aparece 4xx → veja o response body

Cenários específicos

Pré-coleta (lead parcial) não aparece

A pré-coleta manda pro CRM quem digitou e-mail ou telefone e parou, como lead parcial. Ela não depende de a pessoa fechar a aba: dispara 1,5 segundo depois da última tecla. Pra funcionar:

• Recurso ligado: Configurações → app.smart CRM → seção Captura e proteção → Pré-coleta (digitou = enviando). Um formulário específico pode estar desligado com data-smart-precollect="false".
• Aviso mostrado: a pré-coleta só começa depois que o aviso do formulário apareceu (ou, no modo rígido, depois do aceite no banner).
• Contato identificável: e-mail em formato válido ou telefone com 10+ dígitos. Sem isso o CRM descarta o parcial.
• Campo sensível: o que estiver dentro de [data-smart-sensitive] nunca vai na pré-coleta — só no envio final.

No CRM, o parcial aparece na coluna Abandonos de Marketing → Captação → Conversões, sob o mesmo identificador do formulário (cf7-12:parcial, por exemplo). Ele nunca vira conversão e some da coluna quando a pessoa envia de verdade.

Meta CAPI envia mas Pixel não conta como conversão

Quando você tem CAPI + Pixel client-side, ambos chegam no Meta. Se você marcou “Lead” como conversão no Events Manager, só o CAPI vai contar (porque o Pixel não disparou pra esse usuário — adblock, iOS).

Pra evitar duplicar:

1. Configure deduplicação em Events Manager → Settings → Deduplication
2. Ou desligue o Pixel JS pra esse evento específico

GA4 não recebe generate_lead

Sintoma: nada aparece em GA4 Realtime.

Causas:

• Measurement ID errado (deve ser G-XXXXXXXXXX, não UA-XXXXXX-X que é do Universal Analytics antigo)
• API Secret errado (cole novamente)
• Stream do GA4 está pausado/desativado

Diagnóstico:

1. No GA4 → Admin → Data Streams, verifique se o stream está ativo.
2. No log do plugin, procure por GA4 event sent — se aparece status:204 é OK (GA4 retorna 204 sem body)
3. Se aparece status:400, leia o body do log

Hooks pra desenvolvedores

Pra integrações customizadas (logar em outro serviço, disparar webhook externo, etc.):

smart2_conversion_sent

Disparado após sucesso no envio pro CRM. Payload completo:

add_action('smart2_conversion_sent', function($event) {
    // $event['conversion_identifier']  → ex: 'cf7-12'
    // $event['form_name']               → ex: 'CF7 — Contato'
    // $event['fields']                  → array com campos do form
    // $event['metadata']                → UTMs, click_ids, page_url, etc.
    // $event['page_url']                → URL onde aconteceu
    // $event['response']                → resposta do CRM (contact_id, etc.)

    // Exemplo: notificar Slack
    wp_remote_post('https://hooks.slack.com/...', [
        'body' => json_encode([
            'text' => 'Novo lead: ' . $event['form_name']
        ])
    ]);
}, 10, 1);

smart2_whatsapp_clicked

Disparado em clique em link de WhatsApp. Payload:

add_action('smart2_whatsapp_clicked', function($event) {
    // $event['page_url']     → onde o clique aconteceu
    // $event['destination']  → link clicado (https://wa.me/...)
    // $event['label']        → texto do link
    // $event['visitor']      → dados do cookie smart2_visitor (se houver)
    // $event['metadata']     → UTMs/click_ids
});

Reportar bug

Se nada acima resolveu seu problema:

1. Reproduza o erro — uma submissão de teste com erro recente.
2. Copie o trecho relevante do log (sem dados pessoais sensíveis).
3. Abra ticket no suporte com:
   • Versão do plugin (visível em Plugins → linha “app.smart CRM”)
   • Versão do WordPress
   • Versão do PHP
   • Trecho do log
   • URL da página onde aconteceu (se relevante)

Próximos passos

• Visão geral — voltar ao topo
• Configuração — revisar setup
• Documentação da API — alternativa pra integrações fora do WordPress