Kassasysteem Koppelen aan PrestaShop (Square, Zettle, SumUp): documentatie

Werking

PrestaShop is leidend voor de voorraad. Elke voorraadwijziging van een gekoppeld product gaat als absolute hoeveelheid naar de kassa. Elke kassaverkoop wordt geïmporteerd, met de bewegingsreden „Kassaverkoop” van de PrestaShop-voorraad afgetrokken, daarna gaat het nieuwe niveau naar de andere kassa’s. Retouren zetten de artikelen terug in voorraad met de reden „Kassaretour”.

• Square: voorraad in beide richtingen, verkopen, retouren, catalogus versturen.
• Zettle by PayPal: voorraad in beide richtingen, verkopen, terugbetalingen, catalogus versturen.
• SumUp: alleen verkoopimport. De openbare API van SumUp stelt geen voorraad en geen catalogus beschikbaar.

Vereisten

• PrestaShop 8.0 tot 9.x.
• Een cronjob bij je hosting.
• HTTPS op de winkel voor de Zettle-webhook.
• Een Square-, Zettle- of SumUp-account met ontwikkelaarstoegang.

Installatie

1. Klik in Modules > Modulebeheer op Een module uploaden en verstuur het ZIP-bestand.
2. De module voegt het menu Catalogus > Kassakoppeling toe.
3. Het dashboard toont een lijst „Aan de slag” die zichzelf afvinkt tijdens de configuratie.

Kassa’s koppelen

Open het tabblad Verbindingen. Elke kassa heeft een eigen blok met het vakje Ingeschakeld. Inloggegevens worden versleuteld opgeslagen: een leeg gelaten veld behoudt de opgeslagen waarde.

Square

1. Maak een applicatie aan in het Square Developer Dashboard en kopieer het productietoegangstoken.
2. Plak het in Toegangstoken, kies de omgeving, sla op en klik op Verbinding testen.
3. Kies de locatie die de voorraad ontvangt. Heb je er meerdere, vink dan de locaties aan waarvan de verkopen moeten worden geïmporteerd (maximaal 10).
4. Voor directe import maak je een webhook-abonnement aan op het event order.updated met de getoonde notificatie-URL, en plak je de ondertekeningssleutel in de module. De URL moet aan beide kanten exact gelijk zijn.

Zettle by PayPal

1. Maak in het Zettle Developer Portal een self-hosted API-sleutel aan met de scopes READ:PURCHASE, READ:PRODUCT, READ:USERINFO en WRITE:PRODUCT.
2. Vul Client-ID en API-sleutel in, sla op en test de verbinding.
3. Klik op Webhook activeren om verkopen binnen enkele seconden te ontvangen.
4. Voorraadbeheer moet voor de producten in Zettle aan staan. Producten die de module verstuurt hebben dat automatisch.

SumUp

1. Vul je geheime API-sleutel (sup_sk_...) in, sla op en test de verbinding. De handelaarscode wordt automatisch gedetecteerd.
2. SumUp-verkopen worden gekoppeld op artikelnaam: exacte referentie of exacte naam van een product zonder combinaties.

Synchronisatieregels

Bovenaan het tabblad Verbindingen:

• PrestaShop-voorraadniveaus naar de kassa sturen, optioneel direct na elke wijziging.
• Kassaverkopen importeren en van de PrestaShop-voorraad aftrekken.
• Geretourneerde artikelen terugzetten in voorraad (Square en Zettle).
• Automatische koppeling op referentie, op EAN-13 / UPC en voor SumUp op naam.
• Kassaverkopen importeren vanaf: eerdere verkopen worden genegeerd. Een al geïmporteerde verkoop wordt nooit dubbel opgenomen.

Geplande taak en webhooks

Het dashboard toont twee URL’s. Plan de eerste elke 5 minuten en de tweede (met full=1) één keer per nacht:

*/5 * * * * curl -s "https://jouw-winkel.nl/module/dfposconnector/cron?token=JOUW_TOKEN" >/dev/null
0 3 * * * curl -s "https://jouw-winkel.nl/module/dfposconnector/cron?token=JOUW_TOKEN&full=1" >/dev/null

De cron importeert nieuwe verkopen, verstuurt wachtende voorraad en detecteert verschillen die buiten PrestaShop zijn ontstaan (SQL-import, ERP). De nachtelijke synchronisatie verstuurt alle gekoppelde niveaus opnieuw. Cron en webhooks werken ook in onderhoudsmodus.

Producten koppelen

Tabblad Productkoppeling:

