Ir para o conteúdo

Runbook de Operação Real: Google Ads + ClickBank no Brandvelia

Este guia orienta o operador de tráfego pago na execução real de campanhas com dinheiro real na Brandvelia, garantindo segurança financeira, integridade de tracking e automação ponta a ponta guiada por IA.

1. Conexão da Conta Google Ads (MCC + Conta de Anúncios)

A plataforma opera com acesso via MCC e criação direta de campanhas via API Google Ads v25.

Credenciais e Contas Configuradas:

  • MCC Administradora (Login Customer ID): 872-713-5564 (Brandvelia MCC)
  • Conta de Anúncios (Customer ID): 862-553-8203 (vinicdroid@gmail.com)
  • Modo de acesso: DRAFT_WRITE — "Operar campanhas" (criar pausada, ativar, pausar e ajustar orçamento; ativar e aumentar passam por Meu orçamento)
  • Credencial de OAuth: GOOGLE_ADS_REFRESH_TOKEN_1 (armazenada de forma segura nas variáveis de ambiente do servidor)

Como verificar a conexão:

  1. Abra Conexões (/app/integrations) → cartão Google Ads.
  2. Confira conta, MCC, modo Operar campanhas e a ação de conversão (recurso customers/…/conversionActions/…, tipo Importação de cliques).
  3. Clique em Testar conexão (conta, moeda e conversão). A plataforma lê do Google a moeda e o fuso reais da conta (ex.: BRL) e confere se a ação de conversão está ativa e é de importação de cliques. Sem isso a ativação de campanhas fica bloqueada (ACCOUNT_NOT_VERIFIED / CONVERSION_ACTION_NOT_VERIFIED). Trocar conta ou ação zera a verificação.
  4. O mesmo teste grava a saúde real da API (last_api_ok_at) e lê os pré-requisitos da conta. O cartão mostra “API OK há N min”, “Sem confirmação recente” ou, em vermelho, “Token expirado — gere um novo”. Criar pausada e ativar exigem a API confirmada nos últimos 30 min (o passo 4 roda uma sonda leve quando está vencida). Pausar nunca é bloqueado.

Renovar o token do Google Ads

