Kassensystem mit PrestaShop verbinden (Square, Zettle, SumUp): Dokumentation

Funktionsweise

PrestaShop ist führend beim Bestand. Jede Bestandsänderung eines zugeordneten Produkts geht als absolute Menge an die Kasse. Jeder Kassenverkauf wird importiert, mit dem Bewegungsgrund „Kassenverkauf“ vom PrestaShop-Bestand abgezogen, danach geht der neue Bestand an die anderen Kassen. Rückgaben buchen die Artikel mit dem Grund „Kassenrückgabe“ zurück in den Bestand.

• Square: Bestand in beide Richtungen, Verkäufe, Rückgaben, Katalogversand.
• Zettle by PayPal: Bestand in beide Richtungen, Verkäufe, Erstattungen, Katalogversand.
• SumUp: nur Verkaufsimport. Die öffentliche SumUp-API stellt weder Bestand noch Katalog bereit.

Voraussetzungen

• PrestaShop 8.0 bis 9.x.
• Ein Cronjob bei Ihrem Hoster.
• HTTPS im Shop für den Zettle-Webhook.
• Ein Square-, Zettle- oder SumUp-Konto mit Entwicklerzugang.

Installation

1. Klicken Sie unter Module > Modulmanager auf Modul hochladen und senden Sie das ZIP.
2. Das Modul fügt das Menü Katalog > Kassen-Connector hinzu.
3. Das Dashboard zeigt eine Liste „Erste Schritte“, die sich während der Einrichtung selbst abhakt.

Kassen verbinden

Öffnen Sie den Tab Verbindungen. Jede Kasse hat einen eigenen Bereich mit dem Kästchen Aktiviert. Die Zugangsdaten werden verschlüsselt gespeichert: Ein leer gelassenes Feld behält den gespeicherten Wert.

Square

1. Erstellen Sie im Square Developer Dashboard eine Anwendung und kopieren Sie deren Produktions-Zugriffstoken.
2. Fügen Sie es unter Zugriffstoken ein, wählen Sie die Umgebung, speichern Sie und klicken Sie auf Verbindung testen.
3. Wählen Sie den Standort, der den Bestand erhält. Bei mehreren Standorten markieren Sie die, deren Verkäufe importiert werden sollen (höchstens 10).
4. Für den Sofortimport legen Sie ein Webhook-Abonnement für das Ereignis order.updated mit der angezeigten Benachrichtigungs-URL an und fügen den Signaturschlüssel im Modul ein. Die URL muss auf beiden Seiten exakt gleich sein.

Zettle by PayPal

1. Erstellen Sie im Zettle Developer Portal einen Self-hosted-API-Schlüssel mit den Scopes READ:PURCHASE, READ:PRODUCT, READ:USERINFO und WRITE:PRODUCT.
2. Geben Sie Client-ID und API-Schlüssel ein, speichern Sie und testen Sie die Verbindung.
3. Klicken Sie auf Webhook aktivieren, um Verkäufe innerhalb von Sekunden zu erhalten.
4. Die Bestandsverfolgung muss für die Produkte in Zettle aktiv sein. Vom Modul gesendete Produkte haben sie automatisch.

SumUp

1. Geben Sie Ihren geheimen API-Schlüssel (sup_sk_...) ein, speichern Sie und testen Sie die Verbindung. Der Händlercode wird automatisch erkannt.
2. SumUp-Verkäufe werden über den Artikelnamen zugeordnet: exakte Artikelnummer oder exakter Name eines Produkts ohne Kombinationen.

Synchronisationsregeln

Oben im Tab Verbindungen:

• PrestaShop-Bestände an die Kasse senden, optional direkt nach jeder Änderung.
• Kassenverkäufe importieren und vom PrestaShop-Bestand abziehen.
• Zurückgegebene Artikel wieder einlagern (Square und Zettle).
• Automatische Zuordnung über Artikelnummer, EAN-13 / UPC und für SumUp über den Namen.
• Kassenverkäufe importieren ab: Frühere Verkäufe werden ignoriert. Ein bereits importierter Verkauf wird nie doppelt erfasst.

Geplante Aufgabe und Webhooks