• Catalogus lezen van Square of Zettle: koppelt automatisch op SKU en barcode.
• Producten op naam voorstellen: stelt voor elk resterend artikel een product voor, met een score. Suggesties van 90 % of meer kun je in één keer accepteren, de andere één voor één.
• Handmatig koppelen: zoek een product op naam, referentie of EAN.
• Alle voorraad naar de kassa sturen, of voorraad importeren van de kassa naar PrestaShop (gebruik dit één keer, bij de installatie, als de kassavoorraad de betrouwbare is).

Catalogus naar de kassa versturen

Tabblad Catalogus versturen: kies de kassa, een categorie (inclusief subcategorieën), de verstuurde prijs (incl. of excl. btw, zonder kortingen) en of alleen actieve producten meedoen.

1. Controleren wat er verstuurd wordt leest eerst de kassacatalogus, koppelt wat al bestaat en toont daarna het aantal aan te maken producten en varianten.
2. Aanmaken in de kassa verstuurt de producten in batches met een voortgangsbalk. Combinaties worden varianten. Elk aangemaakt artikel wordt gekoppeld en krijgt zijn voorraad.

Niet verstuurd: producten die in die kassa al gekoppeld zijn, virtuele producten, pakketten, afbeeldingen en categorieën. Zettle accepteert maximaal 99 varianten per product.

Voorraadcontrole

Het tabblad Voorraadcontrole leest de echte hoeveelheden uit Square of Zettle en toont de verschillen met PrestaShop, grootste eerst. Per regel:

• PrestaShop-voorraad versturen: de kassa krijgt de PrestaShop-waarde.
• Kassavoorraad overnemen: PrestaShop krijgt de kassawaarde, met een voorraadbeweging.

PrestaShop-bestellingen voor winkelverkopen

Blok PrestaShop-bestellingen, standaard uit. Ingeschakeld maakt elke verkoop waarvan alle artikelen gekoppeld zijn een bestelling aan:

• eigen toonbankklant op het winkeladres;
• gratis vervoerder „Kassaverkoop”, nooit aangeboden in de checkout;
• bonprijzen, waarbij een korting op de hele bon over de regels wordt verdeeld;
• bestelling gedateerd op het moment van de verkoop, met de kassareferentie in de interne notitie;
• status „Kassaverkoop” (betaald, geleverd, zonder factuur en e-mail), aan te passen in de instellingen.

Dan trekt de bestelling zelf de voorraad af. Tijdens het aanmaken wordt geen e-mail verstuurd. Een verkoop met niet-gekoppelde artikelen krijgt geen bestelling: de gekoppelde artikelen worden rechtstreeks afgetrokken.

Verkoopjournaal

Het tabblad Kassaverkopen toont elke verkoop met regels, kassa, locatie, betaling en eventueel de link naar de bestelling. Filters: kassa, status (te koppelen, gekoppeld, retouren, met bestelling), zoeken op bon, artikel of locatie, datumbereik. De knop CSV exporteren exporteert de selectie, één rij per artikel.

E-mailmeldingen

Blok E-mailmeldingen: er wordt een e-mail verstuurd wanneer de geplande synchronisatie 3 keer op rij mislukt (hooguit één per 6 uur), en nog een wanneer ze weer werkt. Laat het adres leeg om het winkeladres te gebruiken. De knop Testmelding versturen controleert de verzending.

Problemen oplossen

„Inventaris niet geïnitialiseerd” bij Zettle

Schakel voorraadbeheer in voor minstens één product in Zettle, of verstuur een product vanuit het tabblad Catalogus versturen.

Square-webhook geweigerd (ongeldige handtekening)

De notificatie-URL in Square moet teken voor teken gelijk zijn aan die van de module, en de ondertekeningssleutel moet bij dat abonnement horen.

Voorraad wordt niet verstuurd na een wijziging in de back-office

PrestaShop voert de hooks van een module niet uit voor een medewerker zonder het recht „Bekijken” op die module. De verschilcontrole van de cron vangt die wijzigingen op bij de volgende run. Je kunt het recht ook toekennen in Geavanceerde instellingen > Team > Rechten.

Een verkoop heeft geen bestelling aangemaakt

Het technisch logboek geeft de reden: niet-gekoppelde artikelen, valuta van de verkoop ontbreekt in PrestaShop, vervoerdersbeperking op een product of een hoeveelheid onder één eenheid. De voorraad is dan rechtstreeks afgetrokken.

Verwijderen

Het verwijderen wist de tabellen van de module (koppelingen, verkoopjournaal, wachtrij, technisch logboek) en de instellingen, en schakelt de vervoerder „Kassaverkoop” uit. Aangemaakte bestellingen, de bestelstatus, de toonbankklant en de redenen voor voorraadbewegingen blijven bewaard, omdat de geschiedenis ernaar verwijst.