Auditoria Técnica de SEO com IA

Automatize auditorias de SEO, integre Google Search Console, PageSpeed Insights, DataForSEO e receba recomendações geradas por inteligência artificial.

1. O que é o ia-seo-audit?

O ia-seo-audit é uma ferramenta de linha de comando (CLI) open‑source que realiza auditorias técnicas completas em sites. Ela combina:

• Crawling inteligente – percorre seu site a partir da homepage ou do sitemap.xml, respeitando robots.txt e limites configuráveis.
• Mais de 20 verificações técnicas – status HTTP, tags noindex, canônicas, títulos, meta descrições, H1, imagens sem alt, dados estruturados, conteúdo raso, links quebrados, entre outros.
• Integração com APIs externas – Google Search Console, PageSpeed Insights, DataForSEO e DeepSeek (IA).
• Relatórios ricos – gera um arquivo JSON com todos os dados e um dashboard interativo para visualização.
• Inteligência artificial – a DeepSeek analisa os problemas e sugere ações priorizadas em português do Brasil.

Ele nasceu da necessidade de automatizar auditorias que antes eram feitas manualmente, consumindo horas de trabalho.

2. Por que automatizar auditorias de SEO?

Uma auditoria técnica de SEO é o primeiro passo para melhorar o posicionamento orgânico. Ela identifica:

• Erros de rastreamento e indexação.
• Falhas na estrutura de headings e títulos.
• Problemas de conteúdo (páginas rasas, duplicidade).
• Oportunidades de performance e dados estruturados.

Fazer isso manualmente para um site com dezenas ou centenas de páginas é inviável. O ia-seo-audit resolve esse problema com uma abordagem sistemática, gerando relatórios detalhados e recomendações acionáveis, tudo com um único comando.

3. Pré‑requisitos

• Antes de começar, certifique‑se de ter:
• Node.js versão 18 ou superior (recomendado 20+).
• npm ou yarn para gerenciar dependências.
• Contas ativas nos serviços que você deseja integrar:
  • DeepSeek – para geração de sugestões por IA.
  • Google Cloud – para Search Console e PageSpeed Insights.
  • DataForSEO – para sugestões de palavras‑chave e temas.

4. Instalação e Configuração Inicial

Siga estes passos para obter o projeto em sua máquina:

# Clonar o repositório
git clone https://github.com/reulison/ia-seo-audit.git
cd ia-seo-audit

# Instalar dependências
npm install

# Criar arquivo de variáveis de ambiente a partir do exemplo
cp .env.example .env

O arquivo .env é onde você colocará todas as chaves e credenciais. Abra‑o em seu editor favorito e preencha conforme as seções a seguir.

5. Configuração Detalhada de Cada API

5.1 DeepSeek – A IA do Projeto

A DeepSeek é responsável por gerar recomendações personalizadas em português com base nos problemas encontrados.

1. Acesse platform.deepseek.com e crie uma conta.
2. No painel, vá em API Keys e gere uma nova chave.
3. Copie a chave e adicione no .env:

DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

A ferramenta enviará um prompt estruturado com a lista de issues e pedirá à IA que sugira ações práticas. O resultado aparece no relatório final.

5.2 Google Search Console

O ia-seo-audit pode buscar dados de cliques, impressões, CTR e posição média diretamente da API do Google Search Console. Para isso, utilizamos uma Service Account – o método mais seguro e recomendado para automação entre sistemas.

Por que Service Account em vez de OAuth2 com Refresh Token?

• Mais segura: não requer login interativo nem expõe tokens de usuário.
• Ideal para servidores e CI/CD: funciona sem necessidade de autorização manual.
• Permissões granulares: você define exatamente quais dados a conta pode acessar.

Passo a passo no Google Cloud Console

1. Criar um projeto (ou usar um existente)

   • Acesse console.cloud.google.com.
   • Clique em "Select a project" e depois em "New Project".
   • Dê um nome (ex: ai-seo-audit) e clique em Create.

2. Ativar a Search Console API

   • No menu lateral, vá em APIs & Services > Library.
   • Busque por "Search Console API" e clique em Enable.

