# AI Competitor: monitorização de preços da concorrência

> Apresentação O AI Competitor vigia os preços dos seus concorrentes diretamente a partir do back office do PrestaShop. Declara um concorrente uma vez, com o seu nome e os seus…

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

## Apresentação

O AI Competitor vigia os preços dos seus concorrentes diretamente a partir do back office do PrestaShop. Declara um concorrente uma vez, com o seu nome e os seus seletores; o módulo pode depois obter a lista completa dos seus produtos a partir do sitemap, relacioná-la com o seu catálogo, ler os preços em intervalos regulares, detetar as variações significativas, avisá-lo por email e propor-lhe um preço ajustado à sua estratégia.

Compatível com PrestaShop 8.0 a 9.x, PHP 7.4 a 8.3, multiloja nativo. Sem dependências Composer, sem biblioteca JavaScript externa.

## Instalação

1. No seu back office, abra **Módulos → Gestor de módulos → Carregar um módulo**.
2. Carregue o ficheiro `dfaicompetitor.zip`.
3. O módulo cria as suas tabelas e o menu **Catálogo → AI Competitor**, que reúne seis páginas: painel, concorrentes, URLs monitorizados, catálogo do concorrente, relatórios e análises, importação/exportação.

Após a instalação é gerado um token de cron único. Encontra-o no painel do módulo.

### Atualização a partir de uma versão 1.0.x

Basta carregar o novo ZIP por cima da instalação existente. O script de atualização cria as novas tabelas, acrescenta as colunas em falta e, sobretudo, **gera um perfil de concorrente para cada nome de concorrente já utilizado** antes de lhe associar os URLs correspondentes. Os seus dados existentes são conservados e não há nada a reintroduzir.

Reinstalar um pacote com o mesmo número de versão do que já está instalado não repete o script de atualização, e a opcache do PHP pode continuar a servir os ficheiros antigos. Verifique sempre o número de versão apresentado no painel depois de um carregamento.

## Configuração inicial

Abra **Catálogo → AI Competitor**. O painel reúne as estatísticas e cinco blocos de configuração.

### Fornecedor de IA

O recurso à IA é facultativo mas recomendado: é ele que assume quando um site da concorrência não expõe nem dados estruturados nem um seletor aproveitável. São suportados três fornecedores:

- **Mistral AI** (predefinido), o mais económico, modelo aconselhado: `mistral-small-latest`
- **Anthropic Claude**, a melhor precisão em páginas complexas, modelo aconselhado: `claude-haiku-4-5-20251001`
- **OpenAI**, bom compromisso, modelo aconselhado: `gpt-4o-mini`

Introduza a chave API do fornecedor escolhido. É apresentada mascarada; deixe o campo vazio numa gravação posterior para conservar a chave. Paga diretamente ao fornecedor, sem sobrecusto DataFirefly.

### Alertas

- **Email de notificação**: destinatário dos resumos de alertas e do relatório semanal.
- **Limiar de variação** em percentagem, 3 % por omissão. Abaixo disso não é criado qualquer alerta.
- **Dia do relatório semanal**, segunda-feira por omissão.

### Scraping

- **URLs por lote de cron**: número de URLs lidos em cada execução, 20 por omissão.
- **Intervalo por omissão** em horas, aplicado aos novos URLs, 24 h por omissão.
- **Timeout HTTP** e **User-Agent**. O User-Agent fornecido identifica o robot pelo nome (`DataFireflyBot`); alguns sites aceitam um robot identificado que de outro modo bloqueariam.
- **Retenção do histórico** em dias, 180 por omissão.

### Rastreio do catálogo

- **Páginas por bloco**: número de fichas da concorrência abertas numa passagem, 15 por omissão.
- **Segundos por bloco**: orçamento de tempo de cada passagem, 20 por omissão. Mantenha-o abaixo do seu `max_execution_time` do PHP.
- **Limiar de correspondência**: semelhança mínima de títulos para aceitar uma correspondência automática, 82 por omissão.
- **Monitorizar automaticamente as correspondências**: cria um URL monitorizado assim que uma página rastreada é relacionada com um dos seus produtos. Desativado por omissão.
- **Fazer avançar os rastreios a partir do cron**: ativo por omissão.

### Estratégia de ajuste

Três estratégias determinam o preço sugerido, sempre calculado a partir do concorrente mais barato:

- **Igualar**: o mesmo preço do concorrente mais baixo.
- **Undercut de X %**: X % abaixo, 1 % por omissão.
- **Premium a X %**: X % acima, para um posicionamento de gama alta assumido.

## Declarar um concorrente

