# AI People Also Ask: documentação completa (dfaipaa)

> Apresentação O AI People Also Ask (slug técnico: dfaipaa) capta as perguntas que os seus clientes fazem realmente à Google, os blocos «People Also Ask», gera as respostas com uma…

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

## Apresentação

O **AI People Also Ask** (slug técnico: `dfaipaa`) capta as perguntas que os seus clientes fazem realmente à Google, os blocos «People Also Ask», gera as respostas com uma IA à sua escolha e publica uma FAQ com marcação schema.org nas suas fichas de produto e páginas de categoria.

O módulo industrializa um pipeline completo em quatro etapas:

- **Recolha** — captura das perguntas PAA nas suas palavras-chave alvo através da SerpApi, do DataForSEO ou por introdução manual.
- **Geração por IA** — redação das respostas através da Mistral, da OpenAI ou da Anthropic, com tom e voz de marca configuráveis.
- **Fluxo editorial** — revisão, atribuição a produtos e categorias, publicação (manual ou automática).
- **Publicação** — acordeão de FAQ acessível no lado da loja + JSON-LD FAQPage para a Google e para os motores generativos.

**Nota** — Não é necessário qualquer `composer install`. O módulo inclui um autoloader PSR-4 mínimo no namespace DataFirefly Dfaipaa.

## Pré-requisitos

- PrestaShop 8.0.0 → 9.99.99
- PHP 8.1, 8.2 ou 8.3
- MySQL 5.7 / MariaDB 10.4 ou superior
- Uma chave de API para, pelo menos, um fornecedor de IA (Mistral, OpenAI ou Anthropic)
- Opcional: uma chave SerpApi ou uma conta DataForSEO para automatizar a recolha
- Ligações HTTPS de saída autorizadas (cURL) a partir do seu alojamento

**Dica** — O modo «introdução manual» permite utilizar o módulo sem qualquer subscrição de recolha: introduz as perguntas você mesmo e a IA encarrega-se das respostas.

## Instalação

1. Descarregue o ZIP `dfaipaa.zip` a partir da sua conta DataFirefly.
2. No back-office do PrestaShop, vá a **Módulos › Gestor de módulos › Carregar um módulo**.
3. Arraste e largue o ZIP, aguarde a confirmação e clique em **Instalar**.
4. Aparece um novo menu **AI People Also Ask** na coluna da esquerda, com três separadores: Configuração, Palavras-chave e Perguntas.

A instalação cria 4 tabelas (prefixo `ps_dfaipaa_`), define os valores de configuração predefinidos e instala 4 separadores de administração (um pai e três filhos) com legendas localizadas em FR, EN, ES, DE, IT e NL.

**Importante** — Se a sua ferramenta de descompressão ignorar as pastas `vendor/`, o autoloader não estará presente e o módulo lançará um erro «Class not found». Descomprima com `unzip` ou carregue o ZIP diretamente pelo back-office, que trata corretamente a estrutura de pastas.

## Configuração: recolha

Separador **AI People Also Ask › Configuração**, primeira secção.

| Campo | Descrição | Predefinição |
| --- | --- | --- |
| Fornecedor | `serpapi`, `dataforseo` ou `manual` | `serpapi` |
| Chave de API | Chave SerpApi, ou credenciais DataForSEO no formato `login:password` | vazio |
| Idioma | Código ISO de 2 letras utilizado no pedido à Google | `fr` |
| País | Código ISO de 2 letras do mercado visado | `FR` |
| Máximo de perguntas por palavra-chave | Limite por operação de recolha | `8` |
| Intervalo de atualização | Em dias, a partir do qual uma palavra-chave é considerada desatualizada | `30` |

**Numa loja portuguesa** — Os valores predefinidos de idioma e país são `fr` e `FR`. Passe-os para `pt` e `PT` antes da primeira recolha, caso contrário captará os blocos PAA do mercado francês.

### Obter uma chave SerpApi

Crie uma conta em **serpapi.com**. O plano gratuito oferece 100 pedidos por mês, o que corresponde a cerca de 100 palavras-chave recolhidas. A chave encontra-se no seu painel, na secção «Your Account». O módulo consulta o endpoint de pesquisa da Google e utiliza o bloco `related_questions` da resposta.

### Obter uma conta DataForSEO

Crie uma conta em **dataforseo.com**. Recebe um par de identificador e palavra-passe para colar no campo Chave de API sob a forma `login:password` (o módulo trata a autenticação HTTP Basic). O DataForSEO cobra por utilização, o que se adequa melhor a grandes volumes. O módulo utiliza o endpoint SERP Google organic live advanced e extrai os elementos `people_also_ask`.

O mapeamento dos códigos de localização está integrado para os seguintes mercados: FR, BE, CH, LU, CA, US, UK, IE, ES, PT, IT, DE, AT, NL, PL, BR e MX.

