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):
- Keyword Data / Google Ads (ou equivalente) — volume de busca mensal e tendência de um termo
- Labs — Related Keywords (ou equivalente) — termos relacionados ao nome do produto
- Labs — SERP (Pro) — quem rankeia hoje para o termo
2. Modelos
- PalavraChaveCache:
termo_normalizado(chave única),volume_busca,tendencia(JSON),termos_relacionados(JSON),atualizado_em. TTL de 30 dias — volume de busca não muda todo dia, e cada consulta ao DataForSEO tem custo real. - SerpCache (Pro):
termo_normalizado,resultados(JSON, top 10),atualizado_em, TTL de 7 dias. - ConsultaSeo:
loja,produto(FK canônico),termo_usado,custo_estimado_centavos,criada_em— para medir o custo real por cliente e confrontar com o preço do plano.
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.
| Plano | Descrições por mês | Chamadas de keyword | Chamadas de SERP |
|---|---|---|---|
| Trial | 3, uma vez | 3 | 0 |
| Essencial | 30 | 30 (com cache) | 0 |
| Pro | 150 | 150 (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
- Teste de normalização de termo com acento, plural e caixa mista caindo no mesmo cache
- Teste de que a segunda consulta ao mesmo termo, dentro do TTL, não chama a API de novo
- Teste do teto de orçamento bloqueando a chamada 31 do plano Essencial
- Consulta real a um produto de teste, com o dado de volume de busca e termos relacionados retornado e gravado
ConsultaSeoregistrando custo estimado real, comparável à margem projetada- Confirmação explícita comigo do custo por chamada antes de fixar os tetos da tabela acima em produção