3. Criar uma Service Account

   • Vá em APIs & Services > Credentials.
   • Clique em + Create Credentials > Service Account.
   • Dê um nome (ex: vertex-express) e um ID (ex: vertex-express). Clique em Create and Continue.
   • Na etapa Grant this service account access to project, você pode pular (as permissões serão dadas diretamente no Search Console).
   • Clique em Done.

4. Gerar a chave JSON da Service Account

   • Na lista de Service Accounts, clique no e‑mail da conta recém‑criada.
   • Vá na aba Keys.
   • Clique em Add Key > Create New Key.
   • Escolha JSON e baixe o arquivo.
   • ⚠️ Guarde este arquivo com segurança – ele contém uma chave privada!

5. Adicionar a Service Account ao Google Search Console

   • Acesse search.google.com/search-console.
   • Selecione a propriedade (domínio ou URL prefixada) que você deseja auditar.
   • Vá em Configurações > Usuários e permissões.
   • Clique em Adicionar usuário.
   • No campo de e‑mail, cole o client_email que está dentro do arquivo JSON baixado (ex: vertex-express@ai-seo-audit-99999.iam.gserviceaccount.com).
   • Selecione a permissão "Visualizador restrito" (basta para leitura de dados).
   • Clique em Adicionar.

6. Configurar o arquivo .env

   • Mova o arquivo JSON baixado para uma pasta segura dentro do projeto (ex: credentials/).
   • No .env, adicione a variável:

# Google Search Console (required for GSC features)
GOOGLE_APPLICATION_CREDENTIALS=./credentials/ai-seo-audit-123456-abcdef.json

7. No arquivo config.ts, temos:

gsc: {
  credentials: process.env.GOOGLE_APPLICATION_CREDENTIALS || '',
},

Isso permite que o cliente do Search Console seja criado sem necessidade de credenciais OAuth2 manuais, usando a autenticação padrão do Google Cloud.

Exemplo do arquivo JSON (dados fictícios)

{
  "type": "service_account",
  "project_id": "ai-seo-audit-123456",
  "private_key_id": "abc123def456...",
  "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC...\n-----END PRIVATE KEY-----\n",
  "client_email": "seo-audit@ai-seo-audit-123456.iam.gserviceaccount.com",
  "client_id": "123456789012345678901",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/seo-audit%40ai-seo-audit-123456.iam.gserviceaccount.com"
}

Como o código usa essa configuração

No módulo gsc/client.ts, a autenticação é feita automaticamente com as credenciais da Service Account:

import { google } from 'googleapis'

const auth = new google.auth.GoogleAuth({
  scopes: ['https://www.googleapis.com/auth/webmasters.readonly'],
})

const webmasters = google.webmasters({ version: 'v3', auth })

// Depois basta chamar:
const response = await webmasters.searchanalytics.query({
  siteUrl: 'sc-domain:seudominio.com.br',
  requestBody: { ... }
})

A biblioteca google-auth-library localiza automaticamente o arquivo de credenciais apontado por GOOGLE_APPLICATION_CREDENTIALS. Isso torna o código mais limpo e seguro, sem expor chaves no código‑fonte.

6. Estrutura do Projeto e Explicação do Código

Agora que tudo está configurado, vamos entender como o código funciona. A pasta src/ contém todos os módulos:

src/
├── index.ts          # Ponto de entrada da CLI (Commander)
├── config.ts         # Leitura de variáveis de ambiente
├── types.ts          # Interfaces compartilhadas
├── persist.ts        # Salvar/carregar relatório em JSON
├── crawler/
│   └── index.ts      # Crawler com axios + cheerio
├── audit/
│   └── checks.ts     # Função runAudit e calculateScore
├── deepseek/
│   └── client.ts     # Integração com API da DeepSeek
├── gsc/
│   └── client.ts     # Integração com Search Console (googleapis)
├── pagespeed/
│   └── client.ts     # Integração com PageSpeed Insights
├── kwrds/
│   └── client.ts     # Integração com DataForSEO
├── server/
│   ├── index.ts      # Servidor HTTP (Express)
│   └── dashboard.ts  # Geração do HTML do dashboard
└── utils/
    └── index.ts      # parseSitemap, formatDate, truncate

6.1 config.ts – Central de Configurações

O arquivo config.ts exporta um objeto com todas as variáveis de ambiente validadas. Ele usa dotenv para carregar o .env.

import dotenv from 'dotenv'
import path from 'path'

dotenv.config()

