# DataFirefly Indexing API: dokumentacja
> Prezentacja DataFirefly Indexing API automatycznie zgłasza produkty, kategorie i strony CMS Twojego sklepu PrestaShop do dwóch istniejących kanałów bezpośredniego zgłaszania: IndexNow przez relay api.indexnow.org, który jednym wywołaniem propaguje do Bing,…
- Strona:
- Język: pl
- Zaktualizowano: 2026-08-01
- Inne języki: [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), [it](https://www.datafirefly.com/it/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)
- Indeks:
## Prezentacja
DataFirefly Indexing API automatycznie zgłasza produkty, kategorie i strony CMS Twojego sklepu PrestaShop do dwóch istniejących kanałów bezpośredniego zgłaszania: **IndexNow** przez relay `api.indexnow.org`, który jednym wywołaniem propaguje do Bing, Yandex, Naver i Seznam, oraz **Google Indexing API** (uwierzytelnianie Service Account OAuth2, natywne podpisywanie JWT RS256). Moduł podpina się do natywnych hooków PrestaShop, kolejkuje każdą modyfikację w kolejce z deduplikacją, a CRON przetwarza partie co kilka minut. Zachowujesz pełny dziennik zgłoszeń i pulpit ze wskaźnikiem akceptacji.
**Do przeczytania przed konfiguracją Google:** Google oficjalnie ogranicza swoje Indexing API do stron z danymi strukturalnymi `JobPosting` albo `BroadcastEvent` osadzonym w `VideoObject`. Karta produktu ani strona kategorii nie mieszczą się w żadnym z tych przypadków. API mimo to przyjmuje zgłoszenie i odpowiada 200, ale ten kod oznacza wyłącznie, że powiadomienie zostało odebrane, a nie że adres zostanie zescrapowany czy zaindeksowany. Dla katalogu e-commerce **to IndexNow daje mierzalny efekt**: skonfiguruj go w pierwszej kolejności, a Google traktuj jako kanał drugorzędny zapisywany w dzienniku.
**W skrócie:** Twoje nowe produkty i modyfikacje kart trafiają do Bing, Yandex, Naver i Seznam w ciągu kilku minut, bez abonamentu zewnętrznego i bez prowizji od adresu. Po stronie Google zgłoszenie przyspiesza odkrycie bez gwarancji indeksacji.
## Wymagania
- PrestaShop 8.0 do 8.99 albo PrestaShop 9.x
- PHP 7.4 do 8.3
- Rozszerzenia PHP `openssl` (do podpisywania JWT RS256 dla Google) i `curl` (do zapytań HTTP)
- CRON systemowy albo zewnętrzna usługa CRON do wywoływania przetwarzania kolejki co 5 do 15 minut
- **Opcjonalnie, dla Google:** konto Google Cloud z projektem, w którym włączysz Indexing API i utworzysz Service Account, oraz zweryfikowana usługa Search Console dla Twojej domeny
## Instalacja
### Krok 1: pobranie
Pobierz ZIP `dfindexingapi-1.0.0.zip` ze swojego konta DataFirefly po zakupie.
### Krok 2: instalacja z back office
1. Zaloguj się do back office PrestaShop
2. Przejdź do **Moduły › Menedżer modułów › Zainstaluj moduł**
3. Kliknij **Wybierz plik** i wskaż pobrany ZIP
4. Zatwierdź. PrestaShop rozpakuje i zainstaluje moduł
5. Po instalacji kliknij **Konfiguruj**
### Krok 3: weryfikacja po instalacji
Przy instalacji moduł tworzy automatycznie:
- Dwie tabele SQL `ps_df_indexapi_queue` (kolejka) i `ps_df_indexapi_log` (dziennik)
- 32-znakowy alfanumeryczny klucz IndexNow
- 32-znakowy losowy token CRON
- 5 zakładek w menu administracyjnym: nadrzędna **DataFirefly Indexing API**, a pod nią **Pulpit**, **Kolejka**, **Dziennik**, **Konfiguracja**
Otwórz zakładkę **Konfiguracja**, aby przejść do kolejnego kroku.
## Konfiguracja IndexNow
IndexNow to kanał do skonfigurowania jako pierwszy: bez Service Account, bez OAuth, bez limitu i bez ograniczeń co do typu strony. Wystarczy klucz opublikowany w katalogu głównym Twojej domeny.
### Jak działa IndexNow
IndexNow to otwarty protokół forsowany przez Microsoft Bing i Yandex w 2021 roku, do którego dołączyły później Naver i Seznam. Generujesz klucz alfanumeryczny, publikujesz go w katalogu głównym domeny jako publicznie dostępny plik i wywołujesz `api.indexnow.org` z listą adresów URL. Serwer weryfikuje klucz, odczytując plik z Twojej domeny, a następnie propaguje adresy do uczestniczących wyszukiwarek. Karty produktów, kategorie i strony CMS mieszczą się w jego normalnym zakresie.
### Metoda 1: przepisanie w pliku htaccess (zalecana)
To najprostsza metoda: moduł sam serwuje zawartość pliku klucza przez kontroler frontowy, a reguła w pliku `.htaccess` w katalogu głównym sklepu przepisuje żądanie do tego kontrolera.
1. W konfiguracji modułu otwórz zakładkę **IndexNow**
2. Zaznacz **Włącz IndexNow**
3. Sprawdź pole **Host**, które musi odpowiadać domenie sklepu bez protokołu (na przykład `moj-sklep.pl`)
4. Zapisz
5. Skopiuj snippet `.htaccess` wyświetlony na stronie konfiguracji, generowany dynamicznie z Twoim bieżącym kluczem
6. Wklej ten snippet na górze pliku `.htaccess` w katalogu głównym PrestaShop, zaraz za blokiem `RewriteEngine on`
7. Kliknij **Testuj IndexNow** w konfiguracji: moduł wywoła adres pliku klucza w Twojej domenie i sprawdzi, czy zwraca oczekiwaną zawartość jako `text/plain`
### Metoda 2: plik fizyczny
Jeśli nie możesz modyfikować pliku `.htaccess`, utwórz ręcznie plik fizyczny w katalogu głównym domeny.
1. Odczytaj swój klucz IndexNow z konfiguracji modułu (pole **Klucz IndexNow**)
2. Utwórz plik o nazwie dokładnie **klucz + .txt** (na przykład `a1b2c3d4e5f6.txt`) w katalogu głównym domeny
3. Zawartością pliku ma być wyłącznie sam klucz, bez znaku końca linii
4. Sprawdź, czy `https://twoja-domena.pl/a1b2c3d4e5f6.txt` zwraca klucz jako `text/plain`
5. Kliknij **Testuj IndexNow**
Klucz IndexNow możesz zregenerować w dowolnym momencie z konfiguracji (przycisk **Zregeneruj klucz**). Pamiętaj wtedy o odpowiedniej aktualizacji snippetu `.htaccess` albo pliku fizycznego.
## Konfiguracja Google Indexing API
**Oficjalny zakres:** to API jest zarezerwowane przez Google dla stron `JobPosting` albo `BroadcastEvent` w `VideoObject`. Na katalogu produktowym pozostaje technicznie używalne (API odpowiada 200, a moduł zapisuje odpowiedź), ale o crawlowaniu i indeksowaniu decyduje wyłącznie Google. Ta sekcja jest opcjonalna: moduł działa doskonale z samym IndexNow.
Google Indexing API wymaga konta usługi Google Cloud. Procedura zajmuje około 5 minut.
### Krok 1: utworzenie projektu Google Cloud
1. Wejdź na [console.cloud.google.com](https://console.cloud.google.com) i zaloguj się
2. U góry kliknij selektor projektu, a następnie **Nowy projekt**
3. Nadaj mu nazwę (na przykład _Indexing API Sklep_) i utwórz go
4. Wybierz nowo utworzony projekt
### Krok 2: włączenie Indexing API
1. W menu po lewej przejdź do **API i usługi › Biblioteka**
2. Wyszukaj _Indexing API_
3. Kliknij **Włącz**
### Krok 3: utworzenie Service Account
1. Przejdź do **API i usługi › Dane logowania**
2. Kliknij **Utwórz dane logowania › Konto usługi**
3. Nadaj mu nazwę (na przykład _indexing-api-prestashop_)
4. Żadna rola IAM nie jest potrzebna: przejdź do kolejnego kroku i zakończ tworzenie
5. Na liście kont usługi kliknij utworzone konto
6. Zakładka **Klucze › Dodaj klucz › Utwórz nowy klucz**
7. Format **JSON**. Pobierz i zachowaj plik, później nie będzie już możliwy do odzyskania
**Bezpieczeństwo:** plik JSON zawiera klucz prywatny konta usługi. Nigdy nie udostępniaj go publicznie i nie commituj do repozytorium Git.
### Krok 4: dodanie Service Account do Search Console
1. Skopiuj adres e-mail konta usługi (w postaci `nazwa@projekt.iam.gserviceaccount.com`) z Google Cloud
2. Wejdź do [Google Search Console](https://search.google.com/search-console)
3. Wybierz swoją usługę (domenę sklepu)
4. Przejdź do **Ustawienia › Użytkownicy i uprawnienia**
5. Kliknij **Dodaj użytkownika**, wklej adres konta usługi i wybierz rolę **Właściciel**
6. Zatwierdź
Rola **Właściciel** jest wymagana przez Google Indexing API. Rola **Czytelnik** albo **Pełne uprawnienia** nie wystarczy, API zwróci `403 Permission denied`.
### Krok 5: wklejenie JSON do modułu
1. Otwórz pobrany plik JSON w edytorze tekstu
2. Skopiuj całą jego zawartość
3. W konfiguracji modułu, sekcja **Google Indexing API**, zaznacz **Włącz Google Indexing API**
4. Wklej pełny JSON w pole **Service Account JSON**
5. Zapisz
### Krok 6: test połączenia
Kliknij przycisk **Testuj Google** na stronie konfiguracji. Moduł podpisze JWT RS256, wymieni go na token OAuth2 i wyświetli wynik. Jeśli wszystko jest poprawne, zobaczysz zielony komunikat _Uwierzytelnienie OK_. Ten test weryfikuje uwierzytelnienie, a nie uwzględnienie Twoich adresów przez Google.
## Konfiguracja CRON-a
CRON to element, który uruchamia przetwarzanie kolejki. Bez regularnie wywoływanego CRON-a zgłoszenia się piętrzą, ale nigdy nie wychodzą.
### Akcja process: przetwarzanie kolejki
Wywoływać **co 5 do 15 minut**. Moduł przetwarza konfigurowalną partię (domyślnie 50 zadań) z poszanowaniem deduplikacji i filtrów indeksowania, a następnie aktualizuje dziennik i kolejkę.
Dokładny adres jest wyświetlany w konfiguracji. Wygląda tak:
```
https://twoja-domena.pl/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=process&token=TWOJ_TOKEN
```
### Akcja purge: czyszczenie dziennika
Wywoływać **raz dziennie**. Moduł usuwa przetworzone zadania i logi powyżej skonfigurowanej retencji (domyślnie 30 dni).
```
https://twoja-domena.pl/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=purge&token=TWOJ_TOKEN
```
### Akcja key: plik klucza IndexNow
Używana wyłącznie przez przepisanie w pliku `.htaccess`. Tego adresu nigdy nie wywołujesz ręcznie.
### Konfiguracja CRON-a systemowego
W Linuksie lub cPanelu dodaj dwie linie w crontab:
```
# Co 10 minut: przetwarzanie kolejki
*/10 * * * * curl -s "https://twoja-domena.pl/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=process&token=TWOJ_TOKEN" > /dev/null
# Raz dziennie o 3:00: czyszczenie dziennika
0 3 * * * curl -s "https://twoja-domena.pl/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=purge&token=TWOJ_TOKEN" > /dev/null
```
### Bezpieczeństwo tokenu CRON
Token to 32-znakowy sekret generowany przy instalacji. Bez poprawnego tokenu w parametrze `token=` kontroler zwraca HTTP 403. Token możesz zregenerować w dowolnym momencie z konfiguracji (przycisk **Zregeneruj token CRON**), pamiętając wtedy o aktualizacji linii crontab nowym tokenem.
## Pulpit
Zakładka **Pulpit** to Twój przegląd w czasie rzeczywistym. Mierzy techniczną kondycję wywołań API, a nie faktyczną indeksację Twoich stron.
### Liczniki kolejki
Pięć kart u góry strony:
- **Oczekujące**: zadania utworzone, ale jeszcze nieprzetworzone
- **W trakcie**: zadania zablokowane w przetwarzaniu przez aktywny CRON
- **Zgłoszone**: zadania przetworzone pomyślnie (suma historyczna nieusunięta)
- **Błąd**: zadania, które zawiodły po N maksymalnych próbach
- **Pominięte**: zadania utworzone, ale pominięte przez filtr (na przykład URL_DELETED w IndexNow)
### Diagnostyka dostawców
Dwie karty pokazują stan konfiguracji:
- **Google Indexing API**: aktywny, źle skonfigurowany albo wyłączony. Wskazuje, czy JSON Service Account jest obecny i poprawny
- **IndexNow**: aktywny, źle skonfigurowany albo wyłączony. Wskazuje, czy klucz i host są skonfigurowane
### Wskaźnik akceptacji 30 dni
Tabela krzyżowa dostawca × status z ostatnich 30 dni, z kolorowaniem semantycznym: zielony powyżej 90 %, pomarańczowy między 60 a 90 %, czerwony poniżej. Jeśli Google spada poniżej 90 %, zwykle oznacza to przekroczenie limitu albo brak dostępności części adresów. Wskaźnik akceptacji 100 % oznacza, że Twoje powiadomienia zostały odebrane, a nie że adresy zostały zaindeksowane.
### Wykres dziennych zgłoszeń
Wykres Chart.js nakładający dwie krzywe dzienne: łącznie zgłoszone i łącznie zaakceptowane. Przydatny do szybkiego wychwycenia spadków lub nietypowych szczytów.
## Kolejka
Zakładka **Kolejka** listuje wszystkie zadania (pending, processing, submitted, error, skipped) z natywnymi filtrami PrestaShop po sklepie, typie obiektu, ID, dostawcy, statusie i dacie.
### Statusy zadań
- **pending**: utworzone, oczekuje na przetworzenie przez kolejny CRON
- **processing**: zablokowane przez aktywny CRON (przejście logiczne zapobiegające podwójnemu przetwarzaniu równolegle)
- **submitted**: zgłoszenie do API powiodło się. Licznik prób jest zamrożony
- **error**: wszystkie próby zawiodły. Pozostaje do wglądu z dokładnym komunikatem błędu zwróconym przez API
- **skipped**: utworzone, a następnie pominięte (na przykład URL_DELETED w IndexNow albo wyłączony filtr)
### Akcje indywidualne
Każdy wiersz oferuje:
- **Ponów**: przywraca zadanie do statusu pending i resetuje licznik prób
- **Usuń**: kasuje zadanie z kolejki
### Akcje masowe
Przyciski u góry listy:
- **Ponów wszystkie zadania w błędzie**: przywraca do statusu pending wszystkie zadania ze statusem error
- **Wyczyść przetworzone zadania**: usuwa wszystkie submitted i skipped niezależnie od ich wieku
## Dziennik
Zakładka **Dziennik** listuje każde wykonane zgłoszenie: dostawca, typ, ID obiektu, zgłoszony adres URL, akcja (URL_UPDATED albo URL_DELETED), zwrócony kod HTTP, wskaźnik zaakceptowane lub odrzucone, pełny komunikat odpowiedzi i data. Filtrowalny, sortowalny, eksportowalny do CSV przez standardowy HelperList PrestaShop.
Jeśli Google odrzuca adres z kodem HTTP 400 i komunikatem _Unable to fetch URL_, zwykle oznacza to, że adres nie jest publicznie dostępny (aktywny tryb konserwacji, blokada w robots.txt, pętla przekierowań itd.). Sprawdź adres w przeglądarce w trybie prywatnym.
## Filtry indeksowania
W konfiguracji możesz niezależnie włączać i wyłączać trzy typy obiektów:
- **Produkty**: zgłoszenie przy utworzeniu, modyfikacji, usunięciu, dezaktywacji
- **Kategorie**: zgłoszenie przy utworzeniu, modyfikacji, usunięciu. Kategorie główne (ID 1 i 2) są pomijane dla bezpieczeństwa
- **Strony CMS**: zgłoszenie przy utworzeniu, modyfikacji, usunięciu
Wyłączenie filtra natychmiast zatrzymuje kolejkowanie dla tego typu, ale nie czyści istniejącej kolejki. Na dużym katalogu ograniczenie filtrów po stronie Google to właściwy odruch, aby nie wyczerpać limitu 200 adresów dziennie.
## Multistore
Moduł jest natywnie wielosklepowy. Konfiguracja (klucze Google, klucz IndexNow, host, aktywacje) jest niezależna per podsklep. Zadania i logi są ograniczone po `id_shop`: ten sam produkt w dwóch podsklepach generuje dwa osobne zadania z własnymi adresami kanonicznymi.
Aby skonfigurować każdy podsklep niezależnie, użyj selektora multistore u góry panelu administracyjnego przed otwarciem konfiguracji.
## Nasłuchiwane hooki PrestaShop
Moduł rejestruje przy instalacji następujące hooki:
- `actionProductSave`: utworzenie lub modyfikacja produktu. Jeśli aktywny, kolejkuje URL_UPDATED, w przeciwnym razie URL_DELETED
- `actionProductDelete`: trwałe usunięcie produktu. Kolejkuje URL_DELETED
- `actionObjectCmsAddAfter`: utworzenie strony CMS
- `actionObjectCmsUpdateAfter`: modyfikacja strony CMS
- `actionObjectCmsDeleteAfter`: usunięcie strony CMS
- `actionCategoryAdd`: utworzenie kategorii
- `actionCategoryUpdate`: modyfikacja kategorii
- `actionCategoryDelete`: usunięcie kategorii
- `displayBackOfficeHeader`: wstrzyknięcie fragmentu CSS do stylizacji pulpitu
Każdy hook buduje adres kanoniczny przez oficjalny obiekt `Link` PrestaShop, co respektuje Twoje ustawienia **przyjaznych adresów SEO** i wielojęzyczne prefiksy językowe.
## Rozwiązywanie problemów
### Test Google kończy się kodem 401
Uwierzytelnienie się nie powiodło. Sprawdź, czy:
- Wklejony JSON Service Account jest kompletny i poprawnie sformowany
- Indexing API jest faktycznie włączone w Google Cloud (biblioteka)
- Zegar systemowy serwera jest poprawny: przesunięcie większe niż 5 minut unieważnia JWT
### Test Google kończy się kodem 403
Uwierzytelnienie się udaje, ale Google odrzuca żądanie. Typowa przyczyna: Service Account nie został dodany jako **Właściciel** usługi w Search Console. Zweryfikuj ponownie krok 4 konfiguracji Google.
### Test IndexNow kończy się niepowodzeniem
Serwer api.indexnow.org nie mógł odczytać pliku klucza w Twojej domenie. Możliwe przyczyny:
- Snippet `.htaccess` nie został wklejony albo został wklejony w złym miejscu (musi być po `RewriteEngine on`)
- Plik fizyczny nie został utworzony albo nie ma poprawnej nazwy (musi to być dokładnie _klucz + .txt_)
- Zawartość pliku nie odpowiada kluczowi (literówka, dodatkowy znak końca linii)
- Serwer WWW serwuje plik z niewłaściwym Content-Type (musi być `text/plain`)
- Firewall albo CDN blokuje żądania robota IndexNow
Otwórz `https://twoja-domena.pl/TWOJ_KLUCZ.txt` w przeglądarce w trybie prywatnym: powinieneś zobaczyć wyłącznie klucz jako czysty tekst.
### Zadania utykają w statusie processing
Oznacza to, że CRON zablokował zadania, ale nigdy nie zwolnił blokady (na przykład proces został ubity przez timeout PHP). Możesz je odblokować ręcznie przez phpMyAdmin:
```
UPDATE ps_df_indexapi_queue SET status = 'pending', attempts = 0 WHERE status = 'processing';
```
Jeśli problem powtarza się regularnie, zwiększ `max_execution_time` PHP na swoim hostingu albo zmniejsz rozmiar partii w konfiguracji modułu.
### Limit Google został przekroczony
Google odpowiada kodem 429 albo komunikatem _Quota exceeded_. Domyślny limit to 200 adresów dziennie na Service Account.
**Nie licz na zwiększenie limitu.** Google udostępnia wprawdzie formularz wniosku, ale zatwierdzenie jest uzależnione od faktycznego używania znaczników `JobPosting` albo `BroadcastEvent` na witrynie. Katalog e-commerce nie spełnia tego kryterium: wniosek zostanie odrzucony. Traktuj 200 adresów dziennie jako stały pułap.
Trzy realistyczne opcje:
- Odczekać 24 h, limit resetuje się codziennie
- Ograniczyć filtry indeksowania po stronie Google do typów, które naprawdę się dla Ciebie liczą (na przykład same produkty, z wyłączeniem kategorii i CMS)
- Utworzyć drugie Service Account i naprzemiennie z nich korzystać, każde ma własny limit 200 adresów dziennie
Przypomnienie: IndexNow nie ma żadnego limitu. Jeśli wolumen jest Twoim głównym ograniczeniem, to na tym kanale należy się oprzeć.
### Pełny reset
Aby zacząć od zera (przydatne przy migracji albo złożonym problemie):
1. Odinstaluj moduł z Moduły › Menedżer
2. Zainstaluj ponownie: tabele zostaną odtworzone, a klucz IndexNow i token CRON zregenerowane
3. Skonfiguruj ponownie Google i IndexNow
4. Zaktualizuj snippet `.htaccess` nowym kluczem
5. Zaktualizuj linie crontab nowym tokenem
Deinstalacja usuwa kolejkę i dziennik, ale nie usuwa zgłoszeń już wykonanych po stronie Google czy IndexNow: pozostają one w ich historiach.
## Znane ograniczenia
- **Google Indexing API oficjalnie ograniczone** do stron `JobPosting` albo `BroadcastEvent` w `VideoObject`. API przyjmuje inne typy i odpowiada 200, ale ten kod potwierdza wyłącznie odebranie powiadomienia. Dla katalogu produktowego IndexNow jest kanałem głównym, a Google uzupełnieniem zapisywanym w dzienniku
- **Limit Google zamknięty** na 200 adresach dziennie na Service Account, bez realnej możliwości zwiększenia dla e-commerce (patrz sekcja Rozwiązywanie problemów)
- **IndexNow nie obsługuje URL_DELETED**: protokół zakłada, że 404 albo 410 na adresie jest właściwym sposobem zasygnalizowania usunięcia. Moduł pomija więc zadania IndexNow z URL_DELETED (Google z kolei je zgłasza)
- **Warianty produktu nie są zgłaszane osobno**: adres kanoniczny produktu głównego wystarcza, Google naturalnie konsoliduje warianty
- **Kategorie główne pomijane** (ID 1 i 2), aby nie zgłaszać nieistotnych adresów
- **Moduł nie zastępuje sitemapy XML**: sitemapa pozostaje oficjalnym kanałem odkrywania i musi być czysta i aktualna. Bezpośrednie zgłaszanie dokłada się do niej, a nie ją zastępuje
## Wsparcie
W sprawach technicznych: [support@datafirefly.com](mailto:support@datafirefly.com), odpowiedź w ciągu 24 godzin roboczych po francusku lub angielsku. W cenie przez 12 miesięcy po zakupie.