DataFirefly Indexing API: documentação

Apresentação

O DataFirefly Indexing API submete automaticamente os produtos, categorias e páginas CMS da sua loja PrestaShop aos dois canais de submissão direta existentes: IndexNow através do relé api.indexnow.org, que propaga para Bing, Yandex, Naver e Seznam numa única chamada, e Google Indexing API (autenticação por Service Account OAuth2, assinatura JWT RS256 nativa). O módulo liga-se aos hooks nativos do PrestaShop, coloca cada alteração numa fila de espera sem duplicados, e um CRON trata o lote de poucos em poucos minutos. Mantém um registo completo das submissões e um painel da taxa de aceitação.

Pré-requisitos

• PrestaShop 8.0 a 8.99, ou PrestaShop 9.x
• PHP 7.4 a 8.3
• Extensões PHP openssl (para a assinatura JWT RS256 do Google) e curl (para os pedidos HTTP)
• Um CRON de sistema ou um serviço de CRON externo para chamar o tratamento da fila de espera a cada 5 a 15 minutos
• Opcional, para o Google: uma conta Google Cloud com um projeto onde ativar a Indexing API e criar um Service Account, e uma propriedade Search Console verificada para o seu domínio

Instalação

Passo 1: transferência

Transfira o ZIP dfindexingapi-1.0.0.zip a partir da sua conta DataFirefly após a compra.

Passo 2: instalação através do back-office

1. Inicie sessão no back-office do PrestaShop
2. Aceda a Módulos › Gestor de módulos › Instalar um módulo
3. Clique em Selecionar um ficheiro e escolha o ZIP transferido
4. Confirme. O PrestaShop descomprime e instala o módulo
5. Uma vez instalado, clique em Configurar

Passo 3: verificações pós-instalação

Na instalação, o módulo cria automaticamente:

• As duas tabelas SQL ps_df_indexapi_queue (fila de espera) e ps_df_indexapi_log (registo)
• Uma chave IndexNow alfanumérica de 32 caracteres
• Um token CRON aleatório de 32 caracteres
• 5 separadores no menu de administração: pai DataFirefly Indexing API, depois Painel, Fila de espera, Registo, Configuração

Abra o separador Configuração para passar ao passo seguinte.

Configuração do IndexNow

O IndexNow é o canal a configurar em primeiro lugar: sem Service Account, sem OAuth, sem quota e sem nenhuma restrição quanto ao tipo de página. Apenas uma chave a publicar na raiz do seu domínio.

Compreender o IndexNow

O IndexNow é um protocolo aberto impulsionado pelo Microsoft Bing e pelo Yandex em 2021, ao qual se juntaram desde então o Naver e o Seznam. Gera uma chave alfanumérica, publica-a na raiz do seu domínio sob a forma de um ficheiro acessível publicamente, e chama api.indexnow.org com uma lista de URLs. O servidor verifica a chave lendo o ficheiro do seu domínio e propaga depois os URLs aos motores participantes. Páginas de produto, categorias e páginas CMS estão no seu âmbito normal.

Método 1: reescrita .htaccess (recomendado)

É o método mais simples: o próprio módulo serve o conteúdo do ficheiro de chave através de um controlador front-office, e uma regra .htaccess na raiz da sua loja reescreve o pedido para esse controlador.

1. Na configuração do módulo, abra o separador IndexNow
2. Assinale Ativar IndexNow
3. Verifique o campo Anfitrião, que deve corresponder ao domínio da sua loja sem o protocolo (por exemplo a-minha-loja.pt)
4. Guarde
5. Copie o excerto .htaccess apresentado na página de configuração, gerado dinamicamente com a sua chave atual
6. Cole esse excerto no topo do ficheiro .htaccess na raiz do PrestaShop, logo a seguir ao bloco RewriteEngine on
7. Clique em Testar IndexNow na configuração: o módulo chama o URL do ficheiro de chave no seu domínio e verifica que devolve o conteúdo esperado em text/plain

Método 2: ficheiro físico

Se não puder modificar o .htaccess, crie manualmente um ficheiro físico na raiz do domínio.

1. Obtenha a sua chave IndexNow na configuração do módulo (campo Chave IndexNow)
2. Crie um ficheiro cujo nome seja exatamente a chave + .txt (por exemplo a1b2c3d4e5f6.txt) na raiz do seu domínio
3. O conteúdo do ficheiro deve ser apenas a própria chave, sem quebra de linha
4. Verifique que https://o-seu-dominio.pt/a1b2c3d4e5f6.txt devolve a chave em text/plain
5. Clique em Testar IndexNow