export const config = {
  dataDir: process.env.DATA_DIR || 'data',
  crawler: {
    maxPages: parseInt(process.env.MAX_PAGES || '100', 10),
    concurrency: parseInt(process.env.CONCURRENCY || '5', 10),
    timeout: parseInt(process.env.TIMEOUT || '30000', 10),
    userAgent: process.env.USER_AGENT || 'ia-seo-audit/1.0',
    followSitemap: process.env.FOLLOW_SITEMAP !== 'false',
  },
  apiKeys: { ... },
  gsc: { ... },
  server: { port: parseInt(process.env.PORT || '3000', 10) },
}

Isso permite que o usuário ajuste comportamento sem alterar o código, apenas com variáveis de ambiente.

6.2 crawler/index.ts – O Coração da Coleta de Dados

O crawler é responsável por visitar as páginas, extrair informações e enfileirar novos links. Ele usa:

• axios para fazer as requisições HTTP.
• cheerio para parsear o HTML e extrair dados com seletores CSS.

A função principal crawl(startUrl, options):

1. Inicializa um Set de URLs visitadas e uma fila com a URL inicial.

2. Se followSitemap for true, tenta baixar sitemap.xml da raiz e adiciona todas as URLs encontradas.

3. Enquanto a fila não estiver vazia e o limite de páginas não for atingido:

   • Retira uma URL da fila.
   • Faz a requisição GET com timeout e User-Agent configurados.
   • Carrega o HTML no Cheerio.
   • Extrai: título, meta description, H1, H2, H3, imagens (com alt), dados estruturados (JSON-LD), links internos/externos.
   • Adiciona links internos à fila (se ainda não visitados e dentro do limite).

4. Retorna um array de PageData.

// Trecho da extração de imagens
images: $('img').map((_, el) => ({
  src: $(el).attr('src') || '',
  alt: $(el).attr('alt') || undefined,
})).get()

6.3 audit/checks.ts – As Verificações de SEO

Este módulo exporta duas funções:

• runAudit(pages: PageData[]): AuditIssue[] – percorre todas as páginas e aplica uma série de regras.
• calculateScore(issues: AuditIssue[]): number – calcula uma pontuação de 0 a 100 com base na gravidade dos problemas.

Exemplos de verificações implementadas:

O cálculo do score usa pesos: critical:10, high:5, medium:2, low:1. A penalidade total é subtraída de 100, com mínimo 0.

6.4 persist.ts – Salvando Relatórios

O módulo persist.ts gerencia o arquivo data/last-report.json. Ele garante que o diretório exista e salva/recupera o relatório em JSON.

export function saveReport(report: AuditReport): string {
  const dir = ensureDataDir()
  const filePath = path.join(dir, 'last-report.json')
  fs.writeFileSync(filePath, JSON.stringify(report, null, 2), 'utf-8')
  return filePath
}

Isso permite que o dashboard leia o relatório mais recente sem precisar rodar a auditoria novamente.

6.5 Integrações com APIs Externas

Cada integração é encapsulada em seu próprio cliente:

• deepseek/client.ts: envia um prompt para a API de chat da DeepSeek e retorna uma lista de sugestões.
• gsc/client.ts: autentica via OAuth2 com refresh token e consulta a Search Console API, retornando dados dos últimos 28 dias.
• pagespeed/client.ts: faz uma requisição GET para a API do PageSpeed Insights com a URL e a chave de API.
• kwrds/client.ts: usando autenticação básica (login/senha), chama o endpoint de keyword_ideas da DataForSEO para obter palavras‑chave relacionadas.

6.6 server/ – O Dashboard Interativo

O servidor usa Express e serve uma interface web construída com HTML + Tailwind CSS (via CDN). Os endpoints principais são:

• GET / – exibe o dashboard com gráficos e listas.
• GET /api/report – retorna o relatório em JSON.
• GET /api/topics – retorna sugestões de temas geradas a partir das keywords.

O dashboard é gerado dinamicamente pelo módulo dashboard.ts, que injeta os dados no HTML. Ele mostra:

• SEO Score (com círculo de progresso)
• Resumo de problemas por gravidade
• Lista detalhada de issues com recomendações
• Sugestões da IA (da DeepSeek)
• Dados do Search Console (cliques, impressões, CTR)
• Métricas do PageSpeed Insights

