# Dwukierunkowa synchronizacja Google Sheets: kompletny przewodnik
> Moduł DataFirefly Sheet Sync synchronizuje katalog PrestaShop z arkuszem Google w obie strony: edytujesz cenę, stan magazynowy, tytuł i status aktywności produktów w arkuszu, a moduł przenosi te zmiany do…
- Strona:
- Język: pl
- Zaktualizowano: 2026-07-31
- Inne języki: [fr](https://www.datafirefly.com/documentation/synchronisation-google-sheets-prestashop/index.md), [en](https://www.datafirefly.com/en/documentation/synchronisation-google-sheets-prestashop/index.md), [es](https://www.datafirefly.com/es/documentation/synchronisation-google-sheets-prestashop/index.md), [de](https://www.datafirefly.com/de/documentation/synchronisation-google-sheets-prestashop/index.md), [it](https://www.datafirefly.com/it/documentation/synchronisation-google-sheets-prestashop/index.md), [pt](https://www.datafirefly.com/pt/documentation/synchronisation-google-sheets-prestashop/index.md), [nl](https://www.datafirefly.com/nl/documentation/synchronisation-google-sheets-prestashop/index.md)
- Indeks:
Moduł **DataFirefly Sheet Sync** synchronizuje katalog PrestaShop z arkuszem Google w obie strony: edytujesz cenę, stan magazynowy, tytuł i status aktywności produktów w arkuszu, a moduł przenosi te zmiany do PrestaShop. W drugą stronę każda zmiana wykonana w panelu administracyjnym automatycznie trafia do arkusza. Ten przewodnik obejmuje instalację, utworzenie konta usługi Google, udostępnienie arkusza, konfigurację, zasadę działania synchronizacji, cron oraz rozwiązywanie problemów.
## Wymagania
- PrestaShop 8.0 do 9.x.
- PHP 7.4 do 8.3 z włączonymi rozszerzeniami **cURL** i **OpenSSL**.
- Konto Google i dostęp do [konsoli Google Cloud](https://console.cloud.google.com), aby utworzyć konto usługi (bezpłatnie).
- Dostęp do crona (zadanie planowane na serwerze albo zewnętrzna usługa cron) na potrzeby automatycznej synchronizacji.
Żadna biblioteka Composer nie jest wymagana: wywołania API Google Sheets są podpisywane w natywnym PHP (JWT RS256) przy użyciu cURL i OpenSSL, których PrestaShop i tak wymaga.
## Instalacja
1. W panelu administracyjnym otwórz _Moduły > Menedżer modułów_, następnie _Wgraj moduł_ i wskaż plik `dfsheetsync.zip`.
2. Po instalacji otwórz stronę konfiguracji przyciskiem _Konfiguruj_.
Podczas instalacji moduł tworzy własną tabelę stanu synchronizacji, zapisuje wartości domyślne i automatycznie generuje token crona.
## Utworzenie konta usługi Google
Konto usługi to tożsamość Google, której moduł używa do odczytu i zapisu w arkuszu, bez OAuth i bez ekranu zgody.
1. W **konsoli Google Cloud** utwórz projekt albo wybierz istniejący.
2. Włącz dla tego projektu API **Google Sheets** (menu _Interfejsy API i usługi > Biblioteka_, wyszukaj „Google Sheets API”, następnie _Włącz_).
3. Otwórz _Interfejsy API i usługi > Dane logowania_, kliknij _Utwórz dane logowania > Konto usługi_, nadaj nazwę i zatwierdź.
4. Otwórz utworzone konto usługi, zakładka _Klucze_, następnie _Dodaj klucz > Utwórz nowy klucz > JSON_. Pobierany jest plik `.json`: to właśnie ten klucz wkleisz w module.
Ten plik JSON zawiera klucz prywatny. Przechowuj go w bezpiecznym miejscu i nie udostępniaj. Zawsze możesz wygenerować nowy i unieważnić poprzedni w konsoli.
## Udostępnienie arkusza kontu usługi
Plik JSON zawiera pole `client_email` w postaci `nazwa@projekt.iam.gserviceaccount.com`. To adres, któremu trzeba nadać uprawnienia.
1. Otwórz swój arkusz Google albo utwórz nowy.
2. Kliknij _Udostępnij_ i dodaj adres `client_email` konta usługi z rolą **Edytor**.
Bez udostępnienia z rolą Edytor API zwróci błąd braku uprawnień: konto usługi ma dostęp wyłącznie do arkuszy, które zostały mu wyraźnie udostępnione.
## Konfiguracja
Strona konfiguracji zawiera następujące ustawienia:
- **JSON konta usługi**: wklej tutaj całą zawartość pliku `.json`. Pozostaw pole puste, aby zachować już zapisany klucz.
- **Identyfikator lub adres URL arkusza**: wklej identyfikator arkusza albo jego pełny adres URL, identyfikator zostanie wyodrębniony automatycznie.
- **Nazwa karty**: nazwa karty używanej w arkuszu (domyślnie `Products`). Przy pierwszym przebiegu wypełniana jest wierszem nagłówka.
- **Język tytułów**: język, w którym tytuły produktów są odczytywane i zapisywane.
- **Priorytet w razie konfliktu**: określa, która strona wygrywa, gdy produkt został zmieniony w obu miejscach (arkusz Google albo PrestaShop).
- **Eksportuj tylko produkty aktywne**: ogranicza synchronizację do produktów aktywnych.
Zapisz, a następnie sprawdź panel statusu: pokazuje adres e-mail podłączonego konta usługi, adres crona, datę ostatniej synchronizacji i bezpośredni odnośnik do arkusza.
## Struktura arkusza
Arkusz zawiera sześć kolumn, których nagłówek tworzony jest automatycznie przy pierwszym przebiegu:
1. **ID**: identyfikator produktu PrestaShop. Nie modyfikować.
2. **Referencja**: referencja produktu (po stronie synchronizacji tylko do odczytu).
3. **Nazwa**: tytuł produktu w skonfigurowanym języku.
4. **Cena netto**: cena bazowa bez podatku.
5. **Ilość**: łączny stan magazynowy.
6. **Aktywny**: 1 dla aktywnego, 0 dla nieaktywnego.
Kolumna **ID** służy do identyfikacji każdego produktu: nigdy jej nie zmieniaj i nie zmieniaj ręcznie kolejności kolumn. Wiersz, którego ID nie odpowiada żadnemu produktowi, jest po prostu pomijany.
## Jak działa synchronizacja
Moduł zapamiętuje sumę kontrolną ostatniego zsynchronizowanego stanu każdego produktu. Przy każdym przebiegu porównuje z nią bieżący stan sklepu i stan arkusza, aby ustalić, co się zmieniło i po której stronie:
- **Arkusz zmieniony, sklep bez zmian**: wartości z arkusza są zapisywane w produkcie.
- **Sklep zmieniony, arkusz bez zmian**: wartości ze sklepu są zapisywane w arkuszu.
- **Obie strony zmienione**: rozstrzyga skonfigurowana reguła priorytetu (wygrywa arkusz albo sklep), a decyzja trafia do dziennika.
- **Produkt nieobecny w arkuszu**: zostaje dodany automatycznie, a punktem odniesienia jest sklep.
Zapisywane są wyłącznie wiersze rzeczywiście zmienione i tylko we właściwym kierunku. Zapisy do Google są grupowane w paczki, aby mieścić się w limitach API i działać szybko nawet przy dużym katalogu.
## Synchronizacja ręczna i reset
W konfiguracji dostępne są dwa przyciski:
- **Synchronizuj teraz**: natychmiast uruchamia pełną synchronizację i wyświetla raport (wiersze wysłane do arkusza, zaktualizowane produkty, dodane wiersze, rozstrzygnięte konflikty, pominięte wiersze).
- **Zresetuj stan**: czyści tabelę stanu synchronizacji. Przy kolejnym przebiegu sklep jest traktowany jako źródło prawdy dla każdego produktu. Przydatne po ręcznej reorganizacji arkusza.
## Konfiguracja crona
Aby synchronizacja działała automatycznie, zaplanuj adres crona wyświetlany w konfiguracji, co 5 do 15 minut:
```
curl "https://twoj-sklep.pl/module/dfsheetsync/cron?token=TWOJ_TOKEN"
```
Token jest generowany przy instalacji i zabezpiecza punkt końcowy. Wywołanie zwraca raport JSON z przebiegu synchronizacji.
Dobierz częstotliwość do swojego rytmu pracy. Co 5 minut sprawdza się przy zespole edytującym na bieżąco, co 15 do 30 minut wystarczy przy sporadycznych aktualizacjach.
## Walidacja danych
Przed zapisem do sklepu moduł sprawdza każdy wiersz arkusza. Wiersz jest pomijany i zapisywany w dzienniku, bez przerywania reszty synchronizacji, w następujących przypadkach:
- pusta nazwa produktu albo nazwa zawierająca niedozwolone znaki,
- cena ujemna,
- ID nieodpowiadające żadnemu produktowi w sklepie.
Raport synchronizacji podaje liczbę pominiętych wierszy, a szczegóły są dostępne w dziennikach PrestaShop.
## Synchronizowane pola i ograniczenia
Wersja 1.0.0 synchronizuje dla każdego produktu: tytuł (w skonfigurowanym języku), cenę bazową netto, łączny stan magazynowy oraz status aktywny lub nieaktywny.
Wersja 1.0.0 nie obsługuje wariantów (stanu i cen na poziomie kombinacji) ani cen specjalnych. Pozostają one sterowane z poziomu PrestaShop. Synchronizacja działa w kontekście bieżącego sklepu.
## Rozwiązywanie problemów
- **Błąd braku uprawnień**: sprawdź, czy arkusz jest udostępniony z rolą Edytor adresowi `client_email` konta usługi.
- **Błąd „nieprawidłowy JSON”**: wklejona treść musi być kompletnym plikiem klucza, zawierającym co najmniej `client_email` i `private_key`.
- **Brak synchronizacji**: sprawdź, czy identyfikator arkusza jest uzupełniony i czy cron faktycznie się wykonuje, albo uruchom synchronizację ręcznie.
- **Błąd uwierzytelniania Google**: upewnij się, że API Google Sheets jest włączone dla projektu i że zegar serwera jest ustawiony poprawnie (JWT zawiera znacznik czasu).
- **Wiersz nie zostaje zastosowany**: pusta lub nieprawidłowa nazwa albo cena ujemna. Popraw wiersz w arkuszu.
- **Produkt wraca do poprzedniej wartości**: sprawdź regułę priorytetu w razie konfliktu. Strona priorytetowa nadpisuje drugą, gdy obie się zmieniły.
## Deinstalacja
Deinstalacja usuwa tabelę stanu synchronizacji i konfigurację modułu, w tym klucz konta usługi i token crona. Twoje produkty i arkusz Google pozostają nienaruszone. Przy zwykłej aktualizacji wystarczy podmienić pliki modułu: stan synchronizacji zostaje zachowany.