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 Shield

Atualizado em 29 de abril de 20263 visualizações

Troubleshooting: Funnel Shield

Funnel Shieldé 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 Shield?

  1. Instalação: Você instala o arquivo aprovei-funnel-shield.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 (?_flshield=TOKEN)
        ↓ Sim
        Valida token via API /api/funnel-shield/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 Shield"

  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-shield/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-shield/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 Shield

  • 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-shield.php';

Isso criará um arquivo ./.aprovei-funnel-shield.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_shield_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-shield

  2. Filtre por campanha, reason ou data

Via SQL:

SELECT
    reason,
    COUNT(*) as total,
    country,
    asn
FROM funnel_shield_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 Shield 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 Shield 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 Shield 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 Shield?

Sim, mas use diretórios separados:

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

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

O filename de download é sempre aprovei-funnel-shield.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