Google Sheets-synchronisatie in beide richtingen: volledige gids

De module DataFirefly Sheet Sync houdt uw PrestaShop-catalogus en een Google Sheet in beide richtingen gelijk: u bewerkt de prijs, de voorraad, de titel en de actieve status van uw producten in de spreadsheet, en de module past die in PrestaShop toe; omgekeerd komt elke wijziging uit de backoffice automatisch in de Sheet terecht. Deze gids behandelt de installatie, het aanmaken van het Google-serviceaccount, het delen van de spreadsheet, de configuratie, de werking van de synchronisatie, de cron en de probleemoplossing.

Vereisten

• PrestaShop 8.0 tot 9.x.
• PHP 7.4 tot 8.3 met de uitbreidingen cURL en OpenSSL actief.
• Een Google-account en toegang tot de Google Cloud-console om een serviceaccount aan te maken (gratis).
• Toegang tot een cron (een geplande taak op de server of een externe cron-dienst) voor de automatische synchronisatie.

Installatie

1. Open in de backoffice Modules > Modulebeheer, klik op Een module uploaden en plaats het bestand dfsheetsync.zip.
2. Open na de installatie de configuratiepagina met de knop Configureren.

Bij de installatie maakt de module zijn tabel met de synchronisatiestatus aan, legt hij zijn standaardwaarden vast en maakt hij automatisch een crontoken aan.

Het Google-serviceaccount aanmaken

Een serviceaccount is een Google-identiteit waarmee de module in uw spreadsheet leest en schrijft, zonder OAuth en zonder toestemmingsscherm.

1. Maak in de Google Cloud-console een project aan (of kies er een).
2. Schakel de Google Sheets-API voor dat project in (menu API’s en services > Bibliotheek, zoek naar « Google Sheets API » en klik op Inschakelen).
3. Open API’s en services > Inloggegevens, klik op Inloggegevens maken > Serviceaccount, geef het een naam en bevestig.
4. Open het aangemaakte serviceaccount, ga naar het tabblad Sleutels en klik op Sleutel toevoegen > Nieuwe sleutel maken > JSON. Er wordt een .json-bestand gedownload: dat is de sleutel die u in de module plakt.

De spreadsheet met het serviceaccount delen

Het JSON-bestand bevat een veld client_email in de vorm naam@project.iam.gserviceaccount.com. Dat is het adres dat u moet toelaten.

1. Open (of maak) uw Google Sheet.
2. Klik op Delen en voeg het adres client_email van het serviceaccount toe met de rol Bewerker.

Configuratie

De configuratiepagina bundelt de volgende instellingen:

• JSON van het serviceaccount: plak hier de volledige inhoud van het .json-bestand. Laat het veld leeg om de al bewaarde sleutel te behouden.
• ID of URL van de spreadsheet: plak de identificatie van de Sheet of haar volledige URL, want de ID wordt er automatisch uit gehaald.
• Naam van het tabblad: het tabblad dat in de spreadsheet wordt gebruikt (standaard Products). Bij de eerste doorloop komt er een kopregel in.
• Taal van de titels: de taal waarin de producttitels worden gelezen en geschreven.
• Voorrang bij een conflict: bepaalt wie het haalt wanneer een product aan beide kanten is gewijzigd (de Google Sheet of PrestaShop).
• Alleen actieve producten exporteren: beperkt de synchronisatie tot de actieve producten.

Sla op en bekijk daarna het statuspaneel: het toont het e-mailadres van het verbonden serviceaccount, de cron-URL, de datum van de laatste synchronisatie en een rechtstreekse link naar de Sheet.

Structuur van de spreadsheet

De spreadsheet telt zes kolommen, waarvan de kop bij de eerste doorloop automatisch wordt aangemaakt:

1. ID: de identificatie van het PrestaShop-product. Niet wijzigen.
2. Referentie: de productreferentie (aan synchronisatiezijde alleen-lezen).
3. Naam: de titel van het product in de ingestelde taal.
4. Prijs excl. btw: de basisprijs exclusief belasting.
5. Hoeveelheid: de totale voorraad.
6. Actief: 1 voor actief, 0 voor inactief.

Hoe de synchronisatie werkt

De module onthoudt de vingerafdruk (checksum) van de laatst gesynchroniseerde toestand van elk product. Bij elke doorloop vergelijkt hij de huidige toestand van de winkel en die van de spreadsheet met die vingerafdruk, om te bepalen wat er is veranderd en aan welke kant:

• Spreadsheet gewijzigd, winkel ongewijzigd: de waarden uit de spreadsheet komen op het product te staan.
• Winkel gewijzigd, spreadsheet ongewijzigd: de waarden uit de winkel worden in de spreadsheet geschreven.
• Allebei gewijzigd: de ingestelde voorrangsregel beslist (de Sheet wint, of de winkel wint), en de beslissing komt in het logboek.
• Product ontbreekt in de spreadsheet: het wordt automatisch toegevoegd, met de winkel als referentie.

Alleen de regels die werkelijk zijn gewijzigd, worden geschreven, in de juiste richting; de schrijfacties naar Google gaan in batches, om de quota van de API te respecteren en ook bij een grote catalogus snel te blijven.

Handmatig synchroniseren en opnieuw instellen

Er staan twee knoppen in de configuratie:

• Nu synchroniseren: start meteen een volledige synchronisatie en toont een verslag (regels die naar de Sheet zijn gestuurd, bijgewerkte producten, toegevoegde regels, opgeloste conflicten en overgeslagen regels).
• De status opnieuw instellen: leegt de tabel met de synchronisatiestatus. Bij de volgende doorloop geldt de winkel voor elk product als de bron van waarheid. Handig na een handmatige herschikking van de spreadsheet.

De cron instellen

Plan voor een automatische synchronisatie de cron-URL uit de configuratie in, om de 5 tot 15 minuten:

curl "https://uw-winkel.nl/module/dfsheetsync/cron?token=UW_TOKEN"

Het token wordt bij de installatie aangemaakt en beveiligt het endpoint. De aanroep geeft een JSON-verslag van de synchronisatie terug.

Gegevenscontrole

Vóór hij in de winkel schrijft, controleert de module elke regel van de spreadsheet. Een regel wordt overgeslagen en in het logboek gezet (zonder de rest van de synchronisatie te onderbreken) in de volgende gevallen:

• een lege productnaam of een naam met niet-toegelaten tekens;
• een negatieve prijs;
• een ID die bij geen enkel product van de winkel hoort.

Het synchronisatieverslag vermeldt hoeveel regels er zijn overgeslagen, en het detail vindt u terug in de PrestaShop-logboeken.

Gesynchroniseerde velden en grenzen

Versie 1.0.0 synchroniseert per product: de titel (in de ingestelde taal), de basisprijs exclusief btw, de totale voorraad en de actieve of inactieve status.

Problemen oplossen

• Fout « toestemming geweigerd »: ga na of de spreadsheet wel als Bewerker is gedeeld met het adres client_email van het serviceaccount.
• Fout « ongeldige JSON »: de geplakte inhoud moet het volledige sleutelbestand zijn, met minstens client_email en private_key.
• Geen enkele synchronisatie: controleer of de ID van de spreadsheet is ingevuld en of de cron wel loopt, of start een handmatige synchronisatie.
• Fout bij het aanmelden bij Google: zorg dat de Google Sheets-API voor het project is ingeschakeld en dat de klok van de server juist staat (de JWT draagt een tijdstempel).
• Een regel wordt niet toegepast: een lege of ongeldige naam, of een negatieve prijs; verbeter de regel in de spreadsheet.
• Een product keert naar de oude waarde terug: bekijk de voorrangsregel bij een conflict; de voorrangskant overschrijft de andere wanneer allebei zijn gewijzigd.

Verwijderen

Het verwijderen wist de tabel met de synchronisatiestatus en de configuratie van de module (ook de sleutel van het serviceaccount en het crontoken). Uw producten en uw Google Sheet blijven ongewijzigd. Voor een gewone update volstaat het de bestanden van de module te vervangen: de synchronisatiestatus blijft behouden.