7. Como Executar uma Auditoria

Com tudo configurado, você pode rodar a auditoria com:

npm run audit https://meusite.com.br -- --max-pages 50 --dashboard

Onde:

• --max-pages 50 limita o número de páginas rastreadas (padrão 100).
• --dashboard inicia automaticamente o servidor web após a auditoria.

Outras opções úteis:

• --no-sitemap – ignora o sitemap.xml e só segue links internos.
• --no-deepseek – não chama a IA (economiza créditos).
• --no-gsc, --no-pagespeed, --no-keywords – desabilitam integrações específicas.

Exemplo de saída no terminal:

🚀 Iniciando auditoria em https://meusite.com.br...
📄 Rastreadas 47 páginas.
🔍 Encontrados 12 problemas.
🧠 IA gerou 5 sugestões.
📊 Dados do Search Console obtidos.
⚡ PageSpeed Insights obtido.
✅ Relatório salvo em data/last-report.json
📊 SEO Score: 42/100

8. O Dashboard Interativo

Se você usar a flag --dashboard ou executar npm run dashboard separadamente, o servidor iniciará em http://localhost:3000. Lá você verá:

O dashboard é atualizado automaticamente sempre que um novo relatório é salvo. Você pode usá-lo para apresentar os resultados para clientes ou equipe de forma visual.

9. Importância da DataForSEO para SEO

A integração com a DataForSEO vai além de simplesmente listar palavras‑chave. Ela fornece:

• Sugestões de palavras‑chave relacionadas – essencial para criar pilares de conteúdo.
• Volume de pesquisa e concorrência – ajuda a priorizar quais termos atacar.
• Citações por LLMs – Busca menções do domínio auditado e de uma keyword (default reulison no config.ts) em respostas de IA (ChatGPT / Google AI Overview) — busca ao vivo no dashboard
• Ideias de temas para artigos – o próprio projeto inclui um gerador de temas (/api/topics), que combina as keywords relacionadas com a análise de conteúdo do site para propor posts relevantes.

Isso permite que o time de conteúdo crie artigos que realmente atendem à intenção de busca dos usuários, aumentando o tráfego orgânico.

Personalização e Próximos Passos

Como adicionar novas verificações?

Basta editar src/audit/checks.ts e incluir sua lógica. Por exemplo, para verificar se a página tem pelo menos um link interno:

const noInternalLinks = pages.filter(p => p.internalLinks.length === 0 && p.status === 200)
if (noInternalLinks.length > 0) {
  issues.push({
    type: 'medium',
    category: 'technical',
    description: 'Páginas sem links internos',
    recommendation: 'Adicione links internos para melhorar a distribuição de autoridade.',
    pagesAffected: noInternalLinks.map(p => p.url),
  })
}

Como modificar o prompt da DeepSeek?

Em deepseek/client.ts, altere a variável prompt para incluir instruções mais específicas, como pedir que a IA sugira títulos novos ou palavras‑chave alvo.

Integração com CI/CD

Você pode executar a auditoria em um pipeline de deploy (ex: GitHub Actions) para garantir que cada nova versão não introduza regressões de SEO. Basta usar o comando npm run audit e, se o score cair abaixo de um limiar, falhar o build.

Conclusão

O ia-seo-audit é uma ferramenta poderosa que coloca na mão de qualquer profissional de SEO uma auditoria técnica automatizada, rica em dados e com recomendações inteligentes. Ela combina:

• Rapidez – auditorias em minutos, não dias.
• Profundidade – dezenas de verificações técnicas e de conteúdo.
• Integração – com as principais fontes de dados (GSC, PageSpeed, DataForSEO).
• Inteligência – com a DeepSeek, gerando conselhos práticos em português.

Se você gerencia um blog, uma loja virtual ou um site institucional, essa ferramenta pode se tornar parte essencial do seu fluxo de trabalho de SEO.

Experimente agora mesmo:

git clone https://github.com/reulison/ia-seo-audit.git
cd ia-seo-audit
npm install
cp .env.example .env
# configure suas chaves
npm run audit https://seudominio.com -- --dashboard

Contribuições são bem-vindas! O repositório está aberto para forks e pull requests. Basta seguir as boas práticas.

Repositório: github.com/reulison/ia-seo-audit