AproveiAproveiHub

Como podemos te ajudar?

Encontre tutoriais, guias e respostas sobre o Checkout, Gateway e Shadow da Aprovei.

... artigos·... categorias
AproveiAproveiShadow

Tutoriais e guias completos

Troubleshooting: Funnel Pass

Atualizado em 28 de abril de 20262 visualizações

Troubleshooting: Funnel Pass

Funnel Pass é um sistema de proteção server-to-server que valida tráfego legítimo usando tokens HMAC. Este guia cobre os problemas mais comuns e suas soluções.

Índice

  1. Visão Geral
  2. Erros Comuns
  3. Debug Mode
  4. Logs de Violação
  5. FAQ

Visão Geral

Como funciona o Funnel Pass?

  1. Instalação: Você instala o arquivo aprovei-funnel-pass.php no seu servidor
  2. Token Generation: O sistema gera um token único HMAC-assinado
  3. Validação: O SDK valida o token server-to-server com a API da Aprovei
  4. Fingerprint: Usa IP + User-Agent + Accept-Language para prevenir replay attacks
  5. Cache: Cache local (30 min) + cache remoto de tentativas negativas (60s)

Fluxo de validação

Request → Cookie HMAC válido?
    ↓ Não
    Token na query string (?_flpass=TOKEN)
        ↓ Sim
        Valida token via API /api/funnel-pass/verify
            ↓ Sucesso
            Define cookies + redireciona para URL limpa
            ↓ Falha
            Redireciona para FALLBACK_URL

Erros Comuns

1. Placeholder não substituído

Sintoma: Log mostra "APROVEI_SECRET nao configurado" ou similar

Causa: O arquivo PHP foi baixado mas as variáveis {{CAMPAIGN_ID}}, {{VERIFY_URL}}, etc. não foram substituídas

Solução:

  1. Acesse o painel da campanha
  2. Vá em "Funnel Pass"
  3. Baixe novamente o arquivo PHP
  4. Verifique se as constantes estão preenchidas: 
    define('APROVEI_CAMPAIGN_ID', 'cmp_123abc'); // ← ID visível
define('APROVEI_VERIFY_URL',  'https://api.aprv-edge.com/api/funnel-pass/verify');
define('APROVEI_SECRET',      'base64encodedsecret...');

2. Token expirado

Sintoma: Usuário é redirecionado para fallback mesmo com token válido na URL

Causa: Tokens têm TTL curto (configurado na geração) e expiram após o período

Solução:

  • Tokens one-shot são descartáveis após uso
  • Se o usuário tentar reutilizar o mesmo token, será rejeitado
  • Gere um novo token quando necessário

Log de violação: reason: "expired"

3. Fingerprint mismatch

Sintoma: Token válido mas validação falha com erro de fingerprint

Causa: O fingerprint (hash de IP+UA+Accept-Language) mudou entre geração e validação

Cenários comuns:

  • Usuário acessou de VPN e depois desconectou
  • Mudança de IP (ex: WiFi → 4G)
  • User-Agent mudou (update de browser)
  • Diferença de IP entre proxy e origem

Solução:

  • O fingerprint usa IP anonimizado (/24 para IPv4, /48 para IPv6)
  • Pequenas variações de IP são toleradas
  • Se problema persiste, verifique configuração de proxy/reverse proxy

Log de violação: reason: "fingerprint_mismatch"

4. Replay attack detectado

Sintoma: Segunda tentativa com mesmo token é rejeitada

Causa: Token já foi usado anteriormente (proteção contra replay)

Solução:

  • Design one-shot: tokens só podem ser usados uma vez
  • Cada acesso requer um novo token
  • Não há como reutilizar tokens

Log de violação: reason: "replay"

5. Assinatura inválida

Sintoma: Erro de validação de assinatura HMAC

Causa:

  • Secret da campanha mudou (rotação)
  • Arquivo PHP desatualizado com secret antigo
  • Token manipulado/alterado

Solução:

  1. Baixe novamente o arquivo PHP após rotação de secret
  2. O sistema suporta duas secrets simultâneas (atual + anterior) para transição suave
  3. Não edite manualmente o token

Log de violação: reason: "invalid_signature"

6. Erro de curl/rede

Sintoma: Todas as validações falham, logs de debug mostram erro curl

Causa:

  • curl não disponível no PHP
  • Firewall bloqueando request para API
  • Timeout de conexão
  • DNS falhando

Solução:

# Verificar se curl está habilitado
php -i | grep curl

# Testar conectividade
curl -v https://api.aprv-edge.com/api/funnel-pass/verify