Das Dashboard zeigt zwei URLs. Planen Sie die erste alle 5 Minuten und die zweite (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 importiert neue Verkäufe, sendet ausstehende Bestände und erkennt Abweichungen, die außerhalb von PrestaShop entstanden sind (SQL-Import, ERP). Die nächtliche Synchronisation sendet alle zugeordneten Bestände erneut. Cron und Webhooks funktionieren auch im Wartungsmodus.

Produkte zuordnen

Tab Produktzuordnung:

• Katalog lesen von Square oder Zettle: ordnet automatisch per SKU und Barcode zu.
• Produkte nach Namen vorschlagen: schlägt für jeden verbleibenden Artikel ein Produkt mit Punktzahl vor. Vorschläge ab 90 % lassen sich gesammelt übernehmen, die übrigen einzeln.
• Manuelle Zuordnung: Produkt nach Name, Artikelnummer oder EAN suchen.
• Gesamten Bestand an die Kasse senden oder Bestand aus der Kasse importieren (nur einmal bei der Einrichtung, wenn der Kassenbestand der verlässliche ist).

Katalog an die Kasse senden

Tab Katalog senden: Wählen Sie die Kasse, eine Kategorie (inklusive Unterkategorien), den gesendeten Preis (brutto oder netto, ohne Rabatte) und ob nur aktive Produkte betroffen sind.

1. Prüfen, was gesendet wird liest zuerst den Kassenkatalog, ordnet Vorhandenes zu und zeigt dann die Zahl der zu erstellenden Produkte und Varianten.
2. In der Kasse erstellen sendet die Produkte in Paketen mit Fortschrittsbalken. Kombinationen werden zu Varianten. Jeder erstellte Artikel wird zugeordnet und erhält seinen Bestand.

Nicht gesendet werden: bereits in dieser Kasse zugeordnete Produkte, virtuelle Produkte, Pakete, Bilder und Kategorien. Zettle akzeptiert höchstens 99 Varianten pro Produkt.

Bestandsprüfung

Der Tab Bestandsprüfung liest die echten Mengen aus Square oder Zettle und listet die Abweichungen zu PrestaShop, die größten zuerst. Für jede Zeile:

• PrestaShop-Bestand senden: Die Kasse erhält den PrestaShop-Wert.
• Kassenbestand übernehmen: PrestaShop erhält den Kassenwert, mit Lagerbewegung.

PrestaShop-Bestellungen für Ladenverkäufe

Bereich PrestaShop-Bestellungen, standardmäßig aus. Aktiviert erzeugt jeder Verkauf mit vollständig zugeordneten Artikeln eine Bestellung:

• eigener Laufkunde mit der Ladenadresse;
• kostenloser Versanddienst „Kassenverkauf“, im Checkout nie angeboten;
• Belegpreise, ein Gesamtrabatt wird auf die Zeilen verteilt;
• Bestellung auf den Verkaufszeitpunkt datiert, mit der Kassenreferenz in der internen Notiz;
• Status „Kassenverkauf“ (bezahlt, zugestellt, ohne Rechnung und E-Mail), in den Einstellungen änderbar.

Dann zieht die Bestellung den Bestand selbst ab. Während der Erstellung wird keine E-Mail versendet. Ein Verkauf mit nicht zugeordneten Artikeln erhält keine Bestellung: Seine zugeordneten Artikel werden direkt abgezogen.

Verkaufsjournal

Der Tab Kassenverkäufe listet jeden Verkauf mit Zeilen, Kasse, Standort, Zahlung und gegebenenfalls dem Link zur Bestellung. Filter: Kasse, Status (zuzuordnen, zugeordnet, Rückgaben, mit Bestellung), Suche nach Beleg, Artikel oder Standort, Datumsbereich. Die Schaltfläche CSV exportieren exportiert die Auswahl, eine Zeile pro Artikel.

E-Mail-Warnungen

Bereich E-Mail-Warnungen: Eine E-Mail wird gesendet, wenn die geplante Synchronisation 3 Mal in Folge fehlschlägt (höchstens eine alle 6 Stunden), und eine weitere, sobald sie wieder funktioniert. Lassen Sie die Adresse leer, um die Shop-Adresse zu verwenden. Die Schaltfläche 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 senden.

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.

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. Die Abweichungsprüfung des Cron holt 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 technische Protokoll nennt den Grund: nicht zugeordnete Artikel, Verkaufswährung in PrestaShop nicht vorhanden, Versandeinschränkung an einem Produkt oder eine Menge unter einer Einheit. Der Bestand wurde dann direkt abgezogen.

Deinstallation

Die Deinstallation löscht die Tabellen des Moduls (Zuordnungen, Verkaufsjournal, Warteschlange, technisches Protokoll) und seine Einstellungen und deaktiviert den Versanddienst „Kassenverkauf“. Erstellte Bestellungen, der Bestellstatus, der Laufkunde und die Bewegungsgründe bleiben erhalten, da die Historie auf sie verweist.