### Modo de introdução manual

Selecione `manual` para desativar qualquer chamada externa. Passa então a acrescentar as perguntas você mesmo no separador Perguntas; a geração por IA mantém-se plenamente funcional.

## Configuração: inteligência artificial

Segunda secção do separador Configuração.

| Campo | Descrição | Predefinição |
| --- | --- | --- |
| Fornecedor | `mistral`, `openai` ou `anthropic` | `mistral` |
| Modelo | Identificador do modelo no fornecedor | `mistral-large-latest` |
| Chave de API | Chave do fornecedor selecionado | vazio |
| Temperatura | 0.0 a 1.0 — mais baixo = mais factual | `0.3` |
| Máximo de tokens | Comprimento máximo da resposta gerada | `500` |
| Tom | Texto livre: especialista, pedagógico, comercial, caloroso... | vazio |
| Voz de marca | Instruções adicionais para alinhar o estilo editorial | vazio |
| Publicação automática | Publica automaticamente cada resposta gerada | desativado |

### Modelos recomendados

- **Mistral** — `mistral-large-latest` pela qualidade, `mistral-small-latest` para reduzir custos em grandes volumes.
- **OpenAI** — `gpt-4o-mini` oferece uma excelente relação qualidade/preço; `gpt-4o` para catálogos técnicos exigentes.
- **Anthropic** — `claude-sonnet-4-6` para respostas mais matizadas e bem estruturadas.

### Restrições impostas ao modelo

O módulo constrói um prompt de sistema estrito, independente do fornecedor: respostas de 60 a 120 palavras, apenas HTML simples (parágrafos, negrito, itálico, listas), proibição de markdown, de etiquetas de título e de qualquer script. O contexto da entidade (nome e descrição do produto ou da categoria, truncados a 1200 caracteres) e a palavra-chave de origem são injetados para ancorar a resposta. O snippet original da Google é fornecido como referência, com uma instrução explícita de reformulação: nunca de cópia.

**Dica** — Se um modelo mais pequeno continuar a devolver markdown, baixe a temperatura para 0.2 e indique «apenas HTML, sem markdown» no campo Voz de marca.

## Configuração: apresentação

Terceira secção do separador Configuração.

| Campo | Descrição | Predefinição |
| --- | --- | --- |
| Modo no produto | `tab` (separador) ou `footer` (bloco no fim da ficha) | `tab` |
| Ativar no produto | Apresenta a FAQ nas fichas de produto | ativado |
| Ativar na categoria | Apresenta a FAQ no fim da página de categoria | ativado |
| Título do separador | Legenda localizada do separador de produto | «Perguntas frequentes» |
| Título no produto | Título do bloco em modo footer | localizado |
| Título na categoria | Título do bloco de categoria | localizado |
| Emitir o JSON-LD | Injeta a marcação FAQPage | ativado |

No modo `tab`, o módulo apoia-se no mecanismo nativo `ProductExtraContent` do PrestaShop: a FAQ aparece como um separador ao lado de «Descrição» e «Detalhes do produto», sem sobreposição de templates.

## Fluxo editorial

### Etapa 1: acrescentar palavras-chave

Separador **Palavras-chave**. Cole a sua lista na caixa de texto, uma palavra-chave por linha, e valide. Os duplicados são ignorados automaticamente (a adição é idempotente por palavra-chave, idioma e loja).

Escolha palavras-chave que correspondam à intenção de compra: «máquina de café automática», «melhor café em grão», «manutenção de máquina de café». Evite pesquisas de marca pura, que raramente despoletam blocos PAA.

### Etapa 2: recolher

Duas opções:

- **Recolher** — botão individual em cada linha de palavra-chave, útil para testar a configuração.
- **Recolher todas as desatualizadas** — trata em lotes de 20 as palavras-chave cuja última captura ultrapassa o intervalo de atualização.

Cada pergunta captada é guardada com um hash de unicidade (pergunta + idioma + loja): voltar a recolher uma palavra-chave nunca cria duplicados, apenas atualiza a data da última captura.

### Etapa 3: gerar as respostas

Separador **Perguntas**. Filtre pelo estado `pending`, selecione as perguntas através das caixas de seleção e lance a ação em massa **Gerar**. Existe também um botão individual em cada linha.

O contexto da entidade é construído a partir da primeira atribuição da pergunta. Para obter melhores respostas, atribua a pergunta a um produto ou a uma categoria _antes_ de gerar: a IA disporá então do nome e da descrição da entidade.

### Etapa 4: rever e atribuir

Clique numa pergunta para abrir o formulário de edição. Pode:

- corrigir a resposta HTML no editor enriquecido;
- atribuir a pergunta a um ou vários produtos e categorias (relação N para N);
- reordenar as atribuições para controlar a ordem de apresentação do acordeão;
- rejeitar uma pergunta fora do tema (estado `rejected`, mantida na base de dados mas nunca apresentada).