Desde a versão 1.1.0, um concorrente é uma ficha própria e não uma simples etiqueta reescrita em cada URL. Abra **Catálogo → AI Competitor → Concorrentes → Adicionar**. A ficha divide-se em três separadores.

### Identidade

O nome apresentado em todo o lado, o domínio sem esquema (`exemplo.pt`), a moeda, o intervalo de leitura, a opção de extração por IA forçada e um campo de notas livres. É o domínio que permite ao módulo associar automaticamente um novo URL ao concorrente correto.

### Seletores

Os seletores CSS do preço, do nome do produto, do SKU, da imagem e da disponibilidade. Deixe-os vazios se o site publicar JSON-LD, o que acontece na maioria das lojas modernas. Sintaxe suportada: etiqueta, `.classe`, `#identificador`, `[atributo=valor]`, descendente e filho direto. Exemplo: `div.product-price > span.amount`

É o principal ganho da ficha de concorrente: no dia em que um site refaz o tema e parte um seletor, corrige-o aqui uma só vez e a correção propaga-se a todos os URLs desse concorrente que não tenham um seletor próprio.

### Rastreio do catálogo

O URL do sitemap (deixe vazio para ler as diretivas `Sitemap:` do robots.txt do domínio), o URL de uma página de categoria de partida, o seletor das ligações de produto e o da ligação para a página seguinte, os padrões de URL a reter ou a descartar, o atraso entre dois pedidos, o teto de produtos e o respeito pelo robots.txt.

Os padrões aceitam uma simples subcadeia ou uma expressão regular delimitada por barras. Numa loja portuguesa, `/produto/` como padrão a reter chega muitas vezes para isolar as fichas de produto num sitemap que contém também o blogue e as páginas CMS.

## Rastrear o catálogo de um concorrente

Abra **Catálogo → AI Competitor → Catálogo do concorrente**, escolha o concorrente, a fonte de descoberta e o teto de produtos, e lance o rastreio.

Estão disponíveis duas fontes:

- **Sitemap**, recomendado. O módulo lê o sitemap configurado ou o anunciado pelo robots.txt, segue os índices de sitemaps de forma recursiva e retém os endereços que correspondem aos seus padrões.
- **Páginas de categoria**, quando nenhum sitemap é aproveitável. O módulo parte do URL de listagem, recolhe as ligações de produto através do seletor do concorrente e segue a ligação para a página seguinte.

À descoberta segue-se uma fase de enriquecimento que abre cada página, extrai título, SKU, EAN, marca, preço, disponibilidade e imagem, e tenta a correspondência com o seu catálogo.

O rastreio avança por blocos limitados no tempo, conduzidos pela página aberta com uma barra de progresso, e retoma em cada passagem do cron. Um sitemap com dezenas de milhares de URLs é processado sem nunca atingir o `max_execution_time` do PHP. Pode fechar a página: o trabalho prossegue do lado do cron.

### A correspondência com o seu catálogo

O módulo tenta três vias, por ordem decrescente de fiabilidade:

1. **EAN13**, procurado nos seus produtos e nas suas variantes. Correspondência certa, pontuação 100.
2. **Referência**, referência de fornecedor ou MPN. Pontuação 95.
3. **Semelhança de título**, com uma ponderação que dá mais peso aos números de modelo e às marcas do que às palavras comuns, e uma penalização quando os dois títulos têm comprimentos muito diferentes. A pontuação tem de ultrapassar o limiar configurado, 82 por omissão.

Cada linha do catálogo mostra o método e a pontuação da sua correspondência. Uma correspondência duvidosa corrige-se à mão: o campo de correspondência propõe preenchimento automático sobre o seu catálogo, por nome ou por referência. Os botões **Corresponder de novo** relançam a operação sobre as linhas sem correspondência, ou sobre todas, o que é útil depois de ter corrigido referências do seu lado.

Uma linha com correspondência torna-se um URL monitorizado através do botão **Monitorizar**, ou em massa pela ação de grupo sobre uma seleção. O URL criado herda o nome, os seletores, a moeda e o intervalo do concorrente.

## Acrescentar um URL à mão

O rastreio não substitui a introdução pontual. Abra **Catálogo → AI Competitor → URLs monitorizados → Adicionar**:

- **Concorrente**: a ficha de que o URL vai herdar. Deixe vazio para introduzir tudo à mão.
- **Produto**: selecionado no seu catálogo.
- **URL**: o endereço completo da ficha de produto do concorrente.
- **Nome do concorrente, seletor CSS, moeda, intervalo**: preenchidos a partir do concorrente quando os deixa vazios.

Se não escolher um concorrente, o módulo procura aquele cujo domínio corresponde ao endereço introduzido e associa-lhe o URL. O botão **Scrape** de cada linha lança uma leitura imediata, prático para validar um URL logo após a criação.

