# Predictive SEO: documentação completa

> Visão geral O DataFirefly Predictive SEO liga o seu PrestaShop à Google Search Console, aplica um motor de previsão de aprendizagem automática embutido ao histórico de pesquisa e identifica automaticamente…

- Página: <https://www.datafirefly.com/pt/documentation/dfpredictiveseo/>
- Idioma: pt
- Atualizado em: 2026-09-09
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dfpredictiveseo/index.md), [en](https://www.datafirefly.com/en/documentation/dfpredictiveseo/index.md), [es](https://www.datafirefly.com/es/documentation/dfpredictiveseo/index.md), [de](https://www.datafirefly.com/de/documentation/dfpredictiveseo/index.md), [it](https://www.datafirefly.com/it/documentation/dfpredictiveseo/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfpredictiveseo/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfpredictiveseo/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

## Visão geral

O DataFirefly Predictive SEO liga o seu PrestaShop à Google Search Console, aplica um motor de previsão de aprendizagem automática embutido ao histórico de pesquisa e identifica automaticamente os picos sazonais que aí vêm. Para cada oportunidade detetada, pode gerar com um clique um resumo editorial estruturado através da Mistral, da OpenAI ou da Claude.

**A reter:** o Predictive SEO não mede o que já aconteceu, projeta o que vai acontecer. O módulo funciona em pura antecipação: publica o conteúdo duas semanas antes do pico de pesquisa e ganha a posição antes da onda.

### Pré-requisitos

- PrestaShop 8.0+ ou PrestaShop 9.x
- PHP 8.1 no mínimo
- MySQL 5.7+ ou MariaDB 10.3+
- Uma conta Google com acesso à propriedade Search Console da loja
- Uma chave de API de um fornecedor de IA (Mistral, OpenAI ou Anthropic; Mistral por predefinição, cerca de 0,002 € por resumo)
- No mínimo 60 a 90 dias de histórico na GSC para previsões fiáveis

## Instalação

### Instalação a partir do ZIP

1. Descarregue o ZIP `dfpredictiveseo.zip` a partir da sua área de cliente DataFirefly.
2. No back-office PrestaShop, vá a **Módulos → Gestor de módulos**.
3. Clique em **Carregar um módulo** e coloque o ZIP.
4. O módulo instala-se automaticamente, cria as 7 tabelas `dfpseo_*`, regista os 6 separadores em MELHORAR e gera um token de cron único.
5. Depois de instalado, encontra o módulo no menu **Melhorar → Predictive SEO**.

**Atualização:** numa atualização futura, o carregamento de um novo ZIP substitui os ficheiros e executa automaticamente os scripts `upgrade-X.Y.Z.php`. Os dados e a configuração são conservados.

### Esquema da base de dados

A instalação cria 7 tabelas com o prefixo `dfpseo_`:

- `dfpseo_keyword`: palavras-chave seguidas a partir da GSC
- `dfpseo_history`: histórico diário (impressões, cliques, CTR, posição)
- `dfpseo_forecast`: previsões diárias com intervalos de confiança
- `dfpseo_opportunity`: oportunidades sazonais detetadas
- `dfpseo_recommendation`: resumos editoriais gerados pela IA
- `dfpseo_seasonality`: índices sazonais (dia da semana × mês) por palavra-chave
- `dfpseo_sync_log`: registo das sincronizações com a GSC

## Configuração da Google Search Console

O módulo usa o protocolo OAuth2 padrão. Cria um cliente OAuth no Google Cloud, cola as credenciais nas definições e inicia o fluxo de autorização a partir do botão Ligar.

### Passo 1: criar um projeto no Google Cloud

1. Vá a [console.cloud.google.com](https://console.cloud.google.com/) e inicie sessão com a conta Google que tem acesso à sua propriedade Search Console.
2. Clique no seletor de projeto no canto superior esquerdo e depois em **Novo projeto**.
3. Dê-lhe um nome, por exemplo _DataFirefly Predictive SEO_, e crie-o.

### Passo 2: ativar a API Search Console

1. No menu da esquerda, vá a **APIs e Serviços → Biblioteca**.
2. Procure _Search Console API_ e clique em **Ativar**.

### Passo 3: configurar o ecrã de consentimento OAuth

1. Vá a **APIs e Serviços → Ecrã de consentimento OAuth**.
2. Tipo de utilizador: **Externo**.
3. Preencha o nome da aplicação, o e-mail de apoio e o domínio autorizado (a sua loja).
4. Em **Âmbitos**, acrescente `https://www.googleapis.com/auth/webmasters.readonly` (leitura da Search Console).
5. Em modo de teste, acrescente o seu e-mail em **Utilizadores de teste**. Pode passar a produção mais tarde, sem alterar o módulo.

### Passo 4: criar o cliente OAuth

1. Vá a **APIs e Serviços → Credenciais**.
2. Clique em **Criar credenciais → ID de cliente OAuth**.
3. Tipo de aplicação: **Aplicação Web**.
4. Nome: à sua escolha (por exemplo _Predictive SEO Produção_).
5. URI de redirecionamento autorizado: copie o URI apresentado nas definições do módulo (**Melhorar → Predictive SEO → Definições → Google Search Console → URI de redirecionamento**). Formato: `https://a-sua-loja.pt/module/dfpredictiveseo/settings/oauth_callback`.
6. Clique em **Criar**: o Google mostra o `client_id` e o `client_secret`.

### Passo 5: ligar o módulo

1. Nas definições do Predictive SEO, cole o `client_id` e o `client_secret`.
2. Grave.
3. Clique em **Ligar à Google Search Console**.
4. É redirecionado para a página de consentimento do Google. Autorize o acesso de leitura.
5. De volta ao back-office, o módulo guardou o `refresh_token` cifrado e está pronto a sincronizar.
6. Selecione depois a **propriedade Search Console** a seguir na lista pendente (o módulo deteta-a automaticamente após a ligação).

**Atenção:** o URI de redirecionamento tem de ser **idêntico ao caractere** entre o Google Cloud e o módulo. Uma diferença de protocolo (http/https), de barra final ou de subdomínio provoca um erro `redirect_uri_mismatch`.

## Configuração do fornecedor de IA

O módulo suporta 3 fornecedores de IA para gerar os resumos editoriais. Só precisa de um, e fornece a sua própria chave de API do fornecedor escolhido: a DataFirefly não cobra qualquer comissão sobre a utilização.

### Mistral (predefinição, recomendado)

- Modelo: `mistral-small-latest`
- Custo indicativo: cerca de 0,002 € por resumo gerado
- Criar a chave: [console.mistral.ai](https://console.mistral.ai/) → API Keys
- Colar a chave em **Definições → Fornecedor de IA → Chave API Mistral**

### OpenAI

- Modelo: `gpt-4o-mini`
- Custo indicativo: cerca de 0,005 € por resumo
- Criar a chave: [platform.openai.com](https://platform.openai.com/api-keys) → API keys
- Colar a chave em **Definições → Fornecedor de IA → Chave API OpenAI**

### Anthropic (Claude)

- Modelo: `claude-3-5-haiku-latest`
- Custo indicativo: cerca de 0,004 € por resumo
- Criar a chave: [console.anthropic.com](https://console.anthropic.com/) → API Keys
- Colar a chave em **Definições → Fornecedor de IA → Chave API Anthropic**

Selecione depois o fornecedor ativo na lista pendente **Fornecedor de IA ativo**. Se mudar de fornecedor, os resumos já gerados não são regenerados automaticamente.

Os resumos seguem o idioma das palavras-chave da sua propriedade Search Console. Numa loja portuguesa, releia os primeiros resumos gerados para confirmar que o texto sai em português europeu e não em português do Brasil, e ajuste os títulos e a meta description propostos antes de os usar.

## Sincronização dos dados

### Primeira sincronização

Estabelecida a ligação à GSC, faça uma primeira sincronização manual: **Definições → Iniciar a sincronização**. O módulo traz o histórico dos últimos 90 dias para a propriedade selecionada, até 250 000 linhas por sincronização, com as dimensões _data × consulta × página_. A primeira sincronização pode demorar de 30 segundos a 2 minutos, consoante o volume.

### Cron diário

Para as sincronizações automáticas, configure um cron diário (recomendado: de madrugada, entre as 4h e as 6h no fuso Europe/Lisbon) que chame o endpoint protegido do módulo.

O URL exato e o token são apresentados em **Definições → Cron**. Formato genérico:

```
https://a-sua-loja.pt/module/dfpredictiveseo/cron/sync?token=O_SEU_TOKEN_GERADO
```

Exemplo de linha de crontab (cron Unix):

```
0 5 * * * curl -s "https://a-sua-loja.pt/module/dfpredictiveseo/cron/sync?token=O_SEU_TOKEN" > /dev/null 2>&1
```

**Sugestão:** o token é gerado aleatoriamente na instalação e guardado na tabela de configuração do PrestaShop (`DFPSEO_CRON_TOKEN`). Se o comprometer, pode regenerá-lo em **Definições → Regenerar o token do cron**.

### Sequência de uma sincronização

Cada sincronização executa em série:

1. Recolha na GSC dos últimos 90 dias móveis (dimensões data/consulta/página)
2. Inserção e atualização em `dfpseo_keyword` e `dfpseo_history`
3. Recálculo dos índices sazonais (por palavra-chave com histórico suficiente)
4. Geração das previsões no horizonte configurado
5. Deteção das oportunidades na janela futura
6. Registo em `dfpseo_sync_log`

## Painel

O painel (**Melhorar → Predictive SEO → Painel**) reúne os indicadores-chave:

- **4 cartões de KPI**: palavras-chave seguidas, oportunidades por vir, cliques previstos a 14 dias, última sincronização com a GSC
- **Gráfico principal**: curva agregada do histórico (90 dias) e da previsão (horizonte configurado, 30 dias por predefinição), com banda de confiança de 95 %
- **Principais oportunidades**: os 10 próximos picos sazonais ordenados por pontuação
- **Registo de sincronizações**: as 5 últimas sincronizações com o respetivo estado

### Estado da ligação

Dois emblemas no topo do painel indicam o estado das integrações: **GSC ligada** (verde/vermelho) e **Fornecedor de IA configurado** (verde/vermelho). Se algum estiver a vermelho, siga a ligação direta para as definições correspondentes.

## Palavras-chave e previsões

### Lista de palavras-chave

O separador **Palavras-chave** mostra a grelha nativa do PrestaShop com todas as consultas sincronizadas. Colunas: consulta, página de destino, impressões a 30 dias, cliques a 30 dias, CTR, posição média e última atualização. Pode filtrar, ordenar e exportar.

### Vista detalhada por palavra-chave

Um clique numa palavra-chave abre a sua ficha:

- Curva individual de histórico e previsão própria
- Intervalo de confiança de 95 % em torno da previsão
- Mapa de calor sazonal 12 × 7 (mês × dia da semana)
- Índices sazonais calculados
- Lista das oportunidades ligadas a essa palavra-chave

### Mapa de calor da sazonalidade

O mapa de calor mostra os índices sazonais multiplicativos. Leitura:

- Célula a 1,00: tráfego médio nessa combinação mês × dia
- Célula a 1,50: tráfego 50 % acima da média (pico sazonal)
- Célula a 0,60: tráfego 40 % abaixo da média (vale)

As células são coloridas do azul-claro (vale) ao azul-escuro e ao laranja-avermelhado (pico). Basta um olhar para identificar as semanas a explorar.

## Oportunidades sazonais

### Deteção automática

É detetada uma oportunidade quando, numa janela futura de 14 dias (configurável em `DFPSEO_OPPORTUNITY_LOOKAHEAD_DAYS`):

- A previsão ultrapassa a linha de base da palavra-chave × 1,25 (**limiar de pico**)
- E o índice sazonal da combinação mês × dia é superior a 1,10

Os picos contíguos (intervalo ≤ 2 dias) são agrupados numa única oportunidade que cobre a janela completa.

### Pontuação da oportunidade

A pontuação combina três fatores:

```
pontuação = cliques_esperados × lift × confiança
```

- `cliques_esperados`: soma dos cliques previstos na janela
- `lift`: rácio entre pico e linha de base
- `confiança`: largura do intervalo de previsão (quanto mais estreito, mais alta a pontuação)

Uma pontuação superior a 80 indica uma oportunidade de forte potencial e forte sinal sazonal. Entre 40 e 80, a oportunidade é moderada. Abaixo de 40, o sinal é demasiado fraco ou incerto para justificar uma ação prioritária.

### Fluxo de trabalho de uma oportunidade

Cada oportunidade tem um estado:

- **Nova**: acabada de detetar, a aguardar decisão
- **Em curso**: foi gerado um resumo e o trabalho editorial está a decorrer
- **Tratada**: conteúdo publicado, oportunidade aproveitada
- **Ignorada**: decisão de não tratar (falso positivo, fora da estratégia)

## Recomendações de IA

### Gerar um resumo

A partir de qualquer oportunidade, clique em **Gerar o resumo**. O módulo envia um pedido ao fornecedor de IA ativo com o contexto da palavra-chave (volume, sazonalidade, posição atual, página em causa) e recebe um resumo estruturado em JSON com:

- **summary**: resumo estratégico
- **meta_description**: meta description SEO pronta a colar (150-160 caracteres)
- **search_intent**: intenção de pesquisa dominante (informacional / transacional / navegacional / comercial)
- **outline**: plano detalhado h1/h2/h3 do artigo ou da página
- **keywords_to_include**: palavras-chave semânticas a incluir
- **internal_links**: sugestões de ligações internas para outras páginas do site
- **rationale**: justificação estratégica da recomendação

A geração demora 1 a 3 segundos, consoante o fornecedor.

### Fluxo de aprovação

Cada resumo passa pelos estados:

1. **Pending**: gerado, a aguardar revisão
2. **Approved**: validado para redação
3. **Published**: conteúdo publicado (a marcar manualmente)
4. **Rejected**: recusado (resumo de má qualidade ou fora de tema)
5. **Draft**: em alteração

O fluxo permite-lhe manter um registo claro do que já foi tratado.

## Arquitetura técnica

### Stack

- Arquitetura PSR-4, namespace `DfPredictiveSeo` → `src/`
- Controladores Symfony que estendem `FrameworkBundleAdminController`
- Repositórios Doctrine DBAL (sem ObjectModel)
- GSC acedida em REST direto por cURL e OAuth2 (sem `google/apiclient`, para se manter leve)
- Sem dependências Composer obrigatórias na instalação (autoloader PSR-4 embutido)

### Sequência de aprendizagem automática

1. **Decomposição sazonal multiplicativa**: índices de dia da semana e de mês calculados por média móvel centrada de 28 dias e média truncada a 10 %
2. **Regressão OLS** sobre `log(impressões+1)` para modelar a tendência log-linear
3. **Previsão**: `exp(previsão_log) × índice_sazonal_dia × índice_sazonal_mês`
4. **Intervalos de 95 %**: aproximação de Student sobre o erro residual da regressão, com alargamento progressivo ao longo do horizonte

### Endpoint de cron

O endpoint é público mas protegido por token. Exemplo em PHP para chamada programática:

```
$token = 'o_seu_token_cron';
$url = 'https://a-sua-loja.pt/module/dfpredictiveseo/cron/sync?token=' . $token;
$response = file_get_contents($url);
$data = json_decode($response, true);
// $data['status'] = 'ok' | 'error'
// $data['keywords_synced'] = número de palavras-chave atualizadas
// $data['opportunities_detected'] = número de oportunidades novas detetadas
```

### Variáveis de configuração

O módulo guarda 18 chaves de configuração na tabela `ps_configuration`:

- `DFPSEO_GSC_CLIENT_ID`, `DFPSEO_GSC_CLIENT_SECRET`, `DFPSEO_GSC_REFRESH_TOKEN` (cifrado), `DFPSEO_GSC_PROPERTY`
- `DFPSEO_AI_PROVIDER`, `DFPSEO_AI_MISTRAL_KEY`, `DFPSEO_AI_OPENAI_KEY`, `DFPSEO_AI_ANTHROPIC_KEY`
- `DFPSEO_FORECAST_HORIZON_DAYS` (predefinição: 30)
- `DFPSEO_OPPORTUNITY_LOOKAHEAD_DAYS` (predefinição: 14)
- `DFPSEO_PEAK_THRESHOLD` (predefinição: 1.25)
- `DFPSEO_SEASONAL_THRESHOLD` (predefinição: 1.10)
- `DFPSEO_CRON_TOKEN` (gerado na instalação)
- `DFPSEO_LAST_SYNC`, `DFPSEO_LAST_FORECAST`

## Resolução de problemas

### Erro `redirect_uri_mismatch` ao ligar à GSC

O URI de redirecionamento configurado no Google Cloud não corresponde exatamente ao esperado pelo módulo. Verifique:

- Protocolo: `https://` e não `http://`
- Sem barra final: `...oauth_callback` e não `...oauth_callback/`
- Subdomínio: com ou sem `www.` consoante a sua loja, tem de coincidir

### A sincronização com a GSC não devolve palavras-chave

- Confirme que a propriedade selecionada nas definições é mesmo a que recebe tráfego de SEO (e não uma domain property vazia)
- Confirme que a conta Google ligada é _proprietária_ ou _utilizadora autorizada_ nessa propriedade
- A propriedade tem de ter pelo menos alguns dias de histórico indexado (a Google Search Console publica os dados com 2 a 3 dias de atraso)

### As previsões parecem pouco fiáveis

- Confirme que tem pelo menos 60 a 90 dias de histórico. Abaixo disso, os índices sazonais não podem ser corretamente estimados
- Nas palavras-chave erráticas (pouco sinal, muito ruído), a largura do intervalo de 95 % é propositadamente maior: o módulo mostra explicitamente uma confiança baixa
- Para previsões mais precisas em horizontes longos (60 a 90 dias), espere ter acumulado 6 a 12 meses de histórico. O motor melhora com o tempo

### O endpoint de cron devolve um erro 403

O token passado na query string não corresponde a `DFPSEO_CRON_TOKEN`. Verifique o valor exato em **Definições → Cron**. Em caso de dúvida, regenere o token e atualize o seu crontab.

### O resumo de IA não é gerado

- Confirme que colou uma chave de API válida para o fornecedor ativo selecionado
- Verifique o seu saldo na consola do fornecedor (Mistral, OpenAI ou Anthropic)
- Se o fornecedor devolver um erro de limite de pedidos, espere alguns minutos e tente de novo
- Os resumos gerados são guardados em `dfpseo_recommendation`; em caso de erro, este também fica registado nessa tabela com o estado `error`

## Perguntas frequentes

### O módulo funciona sem a Google Search Console?

Não, a GSC é a fonte de dados essencial. O módulo precisa de um mínimo de 60 a 90 dias de histórico para produzir previsões fiáveis e calcular a sazonalidade. Se a sua loja acabou de ser lançada, espere ter pelo menos 2 meses de dados indexados antes de instalar o módulo.

### Quanto custa um resumo de IA?

Depende do fornecedor escolhido. Com a Mistral (predefinição), conte cerca de 0,002 € por resumo. Com o GPT-4o-mini da OpenAI, cerca de 0,005 €. Com o Claude Haiku, cerca de 0,004 €. Fornece a sua própria chave de API e paga diretamente ao fornecedor: a DataFirefly não cobra qualquer comissão.

### Quantas palavras-chave é que o módulo consegue seguir?

Não há limite definido no código. Uma sincronização normal traz até 250 000 linhas (data × consulta × página) por chamada, o que cobre a quase totalidade das lojas. Acima disso, aumente a memória PHP atribuída ao processo de cron.

### O módulo é compatível com outros módulos de SEO?

Sim. O Predictive SEO nunca escreve nas páginas de produto nem nos metadados: limita-se a ler a GSC e a produzir recomendações. É totalmente compatível com todos os módulos de SEO existentes, DataFirefly ou de terceiros.

### Os meus dados da GSC ficam guardados na DataFirefly?

Não. Todos os dados ficam no seu servidor, na sua base de dados PrestaShop. O módulo chama diretamente a API da Google com as suas credenciais OAuth e chama diretamente os fornecedores de IA com a sua chave de API. Nenhum dado passa pelos servidores da DataFirefly.

### Que horizonte de previsão é o mais fiável?

O horizonte de 7 a 14 dias é muito fiável (intervalo de 95 % estreito). O de 30 a 60 dias é indicativo (intervalo mais largo). Acima de 90 dias, as previsões tornam-se pouco úteis para decisões operacionais: o módulo calcula-as, mas mostra uma confiança baixa.