### Etapa 5: publicar

Passe o estado para `published`. A FAQ aparece imediatamente do lado da loja, acompanhada do seu JSON-LD.

Se a opção **Publicação automática** estiver ativada na configuração, as etapas 4 e 5 fundem-se: a geração publica diretamente. Prático para um pipeline totalmente automatizado, a reservar para catálogos em que a revisão humana não é crítica.

## Estados das perguntas

| Estado | Significado | Apresentado na loja |
| --- | --- | --- |
| `pending` | Pergunta captada, ainda sem resposta da IA | Não |
| `generated` | Resposta gerada, a aguardar validação | Não |
| `published` | Validada e publicada | Sim |
| `rejected` | Descartada manualmente | Não |

## Apresentação do lado da loja

O acordeão assenta nos elementos HTML nativos `details` e `summary`, o que garante:

- uma navegação por teclado funcional sem JavaScript;
- conteúdo indexável pelos motores mesmo quando recolhido;
- compatibilidade com todos os navegadores modernos.

O primeiro elemento está aberto por predefinição. É carregado um ficheiro CSS leve, totalmente sobreponível a partir do seu tema-filho. Todas as classes usam o prefixo `dfaipaa-faq` para evitar colisões.

### Eventos JavaScript

O script do front-office emite dois eventos personalizados que pode ligar à sua ferramenta de analítica:

```
document.addEventListener('dfaipaa:open', function (e) {
  // e.detail.question, e.detail.index, e.detail.type, e.detail.entityId
  gtag('event', 'faq_open', { question: e.detail.question });
});

document.addEventListener('dfaipaa:close', function (e) {
  console.log('FAQ fechada:', e.detail.question);
});
```

O ficheiro `views/js/front.js` contém também uma constante `SINGLE_OPEN` (a `false` por predefinição): passe-a para `true` para autorizar apenas um painel aberto de cada vez.

### Ligação direta a uma pergunta

Uma âncora com a forma `#dfaipaa-q-123` abre automaticamente a pergunta correspondente e faz a página deslizar até ela. Prático para partilhar uma resposta específica a partir de um e-mail ou de um ticket de apoio ao cliente.

## Marcação JSON-LD FAQPage

Em cada carregamento de uma página de produto ou de categoria com, pelo menos, uma pergunta publicada, o módulo injeta um bloco JSON-LD imediatamente antes do fecho do corpo do documento (hook `displayBeforeBodyClosingTag`).

Estrutura emitida: um nó `FAQPage`, um array `mainEntity` e, para cada entrada, um nó `Question` que contém um `acceptedAnswer` do tipo `Answer`. O conteúdo HTML das respostas é limpo antes da emissão: as etiquetas de script e de estilo, bem como os atributos de eventos, são removidos.

**Dica** — Valide a sua marcação com a ferramenta de teste de resultados enriquecidos da Google. Note que a Google restringiu a apresentação dos rich snippets de FAQ aos sites governamentais e de saúde, mas a marcação continua valiosa para os motores generativos (ChatGPT, Perplexity, Gemini), que a utilizam ativamente.

## Automatização por cron

É fornecido um script CLI para executar o pipeline sem intervenção manual.

```
# Recolher as palavras-chave desatualizadas (20 no máximo por predefinição)
php modules/dfaipaa/cli/cron.php scrape --limit=20

# Gerar as respostas de IA para as perguntas pendentes
php modules/dfaipaa/cli/cron.php generate --limit=10

# Encadear recolha e geração
php modules/dfaipaa/cli/cron.php all --limit=20
```

Exemplo de crontab, execução noturna às 3 h:

```
0 3 * * * cd /var/www/prestashop && php modules/dfaipaa/cli/cron.php all --limit=30 >> /var/log/dfaipaa.log 2>&1
```

**Importante** — Dimensione o parâmetro `--limit` em função das suas quotas de API. Um lote de 30 palavras-chave consome 30 pedidos da SerpApi; com o plano gratuito (100 por mês), uma execução semanal é mais adequada do que uma execução diária.

## Multilingue e multiloja

As perguntas são indexadas por `id_lang` e `id_shop`. Na prática:

- a mesma palavra-chave recolhida em português e em inglês produz dois conjuntos de perguntas distintos;
- as respostas são geradas no idioma da pergunta, uma vez que o prompt aplica uma diretiva linguística explícita (fr, en, es, de, it, nl, pt, pl);
- em multiloja, as perguntas e atribuições de uma loja nunca aparecem noutra;
- os títulos de apresentação (separador, produto, categoria) são guardados em configuração localizada.

## Resolução de problemas

### A recolha não devolve qualquer pergunta