Configuração da Google Indexing API

A API Google Indexing exige um Service Account Google Cloud. O procedimento demora cerca de 5 minutos.

Passo 1: criar um projeto Google Cloud

1. Aceda a console.cloud.google.com e inicie sessão
2. No topo, clique no seletor de projeto e depois em Novo projeto
3. Dê-lhe um nome (por exemplo Indexing API Loja) e crie-o
4. Selecione o projeto acabado de criar

Passo 2: ativar a Indexing API

1. No menu da esquerda, aceda a APIs e serviços › Biblioteca
2. Pesquise Indexing API
3. Clique em Ativar

Passo 3: criar um Service Account

1. Aceda a APIs e serviços › Credenciais
2. Clique em Criar credenciais › Conta de serviço
3. Dê-lhe um nome (por exemplo indexing-api-prestashop)
4. Não é necessário nenhum papel IAM: passe ao passo seguinte e finalize a criação
5. Na lista de contas de serviço, clique na conta criada
6. Separador Chaves › Adicionar uma chave › Criar uma nova chave
7. Formato JSON. Transfira e guarde o ficheiro, não poderá ser recuperado depois

Passo 4: adicionar o Service Account à Search Console

1. Copie o e-mail do Service Account (formato nome@projeto.iam.gserviceaccount.com) a partir do Google Cloud
2. Aceda à Google Search Console
3. Selecione a sua propriedade (o domínio da sua loja)
4. Aceda a Definições › Utilizadores e permissões
5. Clique em Adicionar utilizador, cole o e-mail do Service Account e selecione o papel Proprietário
6. Confirme

Passo 5: colar o JSON no módulo

1. Abra o ficheiro JSON transferido num editor de texto
2. Copie todo o seu conteúdo
3. Na configuração do módulo, secção Google Indexing API, assinale Ativar Google Indexing API
4. Cole o JSON completo no campo Service Account JSON
5. Guarde

Passo 6: testar a ligação

Clique no botão Testar Google na página de configuração. O módulo assina um JWT RS256, troca-o por um token OAuth2 e apresenta o resultado. Se tudo estiver correto, verá uma mensagem verde Autenticação OK. Este teste valida a autenticação, não a consideração dos seus URLs pelo Google.

Configuração do CRON

O CRON é o elemento que faz correr o tratamento da fila de espera. Sem um CRON chamado regularmente, as submissões acumulam-se mas nunca partem.

Ação process: tratamento da fila de espera

A chamar a cada 5 a 15 minutos. O módulo trata um lote configurável (por defeito 50 jobs) respeitando a desduplicação e os filtros de indexação, e atualiza depois o registo e a fila.

O URL exato é apresentado na configuração. Tem este aspeto:

https://o-seu-dominio.pt/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=process&token=O_SEU_TOKEN

Ação purge: limpeza do registo

A chamar uma vez por dia. O módulo elimina os jobs e registos tratados para além da retenção configurada (por defeito 30 dias).

https://o-seu-dominio.pt/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=purge&token=O_SEU_TOKEN

Ação key: ficheiro de chave IndexNow

Utilizada apenas pela reescrita .htaccess. Nunca chama este URL manualmente.

Configurar o seu CRON de sistema

Em Linux/cPanel, adicione duas linhas ao crontab:

# A cada 10 minutos: tratamento da fila de espera
*/10 * * * * curl -s "https://o-seu-dominio.pt/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=process&token=O_SEU_TOKEN" > /dev/null

# Uma vez por dia às 3h: limpeza do registo
0 3 * * * curl -s "https://o-seu-dominio.pt/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=purge&token=O_SEU_TOKEN" > /dev/null

Segurança do token CRON

O token é um segredo de 32 caracteres gerado na instalação. Sem o token correto no parâmetro token=, o controlador devolve HTTP 403. Pode regenerar o token a qualquer momento a partir da configuração (botão Regenerar o token CRON), lembrando-se nesse caso de atualizar as suas linhas de crontab com o novo token.

O Painel

O separador Painel é a sua vista geral em tempo real. Mede a saúde técnica das chamadas à API, não a indexação efetiva das suas páginas.

Contadores da fila de espera

Cinco cartões no topo da página:

