# LLMs.txt e AEO Shopware: guia completo

> Apresentação O DataFirefly LLMs.txt e AEO é uma extensão Shopware 6.7 que torna a sua loja visível e compreensível para os motores de resposta de IA (ChatGPT, Claude, Perplexity, Gemini).…

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

## Apresentação

O DataFirefly LLMs.txt e AEO é uma extensão Shopware 6.7 que torna a sua loja visível e compreensível para os motores de resposta de IA (ChatGPT, Claude, Perplexity, Gemini). Atua em três planos complementares:

- **llms.txt / llms-full.txt**: dois ficheiros conformes à especificação [llmstxt.org](https://llmstxt.org), gerados automaticamente na raiz de cada sales channel, em cada idioma ativo.
- **Schema.org JSON-LD**: injeção automática de dados estruturados em todas as páginas: Organization, Product enriquecido, BreadcrumbList, FAQPage, HowTo e Speakable.
- **Controlo dos crawlers de IA**: um endpoint `/robots-ai.txt` com controlo individual de 9 bots (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, Applebot-Extended, Bingbot, Meta-ExternalAgent, CCBot, cohere-ai).

**Pré-requisitos:** Shopware 6.7.0+, PHP 8.2+, MySQL 8.0+ ou MariaDB 10.6+. A extensão funciona no storefront normal e nos temas personalizados (herança Twig).

## Instalação

### Por ZIP (recomendado)

1. Transfira o `DataFireflyLlmsAeo.zip` a partir da sua conta de cliente.
2. Administração do Shopware → **Extensões → As minhas extensões → Carregar uma extensão**.
3. Clique em **Instalar** e depois em **Ativar**.
4. Limpe a cache: **Definições → Sistema → Cache e índice**, ou por CLI:

```
bin/console cache:clear
```

### Por CLI

```
unzip DataFireflyLlmsAeo.zip -d custom/plugins/
bin/console plugin:refresh
bin/console plugin:install --activate DataFireflyLlmsAeo
bin/console cache:clear
```

Na ativação, a extensão instala automaticamente o conjunto de campos personalizados `datafirefly_aeo` nos produtos, categorias, páginas CMS e fabricantes. Não é necessária qualquer migração manual.

### Compilação dos recursos de administração

Se o módulo de administração não aparecer em Marketing depois da ativação:

```
bin/console bundle:dump
./bin/build-administration.sh
bin/console cache:clear
```

## Configuração

A configuração encontra-se em **Definições → Sistema → Extensões → DataFirefly llms.txt e AEO**. Tem âmbito por sales channel: selecione um canal específico no seletor do topo para substituir os valores globais.

### Cartão «Geral»

- **Ativar o módulo**: interruptor global (por sales channel).
- **Autor do site**: usado no cabeçalho do llms.txt.
- **Descrição do site**: blockquote de cabeçalho do llms.txt; descreva a sua loja em 1 a 2 frases orientadas para a IA.
- **Duração da cache**: TTL em segundos (predefinição: 3600).

### Cartão «llms.txt»

- Incluir as **páginas CMS**, **categorias**, **marcas** e/ou **produtos**.
- **Número máximo de produtos** listados no índice.
- **Incluir os produtos inativos**: desativado por predefinição, a manter desativado em produção.

### Cartão «AEO e Schema.org»

- Interruptores individuais: Organization, Product enriquecido, BreadcrumbList, FAQPage, HowTo, Speakable.
- **Logotipo e URL da organização**: substituem os valores do sales channel.
- **Telefone, email de contacto, perfis sociais**: alimentam o esquema Organization (`contactPoint`, `sameAs`).

### Cartão «Crawlers de IA»

Para cada um dos 9 bots, três modos:

- **Autorizado**: acesso completo (sem diretiva restritiva).
- **Recusado**: `Disallow: /` para esse bot.
- **Seletivo**: `Disallow` nos caminhos que listar (um por linha, por exemplo `/checkout/`, `/account/`).

O conteúdo de `/robots-ai.txt` não é fundido automaticamente no seu `robots.txt` principal. Copie o seu conteúdo para o robots.txt, ou acrescente uma regra de reescrita no servidor (ver a secção [Integração no robots.txt](#robots-integracao)).

## Os três endpoints

| URL | Conteúdo | Cabeçalhos |
| --- | --- | --- |
| `/llms.txt` | Índice sintético: Páginas, Categorias, Marcas, Produtos, Optional | `text/plain; charset=UTF-8`, `X-Robots-Tag: noindex`, cache pública |
| `/llms-full.txt` | Conteúdo integral: descrições limpas, SKU, EAN, marca, características agrupadas, FAQ | idem |
| `/robots-ai.txt` | Bloco de diretivas User-agent para os 9 crawlers de IA | idem |

Verificação rápida após a instalação:

```
curl -I https://a-sua-loja.tld/llms.txt
curl -I https://a-sua-loja.tld/llms-full.txt
curl -I https://a-sua-loja.tld/robots-ai.txt
```

Cada sales channel expõe os seus próprios ficheiros no seu próprio domínio, em cada idioma ativo (os URLs localizados seguem a configuração de domínio do canal).

## Campos personalizados AEO

O conjunto `datafirefly_aeo` está disponível nos **produtos, categorias, páginas CMS e fabricantes**, no separador Campos personalizados de cada entidade.

| Campo | Tipo | Utilização |
| --- | --- | --- |
| `datafirefly_aeo_summary` | Texto | Resumo de 1 a 2 frases usado no llms.txt em vez da descrição truncada |
| `datafirefly_aeo_faq` | JSON | FAQ estruturada, injetada em FAQPage JSON-LD |
| `datafirefly_aeo_howto` | JSON | Tutorial estruturado, injetado em HowTo JSON-LD |
| `datafirefly_aeo_speakable` | Texto | Texto curto para assistentes de voz (30 a 40 palavras pronunciáveis) |
| `datafirefly_aeo_exclude` | Booleano | Exclui a entidade do llms.txt e do llms-full.txt |

### Formato do campo FAQ

```
[
  {
    "q": "Quanto tempo demora a entrega?",
    "a": "A entrega normal demora 2 a 4 dias úteis em Portugal continental."
  },
  {
    "q": "Qual é a vossa política de devolução?",
    "a": "Dispõe de 30 dias para devolver um produto não utilizado."
  }
]
```

### Formato do campo HowTo

```
{
  "name": "Como instalar o produto",
  "totalTime": "PT15M",
  "steps": [
    { "name": "Preparação", "text": "Desembale os componentes." },
    { "name": "Montagem", "text": "Siga o esquema fornecido." },
    { "name": "Verificação", "text": "Teste o funcionamento." }
  ]
}
```

Os campos personalizados do Shopware são traduzíveis: preencha a FAQ em cada idioma através do seletor de idioma da ficha do produto. A extensão lê o valor no idioma do contexto do pedido.

## Dados estruturados Schema.org

A extensão injeta JSON-LD no `` através do template `storefront/layout/meta.html.twig` (herança Twig, compatível com temas personalizados). Esquemas gerados:

- **Organization**: em todas as páginas: nome, logotipo, URL, `contactPoint`, `sameAs` (perfis sociais).
- **Product enriquecido**: nas páginas de produto: `gtin13` (a partir do EAN), `mpn`, `sku`, `brand` (fabricante), `additionalProperty` (características agrupadas por grupo de propriedades), `aggregateRating` (a partir das avaliações nativas do Shopware, se existirem).
- **BreadcrumbList**: caminho de navegação completo da página atual.
- **FAQPage**: se o campo `datafirefly_aeo_faq` estiver preenchido na entidade da página.
- **HowTo**: se o campo `datafirefly_aeo_howto` estiver preenchido.
- **Speakable**: seletores CSS `h1`, `.product-detail-name`, `.product-detail-description-text`, `.cms-element-text`, `[data-speakable]`, mais o texto do campo dedicado.

Validação recomendada depois de ir para produção:

- [Schema.org Validator](https://validator.schema.org/): cole o URL de uma página de produto.
- [Google Rich Results Test](https://search.google.com/test/rich-results).

## Módulo de administração

Em **Marketing → DataFirefly llms.txt e AEO**:

- **Pré-visualização em direto** do llms.txt ou do llms-full.txt, com renderização monoespaçada.
- **Seletor de sales channel**: pré-visualize cada canal de forma independente.
- **Invalidação da cache** num clique (por canal ou global).
- **Abertura do URL público** e **cópia para a área de transferência**.

## Comandos CLI e automatização

### datafirefly:llms-txt:generate

```
# Gerar o llms.txt de um sales channel (apresentado na saída padrão)
bin/console datafirefly:llms-txt:generate --sales-channel=<id>

# Versão completa, escrita num ficheiro, sem passar pela cache
bin/console datafirefly:llms-txt:generate --sales-channel=<id> --full --output=/tmp/llms-full.txt --no-cache
```

### datafirefly:llms-txt:warm

```
# Aquecer a cache de todos os sales channels x todos os idiomas ativos
bin/console datafirefly:llms-txt:warm

# Forçar a regeneração mesmo que a cache ainda seja válida
bin/console datafirefly:llms-txt:warm --force

# Aquecer apenas o llms.txt (sem o llms-full.txt)
bin/console datafirefly:llms-txt:warm --skip-full
```

### Cron recomendado

```
# Aquecimento diário às 03h15
15 3 * * * cd /var/www/shopware && php bin/console datafirefly:llms-txt:warm --quiet
```

É também registada na ativação uma **tarefa agendada do Shopware**: se o seu worker Messenger e o scheduled task runner estiverem a correr, a cache aquece automaticamente sem cron de sistema.

## Integração no robots.txt

Duas abordagens para expor as diretivas de IA no seu robots.txt principal:

### Cópia manual

Abra `/robots-ai.txt`, copie o bloco gerado e cole-o no seu robots.txt existente. A repetir depois de cada alteração da configuração dos bots.

### Reescrita no servidor (recomendada se o robots.txt for inteiramente gerido pela extensão)

```
# nginx
location = /robots.txt {
    rewrite ^ /robots-ai.txt last;
}

# Apache (.htaccess)
RewriteRule ^robots.txt$ /robots-ai.txt [L]
```

Só use a reescrita completa se não tiver outras diretivas de robots.txt a preservar (sitemap, exclusões SEO existentes). Em caso de dúvida, prefira a cópia manual do bloco de IA.

## Cache e desempenho

- Cache **PSR-6** no pool `cache.object` do Shopware, com a tag `datafirefly_llms_aeo`.
- Chaves com âmbito por **sales channel e idioma**: cada combinação tem a sua própria entrada.
- TTL configurável (predefinição 3600 s).
- Invalidação: botão na administração (por canal ou global), comando `warm --force`, ou expiração natural.
- Compatível com cache em cluster (Redis): a invalidação por tags funciona em todos os adaptadores com suporte a tags.

## Resolução de problemas

### Os endpoints devolvem 404

1. Verifique que a extensão está mesmo **ativa** (não apenas instalada).
2. Limpe a cache HTTP e a cache de aplicação: `bin/console cache:clear`.
3. Se usar um proxy inverso ou CDN, limpe-o também.

### Erro «Attempted to call an undefined method named getHeader» nas páginas de navegação

Erro corrigido na **versão 1.0.1**: em algumas instalações Shopware 6.7, a `NavigationPage` não expõe `getHeader()`. Atualize para a 1.0.1 (extração defensiva da categoria ativa). Se já estiver na 1.0.1 e continuar a ver o erro, limpe a cache de opcode do PHP (`opcache_reset` ou reinício do PHP-FPM).

### O módulo de administração não aparece em Marketing

Compile os recursos de administração (ver [Instalação](#instalacao-recursos)) e force o recarregamento do navegador (Ctrl+Shift+R).

### O llms.txt está vazio ou incompleto

1. Verifique os interruptores de inclusão (páginas CMS / categorias / marcas / produtos) no cartão «llms.txt».
2. Verifique que o limite de produtos não está a 0.
3. Controle o campo `datafirefly_aeo_exclude` nas entidades ausentes.
4. Invalide a cache e recarregue.

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

1. Verifique que «Ativar o módulo» e os interruptores Schema.org estão ativos para o sales channel certo.
2. Se o seu tema sobrepuser `storefront/layout/meta.html.twig` sem `{{ parent() }}` no bloco em causa, a injeção perde-se: reponha a chamada ao bloco pai.

## Changelog

### 1.0.1, 2026-05-21

- Correção: extração defensiva da categoria ativa nas páginas de navegação (erro `getHeader()` em algumas instalações 6.7).

### 1.0.0, 2026-05-21

- Versão inicial: llms.txt e llms-full.txt, 6 esquemas JSON-LD, robots-ai.txt (9 bots), campos personalizados AEO, módulo de administração em Vue 3, 2 comandos CLI, tarefa agendada, snippets FR/EN/DE.