SmartHub AppsMáquina de aquisição

P9.1 · Vitrine SEO — integração DataForSEO e cache

Depende de P0.3 e P1.1 (precisa do catálogo canônico já sincronizado).

O prompt

Implemente a camada de dados de palavra-chave, no app seo do repo radar. É a peça que sustenta o produto inteiro — sem dado real de busca, isto é só um gerador de texto genérico, e o produto perde a razão de existir.

1. Cliente DataForSEO

Módulo seo/dataforseo.py, com a mesma disciplina dos outros clientes de API do projeto (Meta, Google): autenticação por login e senha (Basic Auth, conforme a API do DataForSEO), backoff em erro, log estruturado de toda chamada, dry_run de primeira classe.

Endpoints a usar (confirme o nome exato e o formato de resposta na documentação atual do DataForSEO antes de codar — a API muda):

2. Modelos

3. Normalização de termo

Antes de consultar cache ou API: minúsculas, sem acento, espaços colapsados, plural reduzido quando trivial. Termos equivalentes ("tênis runner preto" e "Tênis Runner Preto") têm que cair no mesmo registro de cache — escreva o teste que prova isso.

4. Orçamento por plano

Mesmo padrão do OrcamentoCrawl do Radar de Preço: OrcamentoSeo por loja e mês, com teto de chamadas. Ao estourar, a geração para e avisa dentro do app — nunca deixe passar do orçamento do plano.

PlanoDescrições por mêsChamadas de keywordChamadas de SERP
Trial3, uma vez30
Essencial3030 (com cache)0
Pro150150 (com cache)150

5. Custo real — não pule esta parte

O preço por chamada do DataForSEO varia por endpoint e muda com o tempo. Antes de codar o teto acima como definitivo, confirme o custo atual comigo e calcule: custo_por_chamada × chamadas_do_plano precisa caber com folga dentro da margem calculada em docs/02-economia.md (68% no Pro — a mais apertada do catálogo). Se não couber, pare e me avise antes de continuar — é a mesma disciplina já usada para custo de proxy no Radar de Preço.

Critérios de aceite

  1. Teste de normalização de termo com acento, plural e caixa mista caindo no mesmo cache
  2. Teste de que a segunda consulta ao mesmo termo, dentro do TTL, não chama a API de novo
  3. Teste do teto de orçamento bloqueando a chamada 31 do plano Essencial
  4. Consulta real a um produto de teste, com o dado de volume de busca e termos relacionados retornado e gravado
  5. ConsultaSeo registrando custo estimado real, comparável à margem projetada
  6. Confirmação explícita comigo do custo por chamada antes de fixar os tetos da tabela acima em produção
© 2026 EcomSmart · Uso interno · pt-BR