- Verifique a sua quota no fornecedor: a SerpApi corta silenciosamente acima do plano gratuito.
- Confirme a coerência entre idioma e país: «pt» com «US» dá resultados erráticos.
- Algumas palavras-chave simplesmente não despoletam bloco PAA na Google. Teste o pedido manualmente num navegador em navegação privada.
- No DataForSEO, verifique o formato `login:password` do campo Chave de API.

### A IA devolve markdown em vez de HTML

Baixe a temperatura para 0.2 ou mude para um modelo mais capaz. O prompt já impõe regras HTML estritas, mas os modelos mais leves podem ignorá-las parcialmente.

### A FAQ não aparece na loja

- Verifique se há, pelo menos, uma pergunta no estado `published`.
- Verifique se está mesmo atribuída à entidade consultada (produto ou categoria).
- Confirme que a apresentação está ativada para esse tipo de entidade na configuração.
- Limpe a cache do Smarty em **Parâmetros avançados › Desempenho**.

### O JSON-LD não aparece no código-fonte

Certifique-se de que a opção «Emitir o JSON-LD» está ativada e de que o tema chama efetivamente o hook `displayBeforeBodyClosingTag`. Alguns temas de terceiros omitem-no: acrescente então `{hook h='displayBeforeBodyClosingTag'}` antes do fecho do corpo no seu `layouts/layout-both-columns.tpl`.

### Erro «Class not found» depois da instalação

A pasta `vendor/` não foi extraída. Reinstale o módulo carregando o ZIP através do back-office em vez de o descomprimir manualmente.

### Consultar os registos de operação

Todas as operações (recolha, geração, publicação) ficam registadas. Para investigar:

```
SELECT * FROM ps_dfaipaa_log ORDER BY date_add DESC LIMIT 50;
```

## Desinstalação

Em **Módulos › Gestor de módulos**, clique em **Desinstalar**. A operação elimina as 4 tabelas `ps_dfaipaa_*`, os 4 separadores de administração e todas as chaves de configuração `DFAIPAA_`. O conteúdo gerado é definitivamente perdido: exporte as suas perguntas previamente se as quiser conservar.

## Referência técnica

- **Slug técnico**: `dfaipaa`
- **Namespace**: DataFirefly Dfaipaa (PSR-4, autoloader incorporado)
- **Tabelas criadas**: `ps_dfaipaa_keyword`, `ps_dfaipaa_question`, `ps_dfaipaa_assignment`, `ps_dfaipaa_log`
- **Hooks utilizados**: `displayHeader`, `displayProductExtraContent`, `displayFooterProduct`, `displayCategoryFooter`, `displayBeforeBodyClosingTag`, `actionFrontControllerSetMedia`, `actionAdminControllerSetMedia`, `actionProductUpdate`, `actionProductSave`, `actionCategoryUpdate`, `actionObjectProductDeleteAfter`, `actionObjectCategoryDeleteAfter`
- **Separadores do back-office**: AdminDfaipaa (pai), AdminDfaipaaConfig, AdminDfaipaaKeywords, AdminDfaipaaQuestions
- **Chaves de configuração**: `DFAIPAA_SCRAPER_PROVIDER`, `DFAIPAA_SCRAPER_API_KEY`, `DFAIPAA_SCRAPER_LANG`, `DFAIPAA_SCRAPER_COUNTRY`, `DFAIPAA_SCRAPER_MAX_PER_KEYWORD`, `DFAIPAA_AI_PROVIDER`, `DFAIPAA_AI_MODEL`, `DFAIPAA_AI_API_KEY`, `DFAIPAA_AI_TEMPERATURE`, `DFAIPAA_AI_MAX_TOKENS`, `DFAIPAA_AI_TONE`, `DFAIPAA_AI_BRAND_VOICE`, `DFAIPAA_AUTO_PUBLISH`, `DFAIPAA_REFRESH_INTERVAL`, `DFAIPAA_PRODUCT_MODE`, `DFAIPAA_EMIT_JSONLD`, `DFAIPAA_TAB_TITLE`, `DFAIPAA_PRODUCT_TITLE`, `DFAIPAA_CATEGORY_TITLE`
- **CLI**: `modules/dfaipaa/cli/cron.php` (comandos `scrape`, `generate`, `all`)
- **Template do front-office**: `views/templates/hook/faq.tpl`

## Conformidade com o RGPD

O módulo não recolhe nem guarda qualquer dado pessoal: apenas palavras-chave, perguntas, respostas geradas e registos técnicos de operações. Não é depositado qualquer cookie do lado da loja. As chamadas às API externas (recolha, IA) transmitem apenas a palavra-chave, a pergunta e o contexto do produto: nunca dados de clientes.

## Apoio ao cliente

Para qualquer questão técnica, contacte a equipa DataFirefly através de **contact@datafirefly.com** ou consulte a sua área de cliente em [datafirefly.com](https://www.datafirefly.com/pt/).