### Como funciona a extração

Para cada URL o módulo tenta quatro métodos em cascata e para no primeiro que resulta:

1. **JSON-LD**: os dados estruturados Product/Offer, presentes na grande maioria dos sites de comércio eletrónico. Preço, moeda, disponibilidade e, para o rastreio, título, SKU, GTIN e marca são lidos diretamente sem configuração.
2. **OpenGraph**: as etiquetas meta product price amount.
3. **Seletor CSS**: o do concorrente, ou o próprio do URL se tiver um.
4. **IA**: um excerto HTML limpo é enviado ao seu fornecedor, que devolve o preço, a moeda e o estado de stock. Os formatos de preço internacionais são geridos (1 299,90 tal como 1.234,56 ou $49.99).

Comece sempre sem seletor CSS: o JSON-LD chega na maioria dos casos. Acrescente um seletor ou a IA forçada apenas se a coluna Status mostrar `no_price`.

## Importação e exportação

A página **Importação / Exportação** serve para levar uma configuração de uma loja para outra.

### Concorrentes em JSON

A exportação produz um ficheiro com os nomes, domínios, seletores e definições de rastreio. Marque os concorrentes a incluir, ou não marque nenhum para exportar todos. Na importação, a correspondência faz-se primeiro pelo nome e depois pelo domínio; uma caixa decide se um concorrente já presente é atualizado ou ignorado, e um modo de pré-visualização anuncia o resultado sem escrever nada.

### URLs monitorizados em CSV

Colunas esperadas: `product_id`, `product_reference`, `competitor_name`, `competitor_domain`, `url`, `price_selector`, `currency_iso`, `use_ai_extraction`, `scrape_interval_hours`, `active`.

Só `competitor_name` e `url` são obrigatórias, mais `product_id` ou `product_reference` para saber a que produto associar o URL. Um nome de concorrente desconhecido cria a sua ficha automaticamente, pelo que um único ficheiro basta para arrancar uma instalação inteira. O separador é detetado automaticamente, e a importação arranca em modo de pré-visualização, que relata linha a linha o que seria criado, atualizado ou ignorado.

### Catálogo do concorrente em CSV

Exportação de tudo o que o rastreio descobriu, com o produto correspondente, o método e a pontuação. Uma caixa restringe a exportação apenas às linhas com correspondência. Prático para uma auditoria offline ou para partilhar com a equipa de compras.

## Configurar o cron

O funcionamento periódico assenta num endpoint protegido por token, apresentado no painel. Programe a sua chamada a cada 30 minutos:

```
*/30 * * * * curl -s "https://a-sua-loja.pt/index.php?fc=module&module=dfaicompetitor&controller=cron&token=O_SEU_TOKEN" > /dev/null
```

Em cada execução, o cron lê o lote de URLs cujo intervalo expirou, envia os emails de alerta pendentes, expede o relatório semanal se for o dia certo, faz avançar um bloco de um rastreio de catálogo em curso e limpa o histórico para além da retenção configurada. A resposta é um JSON de resumo.

O token pode ser regenerado a qualquer momento a partir do painel, caso em que os crons existentes têm de ser atualizados. Existe também um arranque manual através do botão **Run cron now**.

## Alertas

São gerados cinco tipos de alerta, cada um com uma gravidade:

- **price_drop / price_rise**: variação acima do limiar. Uma variação igual ou superior a 10 % passa a critical.
- **undercut**: um concorrente desce abaixo do seu preço de venda com IVA. Sempre critical.
- **out_of_stock / back_in_stock**: transições de disponibilidade detetadas pelos dados estruturados ou pela IA.
- **scrape_error**: apenas ao fim de 3 falhas consecutivas, para eliminar o ruído das indisponibilidades passageiras.

Os alertas são agrupados num único email de resumo por execução do cron.

## Relatórios e análises

O ecrã **Relatórios e análises** cabe em quatro separadores, atrás de uma faixa de indicadores apresentada em permanência: produtos comparados, proporção de produtos em que é o mais barato, diferença média face ao preço mínimo do mercado, alertas abertos, saúde do scraping. Um seletor de período cobre 7, 30 ou 90 dias.

### Visão geral

A sua posição no mercado sob a forma de barra (o mais barato, no meio, o mais caro), os produtos onde perde no preço ordenados por diferença decrescente, aqueles onde tem margem para subir, uma tabela por concorrente que indica quem o bate mais vezes, e a síntese executiva redigida pela IA. As oportunidades exportam-se em CSV.

### Alertas