Quando o cartão mostrar “Token expirado — gere um novo” (GOOGLE_ADS_TOKEN_REVOKED):

  1. No Google Cloud Console do client OAuth, confirme “Status de publicação: Em produção” (em Teste o token expira em 7 dias) e a Google Ads API habilitada.
  2. No OAuth Playground → engrenagem → “Use your own OAuth credentials” com o MESMO Client ID/Secret da Vercel. Se aparecer redirect_uri_mismatch, adicione https://developers.google.com/oauthplayground nas URIs autorizadas de um client do tipo Web.
  3. Se o client for do tipo Desktop, crie um client Web (ou use o fluxo local do exemplo oficial) e atualize também GOOGLE_ADS_CLIENT_ID e GOOGLE_ADS_CLIENT_SECRET junto com o token: o refresh token fica preso ao client que o gerou.
  4. Escopo https://www.googleapis.com/auth/adwords, entrando com a conta que administra a MCC 872-713-5564.
  5. “Exchange authorization code for tokens” e copie o refresh token (começa com 1//). Nunca cole o token em chat ou e-mail.
  6. Vercel → Settings → Environment Variables → edite GOOGLE_ADS_REFRESH_TOKEN_1 em Production (e Preview/Development) → redeploy de produção.
  7. Volte em Conexões e clique em Testar conexão.

Trocar a Referência de Credencial no formulário NÃO renova o token.

Pré-requisitos da conta

“Testar conexão” (e o cron, 1×/dia por conexão) lê a conta. Um campo que não pôde ser lido aparece como “Não foi possível conferir” (aviso *_UNKNOWN), nunca como OK.

Código Bloqueia Como resolver
ACCOUNT_PREREQUISITES_NOT_CHECKED ativar (aviso ao criar) Clique em “Testar conexão”.
ACCOUNT_IS_MANAGER criar e ativar Use o ID da conta de anúncios, não o da MCC.
CUSTOMER_NOT_ENABLED criar e ativar Confira o status da conta no Google Ads.
EU_DECLARATION_MISSING_ON_ACCOUNT criar e ativar Declare “Não contém publicidade política da UE” em cada campanha.
TEST_ACCOUNT ativar (aviso ao criar) Use a conta real: contas de teste nunca veiculam.
AUTO_TAGGING_OFF ativar (aviso ao criar) Administrador → Configurações da conta → Codificação automática.
BILLING_NOT_APPROVED ativar (aviso ao criar) Faturamento: aprove a forma de pagamento.
BILLING_APPROVED_HELD não (aviso) Faturamento aprovado mas retido: confira em Faturamento se os anúncios não veicularem.
DEVELOPER_TOKEN_NOT_APPROVED criar e ativar MCC → Administrador → Central de API → “Solicitar acesso básico”.
GOOGLE_API_HEALTH_STALE criar e ativar “Verificar de novo” no passo 4 ou “Testar conexão”.
CONVERSION_COUNTING_ONE_PER_CLICK, CONVERSION_ACTION_SECONDARY, CONVERSION_LOOKBACK_SHORT não (aviso ao ativar) Ajuste a ação de conversão no Google Ads.

Códigos de erro do Google → ação

Código Ação na tela
GOOGLE_ADS_REQUEST_INVALID, GOOGLE_CAMPAIGN_NAME_CONFLICT, códigos do builder (GOOGLE_KEYWORD_*, RSA_COPY_INVALID…) em criar pausada Voltar aos anúncios: corrija e salve de novo (novo envio). A DLQ de validação não é reenviada (COMMAND_NEEDS_NEW_ADS).
GOOGLE_ADS_REQUEST_INVALID em ativar, pausar ou orçamento Abrir no Google Ads (com o código do Google) e Tentar agora. Pausar nunca tem o reenvio recusado.
GOOGLE_ADS_TOKEN_REVOKED, GOOGLE_ADS_CREDENTIALS_MISSING Gerar novo token (passo a passo acima).
GOOGLE_ADS_AUTH_ERROR, GOOGLE_ADS_OAUTH_CLIENT_INVALID, GOOGLE_ADS_DEVELOPER_TOKEN_NOT_APPROVED, GOOGLE_ADS_CUSTOMER_NOT_ENABLED, GOOGLE_ADS_PERMISSION_DENIED Abrir Conexões. “Já resolvi — tentar de novo” só aparece quando a readiness mostra a conexão saudável.
GOOGLE_ADS_NETWORK_ERROR, GOOGLE_ADS_HTTP_ERROR, GOOGLE_ADS_QUOTA_EXHAUSTED O sistema tenta de novo sozinho; Tentar agora antecipa.

“Validar no Google” (passo 4) usa validateOnly — nada é criado no Google Ads — e lista os erros por item. “Criar campanha pausada” roda a mesma validação antes; se o Google recusar, nenhum comando é criado. Um 400 de validação no envio real vai para a DLQ na 1ª tentativa, com google_error_code e google_field_path nos diagnósticos.

2. Presell & Proteção Contra Perda de Vendas (Tracking First-Party)

Para que nenhuma comissão seja perdida no ClickBank e o tráfego do Google Ads seja rastreado com precisão cirúrgica:

O que foi implementado e blindado:

  1. Isenção de Erro 404 no Middleware: As rotas públicas /lp/{slug} (ex: https://brandvelia.com/lp/slug) são servidas diretamente pelo Next.js sem reescrita para /app, eliminando qualquer erro 404 em acessos de visitantes.
  2. Cookies First-Party de 90 Dias:
  3. bv_session_id e bv_click_id são persistidos com Max-Age=7776000 (90 dias), SameSite=Lax e Secure.
  4. Garantem que visitantes que retornam dias depois continuem atribuídos à sua campanha e ao seu lead.
  5. Delegação Nativa de Cliques no Documento:
  6. Eventos de clique em qualquer botão ou link para o ClickBank (*.pay.clickbank.net ou HopLink) são interceptados dinamicamente via document.addEventListener.
  7. O parâmetro extclid (ID único de rastreamento) é injetado no link de checkout.
  8. Os parâmetros gclid, gbraid e wbraid da URL do Google Ads são preservados no checkout.
  9. Conferência antes de publicar: no passo 2 do lançamento, Ver como ficou abre o preview da pressel; a lista de pendências (aviso de afiliado, links legais, promessas proibidas, scripts inseguros) precisa estar vazia para Publicar pressel.

3. Lançamento (passo a passo)

Guia completo e curto: manual-operador.md. Resumo:

  1. Ofertas (/app/radar) → Lançar na linha da oferta (ou Continuar se já existe preparação para ela).
  2. Produto — confirme a política de tráfego do produtor (Google Search permitido + link de evidência).
  3. Pressel — Importar página (URL de vendas já preenchida) → revisar → Publicar pressel. A cópia é determinística; seu link de afiliado substitui os botões de compra.
  4. Anúncios e orçamento — Gerar anúncios com IA (títulos ≤ 30, descrições ≤ 90, palavras-chave e negativas a partir do nome do produto). Orçamento sugerido = metade da comissão por dia, convertida para a moeda da conta e limitada por Meu orçamento.
  5. Conferir e criar no Google — Criar campanha pausada no Google: comando idempotente no outbox, entregue na hora (ou pelo cron em minutos). A tela espera o Google confirmar PAUSED — nada é gasto.
  6. Ativar — a lista "Antes de ativar" confere Meu orçamento, cotação do dólar (≤ 7 dias), aviso de venda do ClickBank recebido, conversão verificada e teto diário. Só então Ativar e começar a gastar.

3.1 Proteção do dinheiro

  • Meu orçamento (Dinheiro): teto por dia, máximo por campanha, verba de teste, stop-loss (× comissão) e aumento máximo em 24h. Imposto no banco: ativar ou aumentar orçamento acima dos limites é recusado.
  • Controle de gasto (/api/cron/traffic-control, a cada 15 min): pausa sozinho e avisa no Telegram quando o teto do dia estoura, a verba de teste acaba ou uma campanha gasta o stop-loss sem venda líquida.
  • Pausar tudo (topo da tela): pausa todas as campanhas no Google na hora e bloqueia ativações até ser desligado. Pausar nunca é bloqueado.

4. Ingestão de Vendas e Fechamento Contábil

  • INS 8.0 Webhook: Cada venda, cancelamento ou rebill dispara notificação para https://brandvelia.com/api/webhooks/clickbank.
  • Atribuição: o extclid recebido no webhook liga a venda à visita. A campanha vem do ID da campanha Google (utm_campaign={campaignid} da visita) ou do vínculo pressel → campanha gravado ao salvar os anúncios (passo ADS); depois nome e pack READY. Ambiguidade fica nula e uma falha do resolvedor nunca derruba a venda. Com gclid na URL, a visita é gravada no servidor mesmo com bloqueador de anúncios.
  • Conferência: em Conexões, o card INS mostra o mini-painel Última venda (atribuída · gclid · enviada ao Google, ou o motivo em pt-BR) e a conferência diária do QuickStats, com divergência por dia. Cada sync do QuickStats registra uma verificação de integridade (deduplicada em 6 h).
  • Rebill: não é enviado ao Google (SKIP_REBILL_NOT_UPLOADED); o reembolso de um rebill não retrata o PURCHASE original.
  • Rebill nas métricas: entra na receita (somas), mas não conta como conversão nova no Início nem no Financeiro (contagens excluem subtype = 'rebill').
  • Eventos antigos com falha de recibo repetido: antes da migration 20260927120400_brandvelia_clickbank_transaction_external_ref, todo rebill/reembolso/chargeback de um recibo já vendido falhava com SQLSTATE_23505_uq_transactions_workspace_external_ref. Se aparecer algum evento INS assim (hoje não há nenhum em produção), use Tentar de novo em Conexões → Avançado (bv_retry_clickbank_ingestion_event) em ordem cronológica (venda → rebill → reembolso), para cada evento encontrar o lançamento original.
  • Ledger Imutável: As transações são registradas em SQL e alimentam o dashboard com Lucro Líquido e ROAS real.
  • Moedas: o gasto do Google (BRL) é convertido para USD pela cotação informada em Meu orçamento (fx_rate_snapshots); lançamentos sem cotação aparecem como "sem câmbio", nunca somados como USD.