# Verificar permissões do diretório de cache
ls -la .aprovei-cache/
# Deve ser gravável pelo usuário do PHP (chmod 0700)

Log de debug: "curl erro N" onde N é o código de erro curl

7. Permissões de diretório

Sintoma: Erro ao criar cache ou logs de debug

Causa: Diretório .aprovei-cache/ não pode ser criado/escrito

Solução:

# Criar manualmente com permissões corretas
mkdir -p .aprovei-cache
chmod 0700 .aprovei-cache
chown www-data:www-data .aprovei-cache  # ajuste para seu usuário PHP

8. Token inválido/malformado

Sintoma: Erro "invalid" na resposta da API

Causa:

  • Token corrompido na URL (encoding errado)
  • Token incompleto
  • Query string malformada

Solução:

  • Token deve conter 3 partes separadas por .: payload.signature.nonce
  • Use urlencode() ao montar URLs em PHP

Log de violação: reason: "invalid_token"

9. Subscription inactive

Sintoma: API retorna {"error": "subscription_inactive"}

Causa: Assinatura do usuário não está ativa ou em grace period

Solução:

  • Verifique status da assinatura no painel
  • Planos inativos não podem validar tokens Funnel Pass
  • Renove ou atualize o plano para reativar

Debug Mode

Para ativar logs detalhados, adicione antes do require_once:

<?php
define('APROVEI_DEBUG_LOG', true);
require_once __DIR__ . '/aprovei-funnel-pass.php';

Isso criará um arquivo ./.aprovei-funnel-pass.log com mensagens como:

2026-04-27T10:30:45+00:00 Token validado com sucesso
2026-04-27T10:30:46+00:00 curl erro 7
2026-04-27T10:30:47+00:00 APROVEI_SECRET nao configurado

⚠️ IMPORTANTE: Desative debug em produção após diagnóstico!

Logs de Violação

O sistema registra automaticamente todas as tentativas falhas de validação em funnel_pass_violations.

Campos registrados:

  • campaign_id — ID da campanha
  • ip — IP de origem
  • ua — User-Agent (truncado em 512 chars)
  • reason — Motivo da falha (expired, invalid_signature, replay, fingerprint_mismatch, invalid_token, unknown)
  • asn — ASN (se disponível)
  • country — País (se disponível)
  • fingerprint — Hash de identificação
  • created_at — Timestamp

Como consultar

Via painel admin:

  1. Acesse /admin/funnel-pass
  2. Filtre por campanha, reason ou data

Via SQL:

SELECT
    reason,
    COUNT(*) as total,
    country,
    asn
FROM funnel_pass_violations
WHERE campaign_id = 'cmp_123abc'
  AND created_at > NOW() - INTERVAL '7 days'
GROUP BY reason, country, asn
ORDER BY total DESC;

FAQ

Token Funnel Pass expira?

Sim. O TTL é definido na geração do token (geralmente curto para segurança). Tokens one-shot são invalidados após primeiro uso.

Posso reutilizar um token?

Não. Funnel Pass usa design one-shot: cada token só pode ser validado uma vez. Segundas tentativas retornam replay.

O cookie local substitui a validação remota?

Parcialmente. O cookie HMAC _aprovei_sess (30 min) evita round-trip para requests do mesmo fingerprint. Mudanças de IP/UA invalidam o cookie e forçam nova validação.

Funnel Pass funciona com Cloudflare?

Sim, desde que:

  • Cloudflare não altere headers críticos (User-Agent, Accept-Language)
  • IP original seja preservado (CF-Connecting-IP header)
  • Cache esteja desabilitado para rotas protegidas

Posso usar múltiplos arquivos Funnel Pass?

Sim, mas use diretórios separados:

  • site1.com/.htaccess → require_once __DIR__ . '/fp-site1/aprovei-funnel-pass.php';
  • site2.com/.htaccess → require_once __DIR__ . '/fp-site2/aprovei-funnel-pass.php';

O filename de download é sempre aprovei-funnel-pass.php. Renomeie ao organizar.

O fallback URL é obrigatório?

Sim. Fail-closed design: qualquer falha redireciona para APROVEI_FALLBACK. Configure uma URL segura (página de "em manutenção", offer pública, etc.).

Suporte

Se após este guia o problema persistir:

  1. Ative debug mode e compartilhe os logs
  2. Consulte os logs de violação no painel admin
  3. Verifique status da assinatura
  4. Entre em contato via suporte Aprovei

Última atualização: Abril 2026
Versão do SDK: 2.x
Produto: Aprovei Shadow