• Pendentes: jobs criados mas ainda não tratados
• Em curso: jobs bloqueados em tratamento por um CRON ativo
• Submetidos: jobs tratados com sucesso (acumulado histórico não limpo)
• Erro: jobs que falharam após N tentativas máximas
• Ignorados: jobs criados mas ignorados por um filtro (por exemplo URL_DELETED no IndexNow)

Diagnóstico dos fornecedores

Dois cartões mostram o estado de configuração:

• Google Indexing API: ativo, mal configurado ou desativado. Indica se o JSON do Service Account está presente e é válido
• IndexNow: ativo, mal configurado ou desativado. Indica se a chave e o anfitrião estão configurados

Taxa de aceitação a 30 dias

Tabela cruzada fornecedor × estado nos últimos 30 dias, com coloração semântica: verde acima de 90%, laranja entre 60 e 90%, vermelho abaixo. Se o Google cair abaixo de 90%, é geralmente sinal de que excedeu a quota ou de que há URLs que deixaram de estar acessíveis. Uma taxa de aceitação de 100% significa que as suas notificações foram recebidas, não que os URLs foram indexados.

Gráfico das submissões diárias

Gráfico Chart.js sobrepondo duas curvas por dia: total submetido e total aceite. Útil para detetar rapidamente quedas ou picos anormais.

A Fila de espera

O separador Fila de espera lista todos os jobs (pending, processing, submitted, error, skipped) com filtros nativos do PrestaShop por loja, tipo de objeto, ID, fornecedor, estado, data.

Estados dos jobs

• pending: criado, à espera de tratamento pelo próximo CRON
• processing: bloqueado por um CRON ativo (transição lógica para evitar o tratamento duplo em paralelo)
• submitted: submissão à API bem-sucedida. O contador de tentativas é congelado
• error: todas as tentativas falharam. Continua consultável com a mensagem de erro exata devolvida pela API
• skipped: criado e depois ignorado (por exemplo URL_DELETED no IndexNow, ou filtro desativado)

Ações individuais

Cada linha propõe:

• Relançar: volta a colocar o job em pending e reinicia o contador de tentativas
• Eliminar: apaga o job da fila

Ações em massa

Botões no topo da lista:

• Relançar todos os jobs em erro: volta a colocar em pending todos os jobs com estado error
• Limpar os jobs tratados: elimina todos os submitted/skipped, qualquer que seja a sua idade

O Registo

O separador Registo lista cada submissão individual realizada: fornecedor, tipo, ID do objeto, URL submetido, ação (URL_UPDATED ou URL_DELETED), código HTTP devolvido, indicador aceite/recusado, mensagem completa da resposta e data. Filtrável, ordenável, exportável em CSV através do HelperList padrão do PrestaShop.

Filtros de indexação

Na configuração, pode ativar ou desativar de forma independente três tipos de objetos:

• Produtos: submissão na criação, modificação, eliminação, desativação
• Categorias: submissão na criação, modificação, eliminação. A raiz das categorias (ID 1 e 2) é ignorada por segurança
• Páginas CMS: submissão na criação, modificação, eliminação

Desativar um filtro interrompe imediatamente o enfileiramento para esse tipo, mas não limpa a fila existente. Num catálogo grande, restringir os filtros do lado do Google é o reflexo certo para não esgotar a quota de 200 URLs por dia.

Multiloja

O módulo é nativamente multiloja. A configuração (chaves Google, chave IndexNow, anfitrião, ativações) é independente por subloja. Os jobs e os registos são delimitados por id_shop: um mesmo produto em duas sublojas gera dois jobs distintos com os seus próprios URLs canónicos.

Para configurar cada subloja de forma independente, use o seletor multiloja no topo da administração antes de abrir a configuração.

Hooks PrestaShop escutados

O módulo regista os seguintes hooks na instalação:

• actionProductSave: criação ou modificação de um produto. Se ativo, enfileira URL_UPDATED; caso contrário URL_DELETED
• actionProductDelete: eliminação definitiva de um produto. Enfileira URL_DELETED
• actionObjectCmsAddAfter: criação de uma página CMS
• actionObjectCmsUpdateAfter: modificação de uma página CMS
• actionObjectCmsDeleteAfter: eliminação de uma página CMS
• actionCategoryAdd: criação de uma categoria
• actionCategoryUpdate: modificação de uma categoria
• actionCategoryDelete: eliminação de uma categoria
• displayBackOfficeHeader: injeção de um fragmento CSS para o estilo do painel

