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 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, 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.

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.

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.

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.

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.

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.

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.