Kassensystem mit PrestaShop verbinden (Square, Zettle, SumUp): Dokumentation
Modul installieren, Square, Zettle oder SumUp verbinden, Produkte zuordnen und Bestand und Verkäufe zwischen Kasse und PrestaShop synchronisieren.
Funktionsweise
Das Modul verbindet PrestaShop mit Ihrer Kasse Square, Zettle by PayPal oder SumUp. Es importiert jeden Verkauf, jede Rückgabe und jede Erstattung der Kasse in ein Journal, aktualisiert den Bestand in der Richtung Ihrer Wahl und kann jeden Verkauf in eine PrestaShop-Bestellung umwandeln. Es kann außerdem Ihren PrestaShop-Katalog an die Kasse senden.
Der Bestand wird in einer der folgenden drei Richtungen synchronisiert, einstellbar pro Kasse:
- Vom Shop zur Kasse: PrestaShop ist führend. Die Kassenverkäufe werden in PrestaShop abgezogen, danach geht der neue Bestand zurück an die Kasse.
- Von der Kasse zum Shop: Die Kasse ist führend. PrestaShop übernimmt die Mengen der Kasse bei jedem Cron-Lauf und bei jedem Bestands-Webhook.
- In beide Richtungen: Die Änderungen auf beiden Seiten seit der letzten Synchronisation werden addiert. Ein Onlineverkauf und ein Ladenverkauf zählen jeweils einmal.

Was jede Kasse unterstützt
- Square: Verkäufe, Rückgaben und Erstattungen, Bestand in allen drei Richtungen, mehrere Standorte, Katalogversand mit dem Hauptbild, signierte Webhooks.
- Zettle by PayPal: Verkäufe und Erstattungen, Bestand in allen drei Richtungen, Katalogversand, signierter Webhook, den das Modul selbst anlegt.
- SumUp: Verkäufe und Erstattungen, die vom PrestaShop-Bestand abgezogen werden. Die öffentliche SumUp-API stellt weder Bestand noch Katalog noch einen Webhook für Kassenverkäufe bereit. Der Import läuft deshalb über den Cron, und der in SumUp angezeigte Bestand wird nicht aktualisiert.
Das Modul ersetzt Ihre Kasse nicht und macht sie nicht zu einer zertifizierten Kasse. Belege, Tagesabschluss und steuerliche Pflichten bleiben bei Square, Zettle oder SumUp.
Voraussetzungen
- PrestaShop 1.7.8 bis 9.x. Das Modul wurde getestet mit PrestaShop 1.7.8.11 (PHP 7.4), 8.2.1 (PHP 8.1) und 9.1.5 (PHP 8.5).
- Ein Cronjob bei Ihrem Hoster.
- Ein Shop mit HTTPS für die Webhooks und für die OAuth-Verbindung.
- Ein Square-, Zettle- oder SumUp-Konto und Zugang zu dessen Entwicklerbereich, wenn Sie sich per Token oder API-Schlüssel verbinden.
Installation und Update
- Klicken Sie unter Module > Modulmanager auf Modul hochladen und senden Sie das ZIP.
- Das Modul fügt das Menü Katalog > Kassen-Connector hinzu. Die Übersicht zeigt eine Liste Erste Schritte, die sich während der Einrichtung nach und nach abhakt.
Für den Wechsel von einer Version 1.x auf 2.0.0 senden Sie das neue ZIP auf dieselbe Weise. Das Update behält die Zuordnungen, das Verkaufsjournal, die Verbindungen, die Importpositionen (kein Verkauf wird erneut importiert) und die Einstellungen. Bestehende Webhook-URLs bleiben gültig. Das Update legt die neuen Tabellen an, verschlüsselt die alten Zugangsdaten neu und entfernt beim Status „Kassenverkauf“ die Versand-Markierung, die eine zweite Zahlung auslöste. Bereits erstellte Bestellungen werden nicht geändert.
Kassen verbinden
Der Tab Verbindungen zeigt den Zustand jeder Kasse und die verfügbaren Funktionen. Jede Kasse hat einen eigenen Assistenten. Die Zugangsdaten werden verschlüsselt gespeichert und nie wieder angezeigt oder ins Protokoll geschrieben. Ein leer gelassenes Feld behält den gespeicherten Wert.

