llms.txt + AEO Schema para WooCommerce: guia completo

Visão geral

O plugin DataFirefly llms.txt + AEO Schema torna a sua loja WooCommerce visível e corretamente compreendida pelos agentes de IA (ChatGPT, Claude, Perplexity, Gemini). Combina dois mecanismos complementares:

• Um endpoint /llms.txt dinâmico conforme ao padrão llmstxt.org, gerado a partir do seu catálogo com cache por idioma.
• Um enriquecimento do schema Product do WooCommerce com os atributos anti-alucinação que os agentes procuram: marca, GTIN, materiais, compatibilidade, políticas de devolução e de expedição, mais um schema FAQPage separado dirigido a agentes.

Requisitos

• WordPress 6.2 ou superior
• WooCommerce 8.0 ou superior (testado até à 9.4)
• PHP 8.0 ou superior
• Facultativo: Polylang ou WPML para a geração multilingue

Instalação

1. Descarregue o arquivo dfllmstxtaeo.zip a partir da sua conta DataFirefly.
2. Na administração do WordPress, vá a Plugins → Adicionar → Carregar plugin, selecione o ZIP e clique em Instalar.
3. Ative o plugin. A regra de reescrita para /llms.txt é registada e os permalinks são atualizados automaticamente na ativação.
4. Verifique que https://oseusite.tld/llms.txt responde. Se obtiver um 404, vá a Definições → Permalinks e clique em Guardar para forçar um flush das regras.

Definições gerais

A página de configuração está em WooCommerce → llms.txt + AEO. Mostra no topo o URL do seu llms.txt com uma ligação direta de pré-visualização.

Servir o /llms.txt

Quatro interruptores controlam as grandes funções: o endpoint llms.txt, o enriquecimento do schema de produto, a saída do schema FAQPage e a especificação Speakable. Está tudo ativo por predefinição.

Conteúdo do llms.txt

• Incluir produtos / páginas / artigos: escolha as secções geradas.
• Número máximo de produtos: de 1 a 1000 (200 por predefinição). Os produtos mais recentes são listados primeiro.
• Duração da cache: em minutos, 0 para desativar. A cache é de qualquer forma limpa automaticamente a cada edição de produto, de página ou de definição.
• Parágrafo de introdução: texto livre (texto simples ou markdown) inserido após a descrição do site.

Valores predefinidos do schema

• Nome da marca predefinido: usado quando um produto não tem marca própria.
• País do comerciante (ISO-2): deixe vazio para usar o país base do WooCommerce.
• Janela de devolução predefinida: em dias, alimenta o hasMerchantReturnPolicy.
• Custos de devolução: devolução gratuita, cliente paga a expedição, ou cliente paga todos os custos.

O endpoint /llms.txt

O ficheiro é servido com o cabeçalho Content-Type: text/markdown; charset=utf-8 e X-Robots-Tag: noindex (destina-se aos crawlers de IA, não ao índice da Google). As secções geradas: categorias de produtos, produtos (título, URL, preço, descrição curta), páginas, artigos, e depois as ligações para a política de privacidade e as condições gerais configuradas no WordPress e no WooCommerce.

Funcionamento da cache

O conteúdo é colocado em cache num transiente delimitado por idioma (dfllmstxtaeo_llms_cache_{lang}). É invalidado automaticamente nos hooks save_post_product, save_post_page, deleted_post e em cada gravação das definições do plugin.

Multilingue

O Polylang e o WPML são detetados automaticamente. Cada idioma tem o seu próprio llms.txt servido no seu prefixo de URL (por exemplo /en/llms.txt, consoante a sua configuração do Polylang), com cache independente. Sem plugin multilingue, é usada a locale do WordPress.

Separador AEO Schema nos produtos

Cada produto ganha um separador AEO Schema no painel de dados do WooCommerce (Produto → Editar).

Campos disponíveis

• Marca: substitui a marca global para este produto. Na sua ausência, o plugin procura um atributo pa_brand ou brand.
• GTIN / EAN / UPC: 8, 12, 13 ou 14 dígitos. A propriedade gtin8/12/13/14 correspondente é acrescentada automaticamente consoante o comprimento.
• MPN: referência do fabricante.
• Materiais: separados por vírgulas (por exemplo «couro, algodão reciclado»). Um único material produz uma cadeia, vários produzem um array.
• Compatível com: um elemento por linha. Cada linha torna-se uma entrada isRelatedTo do tipo Product.

FAQ dirigida a agentes de IA

Por baixo dos campos, a secção FAQ dirigida a agentes permite acrescentar pares de pergunta e resposta curtos e factuais (compatibilidade exata, dimensões, ingredientes, certificações). Alimentam um schema FAQPage em JSON-LD separado, emitido apenas nas páginas de produto que tenham pelo menos uma entrada. Esta FAQ é invisível do lado do cliente: não aparece no tema, existe apenas para os agentes.

Campos Schema.org acrescentados

No objeto Product: brand, gtin (mais gtin8/12/13/14), mpn, material, color, size, weight, height, width, depth (QuantitativeValue com as unidades do WooCommerce), isRelatedTo e speakable. Em cada Offer: seller (Organization com o nome e o URL do site), hasMerchantReturnPolicy (país, janela em dias, tipo de custos) e shippingDetails (destino, deliveryTime com handlingTime de 0 a 1 dia e transitTime de 1 a 5 dias).

Os campos color e size são retomados automaticamente dos atributos pa_color / color e pa_size / size, se existirem. O peso e as dimensões vêm dos campos de expedição nativos do produto.

Compatibilidade com os plugins de SEO

O plugin atua exclusivamente através do filtro nativo woocommerce_structured_data_product, que só toca no JSON-LD gerado pelo próprio WooCommerce. O Yoast SEO, o RankMath e o SEO Press emitem os seus blocos de forma independente através do wp_head: não há colisão. Os valores já presentes no schema do WooCommerce são preservados.

Hooks para programadores

• dfllmstxtaeo_llms_output: filtra o conteúdo final do llms.txt. Argumentos: o conteúdo (string) e o código do idioma.
• dfllmstxtaeo_product_schema: filtra o array de schema enriquecido antes da saída. Argumentos: o array de markup e o objeto WC_Product.

add_filter( 'dfllmstxtaeo_product_schema', function ( $markup, $product ) {
    $markup['award'] = 'Prémio de design 2026';
    return $markup;
}, 10, 2 );

Resolução de problemas

• O /llms.txt devolve um 404: volte a guardar os permalinks (Definições → Permalinks → Guardar).
• O ficheiro não reflete uma alteração recente: a cache é limpa na edição, mas pode forçar colocando a duração da cache a 0 temporariamente, ou voltando a guardar as definições.
• O FAQPage não aparece: verifique que o produto tem pelo menos um par de pergunta e resposta completo e que a opção «Emitir o schema FAQPage» está ativa.
• Validar o schema: teste um URL de produto com o validador do schema.org ou com a ferramenta de resultados enriquecidos da Google para visualizar o JSON-LD completo.