A lista filtrável por tipo, gravidade, estado e texto livre, com um gráfico do volume diário por gravidade. Cada linha confirma-se ou reabre-se sem recarregar a página, e o contador de alertas abertos atualiza-se na faixa.

### Análise de produto

Escolha um produto monitorizado: o módulo traça o seu preço face ao de cada concorrente no período, mostra a sugestão de ajuste com o preço atual e o proposto lado a lado, e lista as fontes com um botão de leitura imediata em cada uma.

Desde a versão 1.1.0, cada leitura regista também o seu próprio preço do momento. É o que torna reconstituível o histórico das diferenças. Numa loja atualizada a partir de uma 1.0.x, a curva do seu preço só é exata a partir das leituras posteriores à atualização; antes dessa data o módulo usa o seu preço atual como recurso.

### Saúde

Os URLs que falham, com o seu estado, o número de falhas consecutivas, o último erro e um botão para repetir, mais uma taxa de sucesso por concorrente. É o primeiro sítio a consultar quando um número parece errado: um concorrente cujo scraping caiu distorce as médias.

## Sugestão de preço

No separador de análise de produto, o módulo mostra o seu preço atual, o mínimo, a média e o máximo dos concorrentes, as fontes e o preço sugerido segundo a sua estratégia. O botão **Aplicar** escreve o preço no produto PrestaShop.

A aplicação nunca é automática. É uma escolha deliberada para evitar as espirais de descida em espelho entre concorrentes equipados com o mesmo tipo de ferramenta. A conversão de preço com IVA para preço sem IVA é gerida automaticamente segundo a taxa de imposto do produto.

## Resolução de problemas

### O rastreio não descobre qualquer página

Verifique primeiro se o domínio do concorrente está indicado sem esquema e sem `www.`. Abra depois `https://dominio/robots.txt` num navegador: se não contiver qualquer diretiva `Sitemap:`, indique o URL do sitemap à mão na ficha do concorrente. Se o sitemap existe mas nada é retido, o seu padrão de filtragem é provavelmente demasiado restrito: esvazie-o para ver o que aparece e depois aperte-o.

### O rastreio descobre páginas que não são produtos

Indique no padrão a reter o segmento comum às fichas de produto do site, por exemplo `/produto/` ou `/p/`, e no padrão a descartar o que polui o resultado, por exemplo `/blog/`. Esvazie depois o catálogo do concorrente e relance.

### Muitas páginas ficam sem correspondência

Veja primeiro se as fichas da concorrência expõem um SKU ou um EAN: sem identificador comum, só a semelhança de título pode funcionar. Indique o seletor de SKU na ficha do concorrente, relance o rastreio e use depois **Corresponder de novo**. Se os seus títulos diferem muito dos do concorrente, baixe o limiar de correspondência para 75 e verifique as correspondências obtidas antes de o deixar assim.

### Estado «no_price»

Nenhum dos métodos encontrou preço. Verifique o URL num navegador, acrescente um seletor CSS de preço na ficha do concorrente, ou ative a extração por IA forçada.

### Estado «error» ou «blocked»

`error` significa que a página não respondeu (HTTP 400 e acima, ou timeout). `blocked` significa que o robots.txt do site proíbe esse endereço ao nosso robot. No primeiro caso, personalize o User-Agent, aumente o timeout ou alargue o intervalo. No segundo, é uma decisão do site visado que lhe cabe avaliar.

### A extração por IA não funciona

Verifique se a chave API é válida e se o modelo existe no seu fornecedor. Os erros de chamada à IA são registados em **Parâmetros avançados → Registos** com o prefixo `[dfaicompetitor]`.

### Os emails não chegam

Teste a configuração de email do PrestaShop em **Parâmetros avançados → E-mail**. O módulo usa o sistema de correio nativo com os seus próprios modelos FR e EN.

## Boas práticas e conformidade

- Deixe ativo o respeito pelo robots.txt. Aplica-se tanto à descoberta como à leitura das fichas, respeita um `Crawl-delay` publicado e aplica a regra de precedência da norma: entre um `Allow` e um `Disallow` que correspondem ambos, ganha a regra mais longa.
- Mantenha um atraso entre pedidos de pelo menos um segundo e um teto de produtos razoável no primeiro rastreio de um site que não conhece.
- Alargue os intervalos de leitura: 6 a 24 h por URL chegam bem para vigilância de preços.
- Conserve um User-Agent identificável. É a prática leal esperada em vigilância concorrencial, e alguns sites toleram um robot identificado que de outro modo bloqueariam.
- A leitura de preços públicos é em geral lícita na Europa, mas continua responsável pelo uso dos dados recolhidos e pela avaliação das condições de utilização dos sites visitados.