Square
- Wählen Sie die Verbindungsart. OAuth wird empfohlen: Sie autorisieren das Modul in Ihrem Square-Konto, und das Token wird automatisch erneuert. Für einen einzelnen Shop können Sie auch ein persönliches Zugriffstoken einfügen.
- Bei OAuth geben Sie die ID und das Secret Ihrer Square-Anwendung ein und hinterlegen in dieser Anwendung die angezeigte Weiterleitungs-URL. Das Modul fragt nur die nötigen Berechtigungen an: Standorte, Bestellungen, Zahlungen, Katalog, Bestand und Kunden lesen, Katalog und Bestand schreiben.
- Klicken Sie auf Mit Square verbinden, bestätigen Sie die Berechtigungen und klicken Sie dann auf Verbindung testen.
- Wählen Sie den Standort, der den Bestand führt, und markieren Sie die Standorte, deren Verkäufe importiert werden (höchstens 10).
- Für den Sofortimport fügen Sie unter Webhooks > Subscriptions die angezeigte Benachrichtigungs-URL mit den Ereignissen
order.updated,refund.created,inventory.count.updatedundoauth.authorization.revokedhinzu. Fügen Sie danach den Signaturschlüssel im Modul ein. Die URL muss auf beiden Seiten Zeichen für Zeichen gleich sein.

Die OAuth-Schaltfläche führt Sie zur Autorisierungsseite der Kasse auf deren eigener Website und danach zurück ins Modul. Der folgende Screenshot wurde im Demomodus mit einem simulierten Autorisierungsbildschirm aufgenommen.


Zettle by PayPal
- Für einen einzelnen Shop wird der Self-hosted-API-Schlüssel empfohlen: Erstellen Sie ihn im Zettle Developer Portal und fügen Sie ihn mit seiner Client-ID ein. Für eine Partneranwendung steht auch eine OAuth-Verbindung mit automatischer Erneuerung der Tokens zur Verfügung.
- Speichern Sie und testen Sie die Verbindung.
- Klicken Sie auf Webhook aktivieren: Das Modul legt das Abonnement selbst an (
PurchaseCreated,InventoryBalanceChanged) und speichert dessen Signaturschlüssel verschlüsselt. Zettle verlangt einen Shop mit HTTPS. - Die Bestandsverfolgung muss für die Produkte in Zettle aktiv sein. Vom Modul gesendete Produkte haben sie automatisch.

SumUp
- Fügen Sie Ihren geheimen API-Schlüssel (SumUp-Dashboard, Developers > API keys) mit Ihrem Händlercode ein, oder verbinden Sie sich per OAuth.
- Testen Sie die Verbindung. Fehlt der Händlercode, wird er automatisch ausgelesen.
- SumUp sendet keinen Webhook für Kassenverkäufe. Sie werden daher alle 5 Minuten über den Cron importiert. Die Zuordnung erfolgt über die Artikelnummer oder den Artikelnamen.

Eine Kasse trennen
Die Schaltfläche Trennen widerruft die Tokens, wenn die Kasse das erlaubt (Square, Zettle), und löscht sie aus PrestaShop. Die Zuordnungen und das Verkaufsjournal bleiben erhalten.
Bestandsrichtung
Wählen Sie unter Einstellungen > Bestand die Bestandsrichtung für Square und für Zettle: vom Shop zur Kasse, von der Kasse zum Shop, in beide Richtungen oder keine Bestandssynchronisierung. Bei SumUp werden die Verkäufe vom PrestaShop-Bestand abgezogen, die Kasse selbst erhält aber keinen Bestand.
- Nur eine Kasse kann den Bestand führen. Wählen Sie eine zweite, setzt das Modul sie auf In beide Richtungen.
- Bei der Richtung „in beide Richtungen“ entscheidet die maßgebliche Quelle über die erste Angleichung und über Konflikte.
- Ein vom Modul geschriebener Bestand wird nie zurückgesendet, damit kein Echo entsteht. Zählt die Kasse ihre eigenen Verkäufe bereits selbst, zieht der Import sie nicht ein zweites Mal ab.
- Die Option Direkt nach jeder Bestandsänderung in PrestaShop senden sendet den Bestand sofort. Andernfalls geht er beim nächsten Cron-Lauf hinaus.

