# DataFirefly Indexing API — Documentazione
> Panoramica DataFirefly Indexing API invia automaticamente i prodotti, le categorie e le pagine CMS del tuo negozio PrestaShop ai due canali di invio diretto esistenti: IndexNow tramite il relay api.indexnow.org,…
- Pagina:
- Lingua: it
- Aggiornato il: 2026-07-28
- Altre lingue: [fr](https://www.datafirefly.com/documentation/datafirefly-indexing-api-prestashop/index.md), [en](https://www.datafirefly.com/en/documentation/datafirefly-indexing-api-prestashop/index.md), [es](https://www.datafirefly.com/es/documentation/datafirefly-indexing-api-prestashop/index.md), [de](https://www.datafirefly.com/de/documentation/datafirefly-indexing-api-prestashop/index.md), [pl](https://www.datafirefly.com/pl/documentation/datafirefly-indexing-api-prestashop/index.md), [nl](https://www.datafirefly.com/nl/documentation/datafirefly-indexing-api-prestashop/index.md), [pt](https://www.datafirefly.com/pt/documentation/datafirefly-indexing-api-prestashop/index.md)
- Indice:
## Panoramica
DataFirefly Indexing API invia automaticamente i prodotti, le categorie e le pagine CMS del tuo negozio PrestaShop ai due canali di invio diretto esistenti: **IndexNow** tramite il relay `api.indexnow.org`, che propaga a Bing, Yandex, Naver e Seznam in una sola chiamata, e **Google Indexing API** (autenticazione Service Account OAuth2, firma JWT RS256 nativa). Il modulo si aggancia agli hook nativi PrestaShop, accoda ogni modifica in una coda con deduplica, e un CRON elabora il lotto ogni pochi minuti. Mantieni un registro completo degli invii e una dashboard del tasso di accettazione.
**Da leggere prima di configurare Google:** Google limita ufficialmente la sua Indexing API alle pagine che contengono dati strutturati `JobPosting`, oppure `BroadcastEvent` integrato in un `VideoObject`. Una scheda prodotto o una pagina categoria non rientra in nessuno dei due casi. L'API accetta comunque l'invio e risponde 200, ma quel codice significa solo che la notifica è stata ricevuta, non che l'URL verrà sottoposto a crawling né indicizzato. Per un catalogo e-commerce, **IndexNow è il canale che produce un effetto misurabile**: configuralo per primo e considera Google un canale secondario registrato.
**In sintesi:** i tuoi nuovi prodotti e le modifiche delle schede vengono inviati a Bing, Yandex, Naver e Seznam nei minuti successivi, senza abbonamenti di terzi né commissioni per URL. Sul lato Google, l'invio accelera la scoperta senza garanzia di indicizzazione.
## Requisiti
- PrestaShop 8.0 a 8.99, o PrestaShop 9.x
- PHP 7.4 a 8.3
- Estensioni PHP `openssl` (per la firma JWT RS256 di Google) e `curl` (per le richieste HTTP)
- Un CRON di sistema o un servizio CRON esterno per chiamare l'elaborazione della coda ogni 5 a 15 minuti
- **Opzionale, per Google:** un account Google Cloud con un progetto dove attivare l'Indexing API e creare un Service Account, e una proprietà Search Console verificata per il tuo dominio
## Installazione
### Passo 1: download
Scarica il ZIP `dfindexingapi-1.0.0.zip` dal tuo account DataFirefly dopo l'acquisto.
### Passo 2: installazione dal back-office
1. Connettiti al tuo back-office PrestaShop
2. Vai a **Moduli › Gestore moduli › Carica un modulo**
3. Clicca su **Seleziona file** e scegli il ZIP scaricato
4. Convalida. PrestaShop decomprime e installa il modulo
5. Una volta installato, clicca su **Configura**
### Passo 3: verifiche post-installazione
All'installazione, il modulo crea automaticamente:
- Le due tabelle SQL `ps_df_indexapi_queue` (coda) e `ps_df_indexapi_log` (registro)
- Una chiave IndexNow alfanumerica di 32 caratteri
- Un token CRON casuale di 32 caratteri
- 5 tab nel menu admin: padre **DataFirefly Indexing API**, poi **Dashboard**, **Coda**, **Registro**, **Configurazione**
Apri la tab **Configurazione** per passare al passo successivo.
## Configurazione di IndexNow
IndexNow è il canale da configurare per primo: senza Service Account, senza OAuth, senza quota e senza restrizioni sul tipo di pagina. Solo una chiave da pubblicare alla radice del tuo dominio.
### Capire IndexNow
IndexNow è un protocollo aperto promosso da Microsoft Bing e Yandex nel 2021, al quale si sono uniti Naver e Seznam. Generi una chiave alfanumerica, la pubblichi alla radice del tuo dominio come file accessibile pubblicamente, e chiami `api.indexnow.org` con una lista di URL. Il server verifica la chiave leggendo il file sul tuo dominio, poi propaga gli URL ai motori partecipanti. Schede prodotto, categorie e pagine CMS rientrano nel suo perimetro normale.
### Metodo 1: riscrittura .htaccess (consigliata)
È il metodo più semplice: il modulo serve esso stesso il contenuto del file chiave tramite un controller frontend, e una regola `.htaccess` alla radice del tuo negozio reindirizza la richiesta a quel controller.
1. Nella configurazione del modulo, apri la tab **IndexNow**
2. Spunta **Attiva IndexNow**
3. Verifica il campo **Host**, che deve corrispondere al dominio del tuo negozio senza il protocollo (ad esempio `mio-negozio.it`)
4. Salva
5. Copia lo snippet `.htaccess` mostrato nella pagina di configurazione, generato dinamicamente con la tua chiave attuale
6. Incolla questo snippet in cima al file `.htaccess` alla radice di PrestaShop, subito dopo il blocco `RewriteEngine on`
7. Clicca su **Testa IndexNow** nella configurazione: il modulo chiama l'URL del file chiave sul tuo dominio e verifica che restituisca il contenuto previsto come `text/plain`
### Metodo 2: file fisico
Se non puoi modificare il `.htaccess`, crea manualmente un file fisico alla radice del dominio.
1. Recupera la tua chiave IndexNow dalla configurazione del modulo (campo **Chiave IndexNow**)
2. Crea un file il cui nome sia esattamente **la chiave + .txt** (ad esempio `a1b2c3d4e5f6.txt`) alla radice del tuo dominio
3. Il contenuto del file deve essere solo la chiave stessa, senza interruzione di riga
4. Verifica che `https://tuo-dominio.com/a1b2c3d4e5f6.txt` restituisca la chiave come `text/plain`
5. Clicca su **Testa IndexNow**
Puoi rigenerare la chiave IndexNow in qualsiasi momento dalla configurazione (pulsante **Rigenera chiave**). Ricordati di aggiornare lo snippet `.htaccess` o il file fisico di conseguenza.
## Configurazione di Google Indexing API
**Perimetro ufficiale:** Google riserva questa API alle pagine `JobPosting` oppure `BroadcastEvent` dentro un `VideoObject`. Su un catalogo prodotti resta tecnicamente utilizzabile (l'API risponde 200 e il modulo registra la risposta), ma su crawling e indicizzazione decide unicamente Google. Questa sezione è facoltativa: il modulo funziona perfettamente anche con il solo IndexNow.
L'API Google Indexing richiede un Service Account di Google Cloud. La procedura richiede circa 5 minuti.
### Passo 1: creare un progetto Google Cloud
1. Vai a [console.cloud.google.com](https://console.cloud.google.com) e accedi
2. In alto, clicca sul selettore di progetto, poi **Nuovo progetto**
3. Dagli un nome (ad esempio _Indexing API Negozio_) e crealo
4. Seleziona il progetto appena creato
### Passo 2: attivare l'Indexing API
1. Nel menu di sinistra, vai a **APIs e servizi › Libreria**
2. Cerca _Indexing API_
3. Clicca su **Attiva**
### Passo 3: creare un Service Account
1. Vai a **APIs e servizi › Credenziali**
2. Clicca su **Crea credenziali › Account di servizio**
3. Dagli un nome (ad esempio _indexing-api-prestashop_)
4. Nessun ruolo IAM necessario: passa al passo successivo e finalizza la creazione
5. Nella lista degli account di servizio, clicca sull'account creato
6. Tab **Chiavi › Aggiungi chiave › Crea nuova chiave**
7. Formato **JSON**. Scarica e conserva il file, non potrà essere recuperato dopo
**Sicurezza:** il file JSON contiene la chiave privata del Service Account. Non condividerlo mai pubblicamente e non caricarlo in un repository Git.
### Passo 4: aggiungere il Service Account a Search Console
1. Copia l'email del Service Account (forma `nome@progetto.iam.gserviceaccount.com`) da Google Cloud
2. Vai a [Google Search Console](https://search.google.com/search-console)
3. Seleziona la tua proprietà (il dominio del tuo negozio)
4. Vai a **Impostazioni › Utenti e autorizzazioni**
5. Clicca su **Aggiungi utente**, incolla l'email del Service Account, seleziona il ruolo **Proprietario**
6. Convalida
Il ruolo **Proprietario** è richiesto da Google Indexing API. I ruoli **Limitato** o **Completo** non bastano, l'API restituirà `403 Permission denied`.
### Passo 5: incollare il JSON nel modulo
1. Apri il file JSON scaricato in un editor di testo
2. Copia tutto il suo contenuto
3. Nella configurazione del modulo, sezione **Google Indexing API**, spunta **Attiva Google Indexing API**
4. Incolla il JSON completo nel campo **Service Account JSON**
5. Salva
### Passo 6: testare la connessione
Clicca sul pulsante **Testa Google** nella pagina di configurazione. Il modulo firma un JWT RS256, lo scambia contro un token OAuth2 e mostra il risultato. Se tutto è corretto, vedi un messaggio verde _Autenticazione OK_. Questo test valida l'autenticazione, non che Google terrà conto dei tuoi URL.
## Configurazione del CRON
Il CRON è l'elemento che fa funzionare l'elaborazione della coda. Senza un CRON chiamato regolarmente, gli invii si accumulano ma non partono mai.
### Azione process: elaborazione della coda
Da chiamare **ogni 5 a 15 minuti**. Il modulo elabora un lotto configurabile (predefinito 50 job) seguendo la deduplica e i filtri di indicizzazione, poi aggiorna il registro e la coda.
L'URL esatto è mostrato nella configurazione. Ha questo aspetto:
```
https://tuo-dominio.com/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=process&token=IL_TUO_TOKEN
```
### Azione purge: pulizia del registro
Da chiamare **una volta al giorno**. Il modulo elimina i job e i log elaborati oltre la ritenzione configurata (predefinito 30 giorni).
```
https://tuo-dominio.com/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=purge&token=IL_TUO_TOKEN
```
### Azione key: file chiave IndexNow
Utilizzata solo dalla riscrittura `.htaccess`. Non chiami mai questo URL manualmente.
### Configurare il tuo CRON di sistema
Su Linux/cPanel, aggiungi due righe in crontab:
```
# Ogni 10 minuti: elaborazione della coda
*/10 * * * * curl -s "https://tuo-dominio.com/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=process&token=IL_TUO_TOKEN" > /dev/null
# Una volta al giorno alle 3: purge del registro
0 3 * * * curl -s "https://tuo-dominio.com/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=purge&token=IL_TUO_TOKEN" > /dev/null
```
### Sicurezza del token CRON
Il token è un segreto di 32 caratteri generato all'installazione. Senza il token corretto nel parametro `token=`, il controller restituisce HTTP 403. Puoi rigenerare il token in qualsiasi momento dalla configurazione (pulsante **Rigenera token CRON**), ricordando poi di aggiornare le tue righe crontab con il nuovo token.
## La Dashboard
La tab **Dashboard** è la tua vista d'insieme in tempo reale. Misura la salute tecnica delle chiamate API, non l'indicizzazione effettiva delle tue pagine.
### Contatori della coda
Cinque card in cima alla pagina:
- **In attesa**: job creati ma non ancora elaborati
- **In elaborazione**: job bloccati in elaborazione da un CRON attivo
- **Inviato**: job elaborati con successo (cumulo storico non purgato)
- **Errore**: job che hanno fallito dopo N tentativi massimi
- **Saltato**: job creati ma ignorati da un filtro (ad esempio URL_DELETED per IndexNow)
### Diagnostica dei provider
Due card mostrano lo stato di configurazione:
- **Google Indexing API**: attivo, mal configurato, o disattivato. Indica se il JSON Service Account è presente e valido
- **IndexNow**: attivo, mal configurato, o disattivato. Indica se la chiave e l'host sono configurati
### Tasso di accettazione a 30 giorni
Tabella incrociata provider × stato sugli ultimi 30 giorni, con colorazione semantica: verde sopra il 90%, arancione tra 60 e 90%, rosso sotto. Se Google scende sotto il 90%, di solito è segno che hai superato la quota o che gli URL non sono più accessibili. Un tasso di accettazione del 100% significa che le tue notifiche sono state ricevute, non che gli URL siano stati indicizzati.
### Grafico degli invii quotidiani
Grafico Chart.js che sovrappone due curve giornaliere: totale inviato e totale accettato. Utile per individuare rapidamente cali o picchi anomali.
## La Coda
La tab **Coda** elenca tutti i job (pending, processing, submitted, error, skipped) con filtri nativi PrestaShop per negozio, tipo di oggetto, ID, provider, stato, data.
### Stati dei job
- **pending**: creato, in attesa di elaborazione dal prossimo CRON
- **processing**: bloccato da un CRON attivo (transizione logica per evitare doppia elaborazione in parallelo)
- **submitted**: invio riuscito all'API. Il contatore di tentativi è congelato
- **error**: tutti i tentativi hanno fallito. Rimane visibile con il messaggio di errore esatto restituito dall'API
- **skipped**: creato e poi ignorato (ad esempio URL_DELETED IndexNow, o filtro disattivato)
### Azioni per riga
Ogni riga offre:
- **Rilancia**: riporta il job in pending e azzera il contatore di tentativi
- **Elimina**: cancella il job dalla coda
### Azioni in blocco
Pulsanti in cima alla lista:
- **Rilancia tutti i job in errore**: riporta in pending tutti i job in stato errore
- **Purga job elaborati**: elimina tutti gli submitted/skipped indipendentemente dall'età
## Il Registro
La tab **Registro** elenca ogni invio individuale effettuato: provider, tipo, ID di oggetto, URL inviato, azione (URL_UPDATED o URL_DELETED), codice HTTP restituito, indicatore accettato/rifiutato, messaggio completo di risposta e data. Filtrabile, ordinabile, esportabile come CSV tramite l'HelperList standard di PrestaShop.
Se Google rifiuta un URL con codice HTTP 400 e messaggio _Unable to fetch URL_, di solito significa che l'URL non è accessibile pubblicamente (modalità manutenzione attiva, robots.txt che blocca, redirect in loop, ecc.). Verifica l'URL in un browser in navigazione privata.
## Filtri di indicizzazione
Nella configurazione, puoi attivare o disattivare indipendentemente tre tipi di oggetti:
- **Prodotti**: invio su creazione, modifica, eliminazione, disattivazione
- **Categorie**: invio su creazione, modifica, eliminazione. La radice di categoria (ID 1 e 2) è ignorata per sicurezza
- **Pagine CMS**: invio su creazione, modifica, eliminazione
Disattivare un filtro ferma immediatamente l'accodamento per quel tipo, ma non purga la coda esistente. Su un catalogo grande, restringere i filtri lato Google è il riflesso giusto per non esaurire la quota di 200 URL al giorno.
## Multi-negozio
Il modulo è nativamente multi-negozio. La configurazione (chiavi Google, chiave IndexNow, host, attivazioni) è indipendente per sub-negozio. I job e i log sono delimitati per `id_shop`: lo stesso prodotto in due sub-negozi genera due job distinti con i propri URL canonici.
Per configurare indipendentemente ogni sub-negozio, usa il selettore multistore in cima all'admin prima di aprire la configurazione.
## Hook PrestaShop ascoltati
Il modulo registra i seguenti hook all'installazione:
- `actionProductSave`: creazione o modifica di un prodotto. Se attivo, accoda URL_UPDATED; altrimenti URL_DELETED
- `actionProductDelete`: eliminazione definitiva di un prodotto. Accoda URL_DELETED
- `actionObjectCmsAddAfter`: creazione di pagina CMS
- `actionObjectCmsUpdateAfter`: modifica di pagina CMS
- `actionObjectCmsDeleteAfter`: eliminazione di pagina CMS
- `actionCategoryAdd`: creazione di categoria
- `actionCategoryUpdate`: modifica di categoria
- `actionCategoryDelete`: eliminazione di categoria
- `displayBackOfficeHeader`: iniezione di frammento CSS per lo stile della dashboard
Ogni hook costruisce l'URL canonico tramite l'oggetto `Link` ufficiale di PrestaShop, il che rispetta le tue preferenze **SEO friendly URL** e i prefissi di lingua multilingua.
## Risoluzione dei problemi
### Il test Google fallisce con codice 401
L'autenticazione è fallita. Verifica che:
- Il JSON Service Account incollato sia completo e ben formato
- L'Indexing API sia ben attivata in Google Cloud (libreria)
- L'orologio del sistema del server sia corretto: uno scostamento di più di 5 minuti invalida il JWT
### Il test Google fallisce con codice 403
L'autenticazione riesce ma Google rifiuta la richiesta. Causa abituale: il Service Account non è stato aggiunto come **Proprietario** della proprietà Search Console. Riverifica il passo 4 della configurazione Google.
### Il test IndexNow fallisce
Il server api.indexnow.org non è riuscito a leggere il file chiave sul tuo dominio. Possibili cause:
- Lo snippet `.htaccess` non è stato incollato, o incollato nel posto sbagliato (deve essere dopo `RewriteEngine on`)
- Il file fisico non è stato creato, o non ha il nome corretto (deve essere esattamente _la chiave + .txt_)
- Il contenuto del file non corrisponde alla chiave (errore di battitura, interruzione di riga aggiuntiva)
- Il server web serve il file con il Content-Type sbagliato (deve essere `text/plain`)
- Il firewall o il CDN blocca le richieste del robot IndexNow
Apri `https://tuo-dominio.com/LA_TUA_CHIAVE.txt` in un browser in navigazione privata: devi vedere solo la chiave come testo semplice.
### Job bloccati nello stato processing
Significa che un CRON ha bloccato i job ma non ha mai rilasciato il lock (ad esempio il processo è stato terminato da un timeout PHP). Puoi sbloccarli manualmente tramite phpMyAdmin:
```
UPDATE ps_df_indexapi_queue SET status = 'pending', attempts = 0 WHERE status = 'processing';
```
Se il problema si ripete regolarmente, aumenta il `max_execution_time` PHP del tuo hosting, o riduci la dimensione del lotto nella configurazione del modulo.
### Quota Google superata
Google risponde con codice 429 o messaggio _Quota exceeded_. La quota predefinita è di 200 URL al giorno per Service Account.
**Non contare su un aumento di quota.** Google offre un modulo di richiesta, ma l'approvazione è condizionata all'uso effettivo del markup `JobPosting` o `BroadcastEvent` sul sito. Un catalogo e-commerce non soddisfa questo criterio: la richiesta verrà rifiutata. Considera i 200 URL al giorno come un tetto fisso.
Tre opzioni realistiche:
- Aspettare 24h, dato che la quota si reimposta giornalmente
- Restringere i filtri di indicizzazione lato Google ai tipi che contano davvero per te (ad esempio solo prodotti, disattivando categorie e CMS)
- Creare un secondo Service Account e alternare, avendo ogni Service Account la propria quota di 200 URL al giorno
Promemoria: IndexNow non ha quota. Se il volume è il tuo vincolo principale, è il canale su cui appoggiarsi.
### Reinizializzazione completa
Per ripartire da zero (utile in caso di migrazione o problema complesso):
1. Disinstallare il modulo da Moduli › Gestore
2. Reinstallare: le tabelle vengono ricreate, la chiave IndexNow e il token CRON vengono rigenerati
3. Riconfigurare Google e IndexNow
4. Aggiornare lo snippet `.htaccess` con la nuova chiave
5. Aggiornare le righe crontab con il nuovo token
La disinstallazione elimina la coda e il registro, ma non elimina gli invii già effettuati lato Google o IndexNow: rimangono nei loro storici rispettivi.
## Limitazioni note
- **Google Indexing API ufficialmente limitata** alle pagine `JobPosting` oppure `BroadcastEvent` dentro un `VideoObject`. L'API accetta altri tipi e risponde 200, ma quel codice attesta solo la ricezione della notifica. Per un catalogo prodotti, IndexNow è il canale principale e Google un complemento registrato
- **Quota Google limitata** a 200 URL al giorno per Service Account, senza aumento realistico disponibile per un e-commerce (vedi Risoluzione dei problemi)
- **IndexNow non gestisce URL_DELETED**: il protocollo considera un 404 o 410 sull'URL come il modo corretto di segnalare un'eliminazione. Il modulo ignora quindi i job IndexNow in URL_DELETED (Google li invia correttamente)
- **Varianti di prodotti non inviate individualmente**: l'URL canonico del prodotto principale basta, Google consolida le varianti naturalmente
- **Radice di categoria ignorata** (ID 1 e 2) per evitare di inviare URL non pertinenti
- **Il modulo non sostituisce una sitemap XML**: la sitemap resta il canale di scoperta ufficiale e deve restare pulita e aggiornata. L'invio diretto si aggiunge sopra, non la rimpiazza
## Supporto
Per qualsiasi domanda tecnica: [support@datafirefly.com](mailto:support@datafirefly.com), risposta entro 24h lavorative in italiano, inglese o francese. Incluso per 12 mesi dopo l'acquisto.