Cada hook constrói o URL canónico através do objeto Link oficial do PrestaShop, o que respeita as suas preferências de URL amigáveis e os prefixos de idioma multilingue.

Resolução de problemas

O teste Google falha com um código 401

A autenticação falhou. Verifique que:

• O JSON do Service Account colado está completo e bem formado
• A Indexing API está ativada no Google Cloud (biblioteca)
• O relógio de sistema do servidor está correto: um desvio superior a 5 minutos invalida o JWT

O teste Google falha com um código 403

A autenticação é bem-sucedida mas o Google recusa o pedido. Causa habitual: o Service Account não foi adicionado como Proprietário da propriedade Search Console. Volte a verificar o passo 4 da configuração Google.

O teste IndexNow falha

O servidor api.indexnow.org não conseguiu ler o ficheiro de chave no seu domínio. Causas possíveis:

• O excerto .htaccess não foi colado, ou foi colado no sítio errado (deve estar depois de RewriteEngine on)
• O ficheiro físico não foi criado, ou não tem o nome correto (deve ser exatamente a chave + .txt)
• O conteúdo do ficheiro não corresponde à chave (erro de digitação, quebra de linha adicional)
• O servidor web serve o ficheiro com o Content-Type errado (deve ser text/plain)
• A firewall ou o CDN bloqueia os pedidos do robô IndexNow

Abra https://o-seu-dominio.pt/A_SUA_CHAVE.txt num navegador em modo de navegação privada: deve ver apenas a chave em texto simples.

Há jobs que ficam bloqueados no estado processing

Isso significa que um CRON bloqueou os jobs mas nunca libertou o lock (por exemplo, o processo foi terminado por um timeout PHP). Pode desbloqueá-los manualmente através do phpMyAdmin:

UPDATE ps_df_indexapi_queue SET status = 'pending', attempts = 0 WHERE status = 'processing';

Se o problema se repetir regularmente, aumente o max_execution_time PHP do seu alojamento, ou reduza o tamanho do lote na configuração do módulo.

A quota Google foi excedida

O Google responde com um código 429 ou uma mensagem Quota exceeded. A quota por defeito é de 200 URLs por dia por Service Account.

Três opções realistas:

• Esperar 24h, uma vez que a quota é reposta diariamente
• Restringir os filtros de indexação do lado do Google aos tipos que contam realmente para si (por exemplo apenas produtos, desativando categorias e CMS)
• Criar um segundo Service Account e alternar, tendo cada Service Account a sua própria quota de 200 URLs por dia

Lembrete: o IndexNow não tem quota. Se o volume for a sua principal restrição, é o canal em que se deve apoiar.

Reinicialização completa

Para recomeçar do zero (útil em caso de migração ou de problema complexo):

1. Desinstalar o módulo em Módulos › Gestor de módulos
2. Reinstalar: as tabelas são recriadas, a chave IndexNow e o token CRON são regenerados
3. Reconfigurar o Google e o IndexNow
4. Atualizar o excerto .htaccess com a nova chave
5. Atualizar as linhas de crontab com o novo token

Limitações conhecidas

• Google Indexing API oficialmente limitada às páginas JobPosting ou BroadcastEvent num VideoObject. A API aceita os outros tipos e responde 200, mas esse código atesta apenas a receção da notificação. Para um catálogo de produtos, o IndexNow é o canal principal e o Google um complemento registado
• Quota Google limitada a 200 URLs por dia por Service Account, sem aumento possível na prática para um e-commerce (ver a secção Resolução de problemas)
• O IndexNow não gere URL_DELETED: o protocolo considera que um 404 ou 410 no URL é a forma correta de sinalizar uma eliminação. O módulo ignora portanto os jobs IndexNow em URL_DELETED (o Google, esse, submete-os)
• Variantes de produto não submetidas individualmente: o URL canónico do produto principal é suficiente, o Google consolida naturalmente as variantes
• Raiz das categorias ignorada (ID 1 e 2) para evitar submeter URLs não relevantes
• O módulo não substitui um sitemap XML: o sitemap continua a ser o canal de descoberta oficial e deve manter-se limpo e atualizado. A submissão direta acrescenta-se por cima, não o substitui

Suporte

Para qualquer questão técnica: support@datafirefly.com, resposta em 24h úteis em francês ou inglês. Incluído durante 12 meses após a compra.