Produkte zuordnen
Der Tab Zuordnungen verknüpft jeden Kassenartikel mit einem PrestaShop-Produkt oder einer Kombination.
- Katalog lesen von Square oder Zettle: Die Artikel werden automatisch per SKU (Artikelnummer des Produkts oder der Kombination) und per Barcode EAN-13 / UPC zugeordnet.
- Vorschläge nach Namen: Für jeden verbleibenden Artikel schlägt das Modul das ähnlichste Produkt mit einer Punktzahl vor. Vorschläge ab 90 % lassen sich gesammelt übernehmen, die übrigen einzeln. Kein Vorschlag wird ohne Ihre Bestätigung gespeichert.
- Manuelle Zuordnung: Suchen Sie ein Produkt nach Name, Artikelnummer oder EAN.
- Ein Artikel, der an der Kasse verkauft wurde, aber im gelesenen Katalog fehlt, erscheint ebenfalls in der Liste. Sie können ihn ausblenden, wenn er nicht online verkauft wird.

Wenn Sie einen Artikel zuordnen, wird der Bestand der bereits importierten Verkäufe einmalig nachgezogen. Die früheren Verkaufszeilen werden mit der neuen Regel verknüpft.
Katalog an die Kasse senden
Der Tab Katalog legt Ihre PrestaShop-Produkte in Square oder Zettle an: Kombinationen als Varianten, Preise, SKU, Barcode, optional das Hauptbild und danach den Bestand. Wählen Sie die Kasse, eine Kategorie (inklusive Unterkategorien), den gesendeten Preis (brutto oder netto, ohne Rabatte) und ob nur aktive Produkte betroffen sind.
- Prüfen, was gesendet wird liest zuerst den Kassenkatalog, ordnet bereits Vorhandenes per SKU oder Barcode zu und zeigt dann die Zahl der anzulegenden Produkte und Varianten.
- Setzen Sie das Bestätigungshäkchen und klicken Sie auf In der Kasse anlegen: Die Produkte werden in Paketen mit Fortschrittsbalken gesendet, und jeder angelegte Artikel wird sofort zugeordnet.

Bestehende Artikel der Kasse werden nie geändert. Bei Square wird jeder Artikel einer bestehenden Square-Steuer mit demselben Satz zugewiesen. Es wird keine Steuer angelegt. Virtuelle Produkte und Pakete sind ausgeschlossen, und Kategorien werden nicht übertragen. Zettle akzeptiert höchstens 99 Varianten pro Produkt. SumUp kann über seine API keine Produkte empfangen.
Bestandsprüfung und Abgleich
Der Tab Bestand vergleicht für jeden zugeordneten Artikel den PrestaShop-Bestand mit dem Kassenbestand und listet die Abweichungen auf. Für jede Abweichung oder für eine Auswahl gilt:
- PrestaShop beibehalten: Die Kasse erhält die PrestaShop-Menge.
- Kasse beibehalten: PrestaShop erhält die Menge der Kasse, mit einer Lagerbewegung.
Die nächtliche Vollsynchronisation startet einen Abgleich und speichert dessen Bericht. Frühere Berichte bleiben einsehbar. Alle Kassenbestände importieren überschreibt den PrestaShop-Bestand jedes zugeordneten Produkts. Verwenden Sie dies nur einmal bei der Einrichtung, wenn der Kassenbestand der verlässlichere ist.

Kassenverkäufe
Der Tab Kassenverkäufe listet jeden Beleg mit seinen Zeilen, seiner Kasse, seinem Standort, seiner Zahlung, seiner MwSt. pro Zeile, seinem Trinkgeld und gegebenenfalls der PrestaShop-Bestellung. Filter: Kasse, Typ (Verkäufe, Rückgaben und Erstattungen, PrestaShop-Bestellungen), Betragsabweichungen, Suche nach Beleg, Artikel, Standort oder Bestellnummer sowie Datumsbereich. CSV exportieren exportiert die Auswahl.

Der Import ist idempotent: Ein bereits importierter Verkauf wird nie doppelt erfasst, auch wenn er gleichzeitig über mehrere Webhooks und den Cron eintrifft. Belege, die an der Kasse offline erfasst und später übertragen werden, werden ebenfalls importiert. Verkäufe vor dem Datum unter Kassenverkäufe importieren ab werden ignoriert.
PrestaShop-Bestellungen für Ladenverkäufe
Unter Einstellungen > Bestellungen und Erstattungen ist die Option Für jeden Kassenverkauf, dessen Artikel alle zugeordnet sind, eine PrestaShop-Bestellung anlegen standardmäßig deaktiviert. Nach der Aktivierung gilt:
- ein Laufkunde pro Shop, mit der Shopadresse;
- ein kostenloser Versanddienst „Kassenverkauf“, der im Checkout nie angeboten wird;
- die Zahlungsart „Kasse – Square / Zettle / SumUp“, eine einzige Zahlung und eine Bestellung, die auf den Verkaufszeitpunkt datiert ist;
- die Preise und Rabatte des Belegs, auf die Zeilen verteilt;
- das Trinkgeld außerhalb der Bestellsumme, in der Notiz der Bestellung vermerkt;
- keine E-Mail, weder an den Kunden noch an Sie.
Der Standardstatus ist „Kassenverkauf“ (bezahlt, zugestellt, ohne E-Mail und ohne Rechnung). Berechnet PrestaShop eine andere Summe als der Beleg (Steuerregeln, Rundungen), wird die Abweichung beim Verkauf angezeigt und im Protokoll vermerkt.

- Rechnungen für Kassenbestellungen erlauben: standardmäßig deaktiviert, weil die Kasse den Beleg bereits liefert. Ohne diese Option wird ein Status, der eine Rechnung erzeugt, abgelehnt. Mit ihr wird die Rechnung auf Basis der bestehenden Zahlung erstellt und im Protokoll gemeldet.
- Identifizierte Kunden (Square): Die Bestellung kann dem bestehenden PrestaShop-Kunden zugeordnet werden, der dieselbe E-Mail-Adresse wie der Square-Kunde hat. Es wird nur ein bestehender Kunde mit Adresse verwendet. Es werden weder Kunden noch Adressen angelegt.

Ein Verkauf mit nicht zugeordneten Artikeln erhält keine Bestellung. Seine zugeordneten Artikel werden direkt vom Bestand abgezogen.
Rückgaben und Erstattungen
Rückgaben aus Square sowie Erstattungen aus Zettle und SumUp werden importiert, auch Teilerstattungen. Zurückgegebene Artikel gehen einmal über die Rückgabezeile zurück in den Bestand. Eine Erstattung ohne zurückgegebenen Artikel ändert den Bestand nicht. Wählen Sie für die ursprüngliche Bestellung:
- Nur Notiz in der Bestellung (Standard);
- Gutschrift für die zurückgegebenen Artikel oder den erstatteten Betrag;
- Gutschrift und Status „Erstattet“, sobald die Bestellung vollständig erstattet ist.

Geplante Aufgaben und Webhooks
Einstellungen > Geplante Aufgaben zeigt die Cron-URL. Rufen Sie sie alle 5 Minuten auf, und dieselbe URL mit full=1 einmal pro Nacht:
*/5 * * * * curl -s "https://ihr-shop.de/module/dfposconnector/cron?token=IHR_TOKEN" >/dev/null 0 3 * * * curl -s "https://ihr-shop.de/module/dfposconnector/cron?token=IHR_TOKEN&full=1" >/dev/null
Der Cron arbeitet die Webhook-Warteschlange ab, importiert neue Verkäufe, erneuert die Tokens und sendet ausstehende Bestände. Zwei Läufe überschneiden sich nie. Der nächtliche Lauf sendet alle zugeordneten Bestände erneut und erstellt den Abgleichsbericht.
Jeder Webhook wird geprüft, bevor er angenommen wird:
- der eigene URL-Schlüssel der Webhooks, getrennt vom Cron-Token;
- die Signatur der Kasse;
- eine maximale Größe von 256 KB;
- ein maximales Alter von 96 Stunden;
- eine noch nie gesehene Ereignis-ID.
Das Modul antwortet sofort und verarbeitet das Ereignis danach. Eine unsignierte, falsch signierte oder wiederholt gesendete Benachrichtigung wird abgelehnt und im Protokoll vermerkt.
Technisches Protokoll
Der Tab Protokoll listet Fehler, Warnungen und Informationen, filterbar nach Kasse, Stufe, Problem, Text und Datum. Jeder bekannte Fehler nennt seine Ursache und seine Lösung, mit einem Link zum betroffenen Bildschirm. Tokens, Schlüssel und Signaturen werden vor dem Schreiben maskiert. Die Einträge werden standardmäßig 30 Tage aufbewahrt (einstellbar), und die zuletzt empfangenen Webhook-Ereignisse werden aufgelistet.

Warnungen
Der Tab Warnungen sammelt die aktuellen Probleme mit ihrer Ursache, ihrer Lösung und einer Schaltfläche Jetzt beheben. Eine Warnung schließt sich von selbst, sobald das Problem verschwindet.
- Synchronisation bei 3 Läufen in Folge fehlgeschlagen, danach eine Nachricht, sobald sie wieder funktioniert;
- Token abgelehnt oder nicht erneuerbar, fehlende Berechtigung, abgelehnte Webhook-Signaturen;
- abgebrochene Bestandsaktualisierungen, Cron, der nicht mehr läuft;
- an der Kasse verkaufte Artikel ohne PrestaShop-Produkt;
- beim nächtlichen Abgleich gefundene Abweichungen.

Die Warnungen können auch per E-Mail gesendet werden, höchstens eine alle 6 Stunden pro Warnung. Lassen Sie die Adresse leer, um die Shop-Adresse zu verwenden. Testwarnung senden prüft den Versand.

Fehlerbehebung
„Inventar nicht initialisiert“ bei Zettle
Aktivieren Sie die Bestandsverfolgung für mindestens ein Produkt in Zettle, oder senden Sie ein Produkt aus dem Tab Katalog.
Square-Webhook abgelehnt (ungültige Signatur)
Die in Square hinterlegte Benachrichtigungs-URL muss Zeichen für Zeichen mit der URL des Moduls übereinstimmen, und der Signaturschlüssel muss zu diesem Abonnement gehören.
Token abgelehnt oder fehlende Berechtigung
Öffnen Sie Verbindungen, verbinden Sie die Kasse mit ihrem Assistenten neu und bestätigen Sie alle aufgeführten Berechtigungen.
Bestand wird nach einer Änderung im Backoffice nicht gesendet
PrestaShop führt die Hooks eines Moduls nicht aus, wenn dem Mitarbeiter das Recht „Anzeigen“ für dieses Modul fehlt. Bei der Richtung vom Shop zur Kasse holt die Abweichungsprüfung des Cron diese Änderungen beim nächsten Lauf nach. Sie können das Recht auch unter Erweiterte Einstellungen > Team > Berechtigungen vergeben.
Ein Verkauf hat keine Bestellung erzeugt
Das Protokoll nennt den Grund: nicht zugeordnete Artikel, Verkaufswährung in PrestaShop nicht aktiv, Produkt auf bestimmte Versanddienste beschränkt oder eine Menge unter einer Einheit. Der Bestand wurde dann direkt verarbeitet. Beheben Sie die Ursache für die folgenden Verkäufe. Die Schaltfläche PrestaShop-Bestellung anlegen wird nur für einen Verkauf angeboten, dessen Bestand noch nicht abgezogen wurde, damit er nie doppelt abgezogen wird.
Die Bestellsumme weicht vom Beleg ab
Prüfen Sie, ob die PrestaShop-Steuerregel der Produkte dem an der Kasse verwendeten MwSt.-Satz entspricht. Die Abweichung wird beim Verkauf angezeigt.
Deinstallation
Die Deinstallation löscht die Tabellen des Moduls (Zuordnungen, Verkaufsjournal, Warteschlangen, technisches Protokoll, Abgleiche, Warnungen) und seine Einstellungen und deaktiviert den Versanddienst „Kassenverkauf“. Erstellte Bestellungen, der Bestellstatus, der Laufkunde und die Gründe für Lagerbewegungen bleiben erhalten, da die Historie auf sie verweist.