# FAQ IA Produto: guia completo de instalação e configuração

> Apresentação O DataFirefly FAQ IA Produto gera automaticamente FAQ contextuais para as suas fichas de produto PrestaShop 8 através da OpenAI ou da Anthropic Claude, com injeção de rich snippets…

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

## Apresentação

O **DataFirefly FAQ IA Produto** gera automaticamente FAQ contextuais para as suas fichas de produto PrestaShop 8 através da OpenAI ou da Anthropic Claude, com injeção de rich snippets Schema.org `FAQPage` no head para os resultados enriquecidos do Google. As FAQ são guardadas na base de dados (tabela `ps_product_faq`): nenhuma chamada à API é feita do lado do front-office.

- **Compatibilidade:** PrestaShop 8.0 → 8.99, PHP 7.2 → 8.3
- **Multilingue:** FAQ geradas e guardadas por idioma
- **Multiloja:** configuração independente por subloja

O título por defeito do bloco FAQ já é fornecido em português (PT) entre os sete idiomas de origem. Para garantir um português europeu nas respostas geradas, acrescente uma diretiva como « escreve em português europeu, nunca em português do Brasil » nas diretivas adicionais (secção 2).

## Instalação

1. No seu back-office, vá a **Módulos → Gestor de módulos → Instalar um módulo**.
2. Carregue `productfaqai-3.0.0.zip`.
3. Clique em **Instalar** e depois em **Configurar**.

**Atualização a partir da v2.x (módulo Sash):** o upgrade não é destrutivo. O esquema da tabela `ps_product_faq` mantém-se inalterado: as suas FAQ existentes são conservadas. Instale simplesmente a v3.0.0 por cima e reconfigure depois a sua chave API na nova interface.

## 1. Fornecedor de IA e modelo

Primeiro formulário da página de configuração.

- **Fornecedor de IA:** OpenAI ou Anthropic Claude. O módulo muda automaticamente para a API certa.
- **Chave API OpenAI:** a partir de [platform.openai.com](https://platform.openai.com) (começa por `sk-`).
- **Chave API Anthropic:** a partir de [console.anthropic.com](https://console.anthropic.com) (começa por `sk-ant-`).
- **Modelo:** para a OpenAI, `gpt-4o-mini` recomendado (o mais económico). Para a Anthropic, `claude-haiku-4-5` recomendado.
- **Número de perguntas:** 1 a 15 (por defeito: 5).
- **Temperatura:** 0 = determinista, 2 = muito criativo. Recomendado: 0,7.
- **Max tokens:** comprimento máximo da resposta (por defeito: 2000). Aumente se gerar mais de 8 perguntas.
- **Geração automática:** gera automaticamente a FAQ (idioma por defeito) a cada criação de produto.

**Custo indicativo:** uma geração de 5 perguntas custa cerca de 0,0005 $ com o gpt-4o-mini e cerca de 0,001 $ com o claude-haiku-4-5. 200 produtos × 3 idiomas ≈ 0,30 a 0,60 $ no total.

## 2. Prompt e diretivas de conteúdo

Segundo formulário: controla a qualidade e o estilo das FAQ geradas.

- **Tom de voz:** profissional, amigável, descontraído, técnico, entusiasta ou tranquilizador.
- **Audiência-alvo** (opcional): texto livre, ex. « profissionais de saúde B2B », « compradores pela primeira vez ». A IA adapta o vocabulário e o nível de detalhe.
- **Prompt de sistema personalizado** (opcional): substitui integralmente as instruções por defeito. Deixe vazio para usar o prompt integrado.
- **Diretivas adicionais** (opcional): instruções acrescentadas ao prompt, ex. « mencionar sempre a garantia de 3 anos », « evitar o jargão ».
- **Incluir categoria / fabricante / características:** três interruptores que enriquecem o contexto enviado à IA. Ative « características » para os produtos técnicos: a precisão das respostas melhora nitidamente.

## 3. Apresentação e SEO

- **Posição de apresentação (hook):** escolha entre 5 locais:
   - `displayProductFooter`: sob toda a ficha (por defeito, funciona em todo o lado)
   - `displayFooterProduct`: variante consoante o tema
   - `displayProductAdditionalInfo`: sob o botão de compra (mais visível)
   - `displayReassurance`: bloco de confiança
   - `displayAfterProductThumbs`: sob as miniaturas
- **Título da FAQ:** um campo por idioma da loja. Valores por defeito fornecidos em FR/EN/ES/DE/IT/PT/NL.
- **Modo acordeão:** ativado = perguntas retráteis (primeira aberta). Desativado = todas as respostas visíveis.
- **Rich snippets JSON-LD:** injeta a marcação Schema.org `FAQPage` no head. Recomendado: ativado.
- **Categorias excluídas:** IDs separados por vírgulas (ex. `12,45,78`). Os produtos dessas categorias são ignorados na geração em massa.

O módulo regista os 5 hooks na instalação mas só renderiza o bloco no hook configurado. Se um hook não existir no seu tema, o bloco simplesmente não aparecerá: teste primeiro com o hook por defeito.

## Gerar FAQ

### Geração individual

No painel « Gerar FAQ para os produtos », cada linha de produto mostra um botão **Gerar**. Selecione primeiro o idioma de destino no menu pendente no topo da tabela. O número de FAQ existentes por idioma é apresentado para cada produto.

### Geração em massa

- **Gerar para todos os produtos (idioma atual):** processa todos os produtos sem FAQ no idioma ativo.
- **Gerar para todos os produtos (todos os idiomas):** processa todos os idiomas ativos da loja.
- **Forçar a regeneração:** marque esta caixa para sobrescrever as FAQ existentes, útil depois de uma mudança de prompt, de tom ou de fornecedor.

**Duração:** conte cerca de 1 produto/segundo por idioma (latência da API variável). 100 produtos × 3 idiomas ≈ 5 minutos. Não feche o separador durante o processamento. Os produtos das categorias excluídas são automaticamente ignorados.

### Geração automática

Se ativada no primeiro formulário, cada novo produto (hook `actionProductAdd`) recebe automaticamente uma FAQ no idioma por defeito da loja.

## Editor de FAQ por produto

Clique em **Editar FAQ** numa linha de produto para abrir o editor:

- **Seletor de idioma** no topo: mudança instantânea entre idiomas.
- **Posição:** peso numérico, ordem crescente de apresentação.
- **Pergunta / Resposta:** edição direta do texto.
- **Estado:** ativar/desativar uma entrada sem a eliminar (uma entrada inativa não aparece nem na ficha nem no JSON-LD).
- **Eliminar:** eliminação definitiva de uma entrada.
- **Adicionar uma FAQ:** adição manual de uma pergunta/resposta.

Clique em **Guardar** para validar o conjunto das alterações da página.

## Rich snippets FAQPage

Quando a opção JSON-LD está ativa, o módulo injeta no `head` de cada ficha de produto com pelo menos uma FAQ ativa um bloco `application/ld+json` conforme ao Schema.org `FAQPage`:

```
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "…",
      "acceptedAnswer": { "@type": "Answer", "text": "…" }
    }
  ]
}
```

Verifique a marcação com o [teste de resultados enriquecidos do Google](https://search.google.com/test/rich-results). A aparição na SERP depende do Google e pode demorar vários dias depois da reindexação da página.

## Resolução de problemas

### « Configure a sua chave API »

A chave do fornecedor selecionado está vazia ou é inválida. Verifique que a chave corresponde ao fornecedor ativo (OpenAI = `sk-…`, Anthropic = `sk-ant-…`).

### Erros de geração em massa

Os erros de API (quota ultrapassada, chave revogada, timeout) são registados em **Parâmetros avançados → Registos** via PrestaShopLogger. O relatório de fim de processamento mostra o detalhe de sucessos / ignorados / erros por idioma.

### A FAQ não aparece na ficha de produto

1. Verifique que o produto tem pelo menos uma FAQ **ativa** no idioma consultado.
2. Verifique que o hook configurado existe no seu tema: volte a `displayProductFooter` para testar.
3. Limpe a cache do PrestaShop (**Parâmetros avançados → Desempenho**).

### Os rich snippets não aparecem no Google

A marcação pode ser válida sem que o Google a mostre: a apresentação dos resultados enriquecidos fica ao critério do Google. Verifique primeiro a marcação com o teste de resultados enriquecidos e aguarde depois o tempo da reindexação.

## Desinstalação

A desinstalação elimina a tabela `ps_product_faq` (todas as FAQ geradas) e o conjunto das chaves de configuração. É pedida uma confirmação. Exporte os seus dados previamente se necessário.