# DataFirefly FAQ IA de Produto para WooCommerce: documentação
> O DataFirefly FAQ IA de Produto gera automaticamente FAQ contextuais para as suas fichas de produto WooCommerce com o OpenAI ou o Anthropic Claude, e injeta os rich snippets Schema.org…
- Página:
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dffaqai/index.md), [en](https://www.datafirefly.com/en/documentation/dffaqai/index.md), [es](https://www.datafirefly.com/es/documentation/dffaqai/index.md), [de](https://www.datafirefly.com/de/documentation/dffaqai/index.md), [it](https://www.datafirefly.com/it/documentation/dffaqai/index.md), [pl](https://www.datafirefly.com/pl/documentation/dffaqai/index.md), [nl](https://www.datafirefly.com/nl/documentation/dffaqai/index.md)
- Índice:
O DataFirefly FAQ IA de Produto gera automaticamente FAQ contextuais para as suas fichas de produto WooCommerce com o OpenAI ou o Anthropic Claude, e injeta os rich snippets Schema.org FAQPage na etiqueta head para os resultados enriquecidos da Google. Este guia cobre a instalação, a configuração completa e a utilização diária.
## Requisitos
- WordPress 6.0 ou superior (testado até à 6.6)
- WooCommerce 7.0 ou superior (testado até à 9.4), compatível com HPOS
- PHP 7.4 a 8.3
- Uma chave de API da OpenAI ([platform.openai.com/api-keys](https://platform.openai.com/api-keys)) ou da Anthropic ([console.anthropic.com](https://console.anthropic.com/))
- Facultativo: Polylang ou WPML para o multilingue
## Instalação
1. Descarregue o ficheiro `dffaqai-1.0.0.zip` a partir da sua conta DataFirefly.
2. Na administração do WordPress: **Plugins → Adicionar → Carregar plugin**, selecione o ZIP e clique em **Instalar agora**.
3. Clique em **Ativar**. O plugin cria a sua tabela de armazenamento das FAQ e as definições predefinidas.
Na ativação, aparece um menu **FAQ IA** na barra lateral da administração, com duas entradas: _Definições_ e _Geração em massa_.
## Configuração do fornecedor de IA
Vá a **FAQ IA → Definições → separador Fornecedor**.
### Escolher OpenAI ou Anthropic Claude
- **OpenAI**: cole a sua chave de API e escolha um modelo: `gpt-4o-mini` (o mais económico, recomendado), `gpt-4o`, `gpt-4-turbo` ou `gpt-3.5-turbo`.
- **Anthropic Claude**: cole a sua chave de API e escolha: `claude-haiku-4-5` (económico, recomendado), `claude-sonnet-4-6` ou `claude-opus-4-7`.
O plugin encaminha automaticamente para a API certa consoante o fornecedor selecionado. Pode alternar a qualquer momento: as FAQ já geradas são conservadas.
### Parâmetros de geração
- **Número de perguntas por produto**: 1 a 15 (5 por predefinição).
- **Temperatura**: 0 (determinista) a 2 (muito criativo). 0,7 por predefinição.
- **Max tokens**: comprimento máximo da resposta da IA. 2000 por predefinição.
Custo indicativo: uma geração de 5 perguntas custa cerca de 0,0005 USD com o gpt-4o-mini e 0,001 USD com o claude-haiku-4-5. Para 200 produtos em 3 idiomas, conte com 0,30 a 0,60 USD no total.
## Separador Prompt: personalizar o conteúdo gerado
### Tom de voz
Seis estilos pré-configurados: profissional, amigável, descontraído, técnico, entusiasta, tranquilizador. O tom muda a formulação das respostas sem programar nada.
### Público-alvo
Texto livre, por exemplo «profissionais de saúde (B2B)», «primeiros compradores» ou «entusiastas de bricolagem». A IA adapta o vocabulário, as referências e o nível de detalhe.
### Prompt de sistema personalizado
Deixe vazio para usar o prompt predefinido, construído a partir do tom e do público. Se o preencher, substitui por completo as instruções predefinidas, o que é útil para lojas com uma linha editorial estrita.
### Diretrizes adicionais
Instruções acrescentadas a cada prompt, por exemplo «mencionar sempre a garantia de 2 anos», «evitar superlativos», «não comparar com a concorrência».
### Contexto de produto a incluir
Três caixas de seleção enriquecem o contexto enviado à IA: **categoria principal**, **marca** (taxonomias `product_brand`, `pwb-brand` e `yith_product_brand` detetadas automaticamente) e **atributos do WooCommerce**. Nos produtos técnicos, a inclusão dos atributos melhora nitidamente a pertinência das perguntas.
## Separador Apresentação e SEO
### Posição de apresentação
Cinco hooks do WooCommerce à escolha:
- `woocommerce_after_single_product_summary`: por baixo dos separadores (predefinido)
- `woocommerce_single_product_summary`: dentro do resumo do produto
- `woocommerce_product_meta_end`: no fim das metas do produto
- `woocommerce_after_single_product`: depois de toda a zona do produto
- `woocommerce_before_single_product`: antes de toda a zona do produto
A **prioridade do hook** (15 por predefinição) é configurável para gerir a coexistência com outros plugins.
### Modo de apresentação
Acordeão (primeira pergunta aberta, navegação por teclado conforme a ARIA) ou todas as respostas abertas.
### Rich snippets FAQPage
Quando a opção está ativa, o plugin injeta o JSON-LD Schema.org FAQPage na etiqueta head de cada ficha de produto que tenha pelo menos uma FAQ ativa. A codificação usa `JSON_HEX_TAG`, `JSON_HEX_AMP`, `JSON_HEX_APOS` e `JSON_HEX_QUOT` e passa o Rich Results Test da Google.
### Título da FAQ por idioma
Um campo de título por idioma ativo no site, com valores predefinidos fornecidos em FR, EN, ES, DE, IT, PT e NL.
### Categorias excluídas
Lista de identificadores de categorias do WooCommerce separados por vírgulas. Os produtos dessas categorias são ignorados na geração em massa e na geração automática (produtos virtuais, vales de oferta, etc.).
## A metabox FAQ na ficha de produto
No ecrã de edição de cada produto, a metabox **FAQ IA** oferece um controlo completo:
- **Gerar com a IA**: cria um conjunto de perguntas e respostas para o idioma selecionado.
- **Acrescentar uma pergunta** manual a qualquer momento.
- **Alterar** uma pergunta ou uma resposta: a linha é gravada automaticamente ao perder o foco.
- **Reordenar** por arrastar e largar através da pega à esquerda de cada linha.
- **Ativar ou desativar** uma entrada sem a eliminar.
- **Eliminar** definitivamente uma entrada.
Um seletor de idioma no topo da metabox permite alternar instantaneamente entre as traduções Polylang ou WPML do produto: cada tradução tem o seu próprio conjunto de FAQ.
## Geração em massa
Menu **FAQ IA → Geração em massa**:
1. Escolha o **idioma de destino**: idioma predefinido, idioma específico, ou todos os idiomas ativos.
2. Assinale, se quiser, **Forçar a regeneração** para substituir as FAQ existentes (útil depois de mudar o tom ou o fornecedor).
3. Clique em **Iniciar**.
O processamento é sequencial (cerca de um produto por segundo, consoante a latência da API), com barra de progresso em tempo real, contador de produtos tratados e registo de erros por produto. O botão **Parar** interrompe de forma limpa entre dois produtos. São tratados apenas os produtos publicados; as categorias excluídas são ignoradas.
Deixe o separador do navegador aberto durante a geração em massa: o processamento é comandado do lado do navegador para permitir a barra de progresso e a paragem a pedido.
## Geração automática na criação de produto
Opção do separador Fornecedor: quando está ativa, o plugin gera automaticamente uma FAQ no idioma predefinido a cada gravação de um produto que ainda não a tenha. As FAQ existentes nunca são substituídas por este mecanismo.
## Multilingue com Polylang e WPML
O plugin deteta automaticamente o Polylang (`pll_languages_list`, `pll_get_post_translations`) e o WPML (`wpml_active_languages`, `wpml_object_id`). Cada tradução de um produto recebe o seu próprio conjunto de FAQ, gerado nativamente no idioma de destino, e não uma tradução do original. A geração em massa «todos os idiomas» percorre cada tradução de cada produto.
## Verificar os rich snippets
1. Abra uma ficha de produto com pelo menos uma FAQ ativa.
2. Veja o código-fonte e procure `application/ld+json`: tem de existir um bloco `"@type":"FAQPage"`.
3. Teste o URL no [Rich Results Test da Google](https://search.google.com/test/rich-results): a deteção «FAQ» tem de ser válida.
A Google decide sozinha a apresentação dos rich results na SERP; a marcação válida é uma condição necessária mas não suficiente. A apresentação surge geralmente após a reindexação da página.
## Resolução de problemas
### «A chave de API do fornecedor de IA não está configurada»
Indique a chave do fornecedor ativo no separador Fornecedor. Verifique que não há espaços antes ou depois da chave.
### Erro de API durante a geração
Consulte **WooCommerce → Estado → Registos** e selecione a origem `dffaqai`: cada erro de API fica aí registado com o código HTTP e a mensagem do fornecedor (chave inválida, quota excedida, modelo desconhecido...).
### O bloco de FAQ não aparece
Verifique que o produto tem pelo menos uma FAQ _ativa_ no idioma apresentado, e que o tema executa o hook escolhido. Em caso de dúvida, volte ao hook predefinido `woocommerce_after_single_product_summary`, presente em todos os temas WooCommerce padrão.
### As perguntas geradas estão no idioma errado
O idioma de geração segue a tradução do produto (Polylang/WPML) ou a locale do site em modo monolingue. Verifique o seletor de idioma da metabox antes de gerar.
## Desinstalação
A desativação conserva todos os dados. A **remoção** do plugin executa o `uninstall.php`: a tabela SQL das FAQ e todas as opções `dffaqai_*` são eliminadas definitivamente.
## Suporte
O suporte é feito por e-mail com resposta em 24 horas úteis (FR/EN). Junte, se possível, o registo `dffaqai` e as versões do WordPress, do WooCommerce e do PHP.