PS PrestaShop PrestaShop Mittel

Bidirektionale Google-Sheets-Synchronisation — Vollständige Anleitung

Bidirektionale Synchronisation Google Sheets ⇄ PrestaShop installieren, konfigurieren und betreiben: Google-Dienstkonto, Freigabe des Sheets, Spalten, Konflikte, Cron und Fehlerbehebung.

Aktualisiert Modulversion 1.0.0

Das Modul DataFirefly Sheet Sync hält Ihren PrestaShop-Katalog in beide Richtungen mit einem Google Sheet synchron: Sie bearbeiten Preis, Lagermenge, Titel und Aktivstatus Ihrer Produkte im Sheet, und das Modul überträgt sie nach PrestaShop; umgekehrt fließt jede im Backoffice vorgenommene Änderung automatisch ins Sheet zurück. Dieses Handbuch behandelt Installation, Erstellung des Google-Dienstkontos, Freigabe des Sheets, Konfiguration, Funktionsweise der Synchronisation, den Cron und die Fehlerbehebung.

Voraussetzungen

  • PrestaShop 8.0 bis 9.x.
  • PHP 7.4 bis 8.3 mit aktivierten Erweiterungen cURL und OpenSSL.
  • Ein Google-Konto mit Zugang zur Google-Cloud-Konsole, um ein Dienstkonto zu erstellen (kostenlos).
  • Cron-Zugang (geplante Serveraufgabe oder externer Cron-Dienst) für die automatische Synchronisation.

Es ist keine Composer-Bibliothek erforderlich: Die Aufrufe der Google Sheets API werden in nativem PHP (JWT RS256) mit cURL und OpenSSL signiert – beide sind von PrestaShop ohnehin vorausgesetzt.

Installation

  1. Öffnen Sie im Backoffice Module > Modulmanager, dann Ein Modul hochladen und legen Sie die Datei dfsheetsync.zip ab.
  2. Öffnen Sie nach der Installation die Konfigurationsseite über die Schaltfläche Konfigurieren.

Bei der Installation erstellt das Modul seine Synchronisationsstatus-Tabelle, registriert seine Standardwerte und generiert automatisch einen Cron-Token.

Das Google-Dienstkonto erstellen

Ein Dienstkonto ist eine Google-Identität, die das Modul zum Lesen und Schreiben in Ihrem Sheet nutzt – ohne OAuth-Ablauf und ohne Zustimmungsbildschirm.

  1. Erstellen (oder wählen) Sie in der Google-Cloud-Konsole ein Projekt.
  2. Aktivieren Sie die Google Sheets API für dieses Projekt (Menü APIs und Dienste > Bibliothek, nach „Google Sheets API“ suchen, dann Aktivieren).
  3. Öffnen Sie APIs und Dienste > Anmeldedaten, klicken Sie auf Anmeldedaten erstellen > Dienstkonto, geben Sie ihm einen Namen und bestätigen Sie.
  4. Öffnen Sie das erstellte Dienstkonto, Tab Schlüssel, dann Schlüssel hinzufügen > Neuen Schlüssel erstellen > JSON. Eine .json-Datei wird heruntergeladen: Das ist der Schlüssel, den Sie ins Modul einfügen.

Diese JSON-Datei enthält einen privaten Schlüssel. Bewahren Sie sie sicher auf und geben Sie sie nicht weiter. Sie können jederzeit einen neuen erzeugen und den alten in der Konsole widerrufen.

Das Sheet mit dem Dienstkonto teilen

Die JSON-Datei enthält ein Feld client_email in der Form name@projekt.iam.gserviceaccount.com. Das ist die zu berechtigende Adresse.

  1. Öffnen (oder erstellen) Sie Ihr Google Sheet.
  2. Klicken Sie auf Freigeben und fügen Sie die client_email-Adresse des Dienstkontos mit der Rolle Bearbeiter hinzu.

Ohne diese Bearbeiter-Freigabe gibt die API einen Fehler „Berechtigung verweigert“ zurück: Ein Dienstkonto hat nur auf die ihm ausdrücklich freigegebenen Sheets Zugriff.

Konfiguration

Die Konfigurationsseite fasst folgende Einstellungen zusammen:

  • Dienstkonto-JSON: Fügen Sie hier den vollständigen Inhalt der .json-Datei ein. Lassen Sie das Feld leer, um den bereits gespeicherten Schlüssel zu behalten.
  • Tabellen-ID oder URL: Fügen Sie die ID des Sheets oder seine vollständige URL ein – die ID wird automatisch extrahiert.
  • Name des Tabellenblatts: das im Tabellendokument zu verwendende Blatt (Standard Products). Es wird beim ersten Lauf mit einer Kopfzeile gefüllt.
  • Sprache der Titel: die Sprache, in der die Produkttitel gelesen und geschrieben werden.
  • Priorität bei Konflikt: legt fest, welche Seite gewinnt, wenn ein Produkt auf beiden Seiten bearbeitet wurde (das Google Sheet oder PrestaShop).
  • Nur aktive Produkte exportieren: beschränkt die Synchronisation auf aktive Produkte.

Speichern Sie und prüfen Sie die Statusanzeige: Sie zeigt die E-Mail des verbundenen Dienstkontos, die Cron-URL, das Datum der letzten Synchronisation und einen direkten Link zum Sheet.

Aufbau des Tabellenblatts

Das Blatt hat sechs Spalten, deren Kopfzeile beim ersten Lauf automatisch erstellt wird:

  1. ID — die PrestaShop-Produkt-ID. Nicht bearbeiten.
  2. Referenz — Produktreferenz (für die Synchronisation schreibgeschützt).
  3. Name — der Produkttitel in der konfigurierten Sprache.
  4. Nettopreis — der Grundpreis ohne Steuern.
  5. Menge — die globale Lagermenge.
  6. Aktiv — 1 für aktiv, 0 für inaktiv.

Die Spalte ID identifiziert jedes Produkt: Bearbeiten Sie sie niemals und ordnen Sie die Spalten nicht manuell um. Eine Zeile, deren ID zu keinem Produkt passt, wird einfach übersprungen.

So funktioniert die Synchronisation

Das Modul speichert den Fingerabdruck (Prüfsumme) des letzten synchronisierten Zustands jedes Produkts. Bei jedem Lauf vergleicht es den aktuellen Zustand des Shops und den des Sheets mit diesem Fingerabdruck, um zu bestimmen, was sich geändert hat und auf welcher Seite:

  • Sheet geändert, Shop unverändert → die Werte des Sheets werden auf das Produkt angewendet.
  • Shop geändert, Sheet unverändert → die Werte des Shops werden ins Sheet geschrieben.
  • Beide geändert → die konfigurierte Prioritätsregel entscheidet (das Sheet gewinnt, oder der Shop gewinnt), und die Entscheidung wird protokolliert.
  • Produkt fehlt im Sheet → es wird automatisch ergänzt, wobei der Shop die Referenz ist.

Nur die tatsächlich geänderten Zeilen werden geschrieben, in die richtige Richtung; die Schreibvorgänge an Google werden gebündelt, um die API-Kontingente einzuhalten und auch bei einem großen Katalog schnell zu bleiben.

Manuelle Synchronisation und Zurücksetzen

In der Konfiguration stehen zwei Schaltflächen zur Verfügung:

  • Jetzt synchronisieren: führt sofort eine vollständige Synchronisation aus und zeigt einen Bericht an (ins Sheet übertragene Zeilen, aktualisierte Produkte, ergänzte Zeilen, gelöste Konflikte, übersprungene Zeilen).
  • Status zurücksetzen: leert die Synchronisationsstatus-Tabelle. Beim nächsten Lauf gilt der Shop als Quelle der Wahrheit für jedes Produkt. Nützlich nach einer manuellen Neuordnung des Sheets.

Cron-Einrichtung

Planen Sie für die automatische Synchronisation die in der Konfiguration angezeigte Cron-URL alle 5 bis 15 Minuten ein:

curl "https://ihr-shop.de/module/dfsheetsync/cron?token=IHR_TOKEN"

Der Token wird bei der Installation generiert und sichert den Endpunkt. Der Aufruf gibt einen JSON-Bericht der Synchronisation zurück.

Wählen Sie eine Frequenz, die zu Ihrem Bearbeitungsrhythmus passt. Alle 5 Minuten eignet sich für ein durchgehend bearbeitendes Team; alle 15 bis 30 Minuten reicht für gelegentliche Aktualisierungen.

Datenvalidierung

Vor dem Schreiben in den Shop validiert das Modul jede Zeile des Sheets. Eine Zeile wird übersprungen und protokolliert (ohne den Rest der Synchronisation zu unterbrechen) in folgenden Fällen:

  • leerer Produktname oder ein Name mit unzulässigen Zeichen;
  • negativer Preis;
  • ID, die zu keinem Produkt im Shop passt.

Der Synchronisationsbericht zeigt die Anzahl der übersprungenen Zeilen; die Details sind in den PrestaShop-Protokollen einsehbar.

Synchronisierte Felder und Einschränkungen

Version 1.0.0 synchronisiert für jedes Produkt: den Titel (in der konfigurierten Sprache), den Netto-Grundpreis, die globale Lagermenge und den Status aktiv/inaktiv.

In Version 1.0.0 nicht unterstützt: Kombinationen (Bestand und Preis je Variante) sowie spezifische Preise. Sie werden weiterhin über PrestaShop verwaltet. Die Synchronisation läuft im Kontext des aktuellen Shops.

Fehlerbehebung

  • Fehler „Berechtigung verweigert“: Prüfen Sie, ob das Sheet als Bearbeiter mit der client_email-Adresse des Dienstkontos geteilt ist.
  • Fehler „Ungültiges JSON“: Der eingefügte Inhalt muss die vollständige Schlüsseldatei sein, die mindestens client_email und private_key enthält.
  • Keine Synchronisation: Prüfen Sie, ob die Tabellen-ID gesetzt ist und der Cron tatsächlich läuft, oder lösen Sie eine manuelle Synchronisation aus.
  • Google-Authentifizierungsfehler: Stellen Sie sicher, dass die Google Sheets API für das Projekt aktiviert ist und die Serveruhr korrekt geht (der JWT ist mit einem Zeitstempel versehen).
  • Eine Zeile wird nicht angewendet: leerer/ungültiger Name oder negativer Preis; korrigieren Sie die Zeile im Sheet.
  • Ein Produkt kehrt zum alten Wert zurück: Prüfen Sie die Konfliktprioritätsregel; die prioritäre Seite überschreibt die andere, wenn beide geändert wurden.

Deinstallation

Die Deinstallation entfernt die Synchronisationsstatus-Tabelle und die Konfiguration des Moduls (einschließlich des Dienstkonto-Schlüssels und des Cron-Tokens). Ihre Produkte und Ihr Google Sheet werden nicht verändert. Für ein einfaches Update genügt das Ersetzen der Moduldateien: Der Synchronisationsstatus bleibt erhalten.

War diese Seite hilfreich?

Immer noch nicht weiter? Support kontaktieren