PS PrestaShop Gemiddeld

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

De module installeren, Square, Zettle of SumUp koppelen, producten koppelen en voorraad en verkopen synchroniseren tussen kassa en PrestaShop.

Bijgewerkt Moduleversie 2.0.0

Werking

De module koppelt PrestaShop aan je kassa van Square, Zettle by PayPal of SumUp. Ze importeert elke verkoop, retour en terugbetaling van de kassa in een journaal, werkt de voorraad bij in de richting die je kiest en kan van elke verkoop een PrestaShop-bestelling maken. Ze kan ook je PrestaShop-catalogus naar de kassa versturen.

De voorraad wordt in een van de volgende drie richtingen gesynchroniseerd, in te stellen per kassa:

  • Van winkel naar kassa: PrestaShop is leidend. Kassaverkopen worden in PrestaShop afgeboekt, daarna gaat het nieuwe niveau terug naar de kassa.
  • Van kassa naar winkel: de kassa is leidend. PrestaShop neemt de hoeveelheden van de kassa over bij elke cron-uitvoering en bij elke voorraadwebhook.
  • In beide richtingen: de wijzigingen aan beide kanten sinds de laatste synchronisatie worden opgeteld. Een online verkoop en een verkoop in de winkel tellen elk één keer.
Dashboard van de kassakoppeling: geïmporteerde verkopen, gesynchroniseerde voorraad, fouten, wachtrij en laatste synchronisatie
Dashboard van de kassakoppeling

Wat elke kassa ondersteunt

  • Square: verkopen, retouren en terugbetalingen, voorraad in alle drie de richtingen, meerdere vestigingen, catalogus versturen met de hoofdafbeelding, ondertekende webhooks.
  • Zettle by PayPal: verkopen en terugbetalingen, voorraad in alle drie de richtingen, catalogus versturen, ondertekende webhook die de module zelf aanmaakt.
  • SumUp: verkopen en terugbetalingen, afgeboekt van de PrestaShop-voorraad. De openbare API van SumUp biedt geen voorraad, geen catalogus en geen webhook voor kassaverkopen. De import loopt daarom via de cron, en de voorraad in SumUp wordt niet bijgewerkt.

De module vervangt je kassa niet en maakt er geen gecertificeerde kassa van. Bonnen, dagafsluiting en fiscale verplichtingen blijven bij Square, Zettle of SumUp.

Vereisten

  • PrestaShop 1.7.8 tot 9.x. De module is getest op PrestaShop 1.7.8.11 (PHP 7.4), 8.2.1 (PHP 8.1) en 9.1.5 (PHP 8.5).
  • Een cronjob bij je hosting.
  • Een winkel op HTTPS voor de webhooks en voor de OAuth-verbinding.
  • Een Square-, Zettle- of SumUp-account, en toegang tot de ontwikkelaarsomgeving ervan als je verbinding maakt met een token of een API-sleutel.

Installatie en update

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

Om van een versie 1.x naar 2.0.0 te gaan, verstuur je het nieuwe ZIP-bestand op dezelfde manier. De update behoudt de koppelingen, het verkoopjournaal, de verbindingen, de importcursors (geen enkele verkoop wordt opnieuw geïmporteerd) en de instellingen. Bestaande webhook-URL’s blijven geldig. De update voegt de nieuwe tabellen toe, versleutelt de oude geheimen opnieuw en haalt bij de status „Kassaverkoop” de verzendmarkering weg die een tweede betaling veroorzaakte. Al aangemaakte bestellingen worden niet gewijzigd.

Kassa’s koppelen

Het tabblad Verbindingen toont de status van elke kassa en de beschikbare functies. Elke kassa heeft een eigen wizard. Geheimen worden versleuteld opgeslagen en nooit opnieuw getoond of in het logboek geschreven. Een leeg gelaten veld behoudt de opgeslagen waarde.

Verbindingen met Square, Zettle en SumUp met hun functies
Verbindingen met Square, Zettle en SumUp met hun functies

Square

  1. Kies hoe je verbinding maakt. OAuth wordt aanbevolen: je autoriseert de module vanuit je Square-account, en het token wordt automatisch vernieuwd. Voor één winkel kun je ook een persoonlijk toegangstoken plakken.
  2. Bij OAuth vul je de ID en het secret van je Square-applicatie in, en geef je in die applicatie de getoonde redirect-URL op. De module vraagt alleen de nodige rechten: vestigingen, bestellingen, betalingen, catalogus, voorraad en klanten lezen, catalogus en voorraad schrijven.
  3. Klik op Verbinden met Square, accepteer de rechten en klik daarna op Test de verbinding.
  4. Kies de vestiging die de voorraad bevat, en vink de vestigingen aan waarvan de verkopen worden geïmporteerd (maximaal 10).
  5. Voor directe import voeg je in Webhooks > Subscriptions de getoonde notificatie-URL toe met de events order.updated, refund.created, inventory.count.updated en oauth.authorization.revoked. Plak daarna de handtekeningsleutel in de module. De URL moet aan beide kanten teken voor teken gelijk zijn.
Square-verbindingsassistent: OAuth, minimale rechten, vestigingen
Square-verbindingsassistent

De OAuth-knop stuurt je naar de autorisatiepagina van de kassa, op haar eigen website, en brengt je daarna terug in de module. De schermafbeelding hieronder is gemaakt in demomodus, met een gesimuleerd autorisatiescherm.

Gesimuleerd OAuth-autorisatiescherm (demomodus)
Gesimuleerd OAuth-autorisatiescherm (demomodus)
Square-vestigingen: voorraadvestiging en import van verkopen
Square-vestigingen

Zettle by PayPal

  1. Voor één winkel wordt de self-hosted API-sleutel aanbevolen: maak hem aan in het Zettle Developer Portal en plak hem samen met de Client-ID. Voor een partnerapplicatie is er ook een OAuth-verbinding, met automatische vernieuwing van de tokens.
  2. Sla op en test de verbinding.
  3. Klik op Webhook activeren: de module maakt het abonnement zelf aan (PurchaseCreated, InventoryBalanceChanged) en bewaart de handtekeningsleutel versleuteld. Zettle vereist een winkel op HTTPS.
  4. Voorraadbeheer moet voor de producten in Zettle aan staan. Producten die de module verstuurt hebben dat automatisch.
Zettle-verbindingsassistent: API-sleutel of OAuth en ondertekende webhook
Zettle-verbindingsassistent

SumUp

  1. Plak je geheime API-sleutel (SumUp-dashboard, Developers > API keys) met je merchantcode, of maak verbinding via OAuth.
  2. Test de verbinding. Ontbreekt de merchantcode, dan wordt die automatisch opgehaald.
  3. SumUp stuurt geen webhook voor kassaverkopen. Ze worden daarom elke 5 minuten via de cron geïmporteerd. Ze worden gekoppeld op referentie of op artikelnaam.
SumUp-verbindingsassistent: API-sleutel of OAuth, import via cron
SumUp-verbindingsassistent

Een kassa loskoppelen

De knop Verbinding verbreken trekt de tokens in als de kassa dat toestaat (Square, Zettle) en verwijdert ze uit PrestaShop. De koppelingen en het verkoopjournaal blijven bewaard.

Richting van de voorraad

Kies in Instellingen > Voorraad de richting van de voorraad voor Square en voor Zettle: van winkel naar kassa, van kassa naar winkel, in beide richtingen of geen voorraadsynchronisatie. Bij SumUp worden de verkopen van de PrestaShop-voorraad afgeboekt, maar de kassa zelf ontvangt geen voorraad.

  • Slechts één kassa kan leidend zijn voor de voorraad. Kies je een tweede, dan zet de module die op In beide richtingen.
  • In beide richtingen beslist de leidende bron over de eerste gelijktrekking en over conflicten.
  • Een niveau dat de module zelf schrijft, wordt nooit teruggestuurd, om echo’s te voorkomen. Als de kassa haar eigen verkopen al meetelt, boekt de import ze niet nog een keer af.
  • De optie Direct na elke voorraadwijziging in PrestaShop verzenden verstuurt het niveau meteen. Anders gaat het mee met de volgende cron-uitvoering.
Richting van de voorraadsynchronisatie per kassa en leidende bron
Richting van de voorraadsynchronisatie per kassa en leidende bron

Producten koppelen

Het tabblad Koppelingen koppelt elk kassa-artikel aan een PrestaShop-product of een combinatie.

  • De catalogus lezen van Square of Zettle: de artikelen worden automatisch gekoppeld op SKU (referentie van het product of de combinatie) en op barcode EAN-13 / UPC.
  • Suggesties op naam: voor elk resterend artikel stelt de module het meest gelijkende product voor, met een score. Suggesties van 90 % of meer kun je in één keer accepteren, de andere één voor één. Geen enkele suggestie wordt opgeslagen zonder jouw bevestiging.
  • Handmatig koppelen: zoek een product op naam, referentie of EAN.
  • Een artikel dat aan de kassa is verkocht maar niet in de gelezen catalogus staat, verschijnt ook in de lijst. Je kunt het verbergen als het niet online wordt verkocht.
Koppelingen tussen kassa-artikelen en PrestaShop-producten met suggesties
Koppelingen tussen kassa-artikelen en PrestaShop-producten met suggesties

Als je een artikel koppelt, wordt de voorraad van de al geïmporteerde verkopen één keer bijgewerkt. De eerdere verkoopregels worden aan de nieuwe regel gekoppeld.

Catalogus naar de kassa versturen

Het tabblad Catalogus maakt je PrestaShop-producten aan in Square of Zettle: combinaties als varianten, prijzen, SKU, barcode, optioneel de hoofdafbeelding, en daarna de voorraad. 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 wordt verzonden leest eerst de kassacatalogus, koppelt wat al bestaat op SKU of barcode, en toont daarna het aantal aan te maken producten en varianten.
  2. Vink de bevestiging aan en klik op Aanmaken in de kassa: de producten gaan in batches over, met een voortgangsbalk, en elk aangemaakt artikel wordt meteen gekoppeld.
PrestaShop-catalogus naar de kassa sturen met voorbeeld vóór het aanmaken
PrestaShop-catalogus naar de kassa sturen met voorbeeld vóór het aanmaken

Bestaande artikelen in de kassa worden nooit gewijzigd. Bij Square wordt elk artikel gekoppeld aan een bestaande Square-belasting met hetzelfde tarief: er wordt geen belasting aangemaakt. Virtuele producten en pakketten worden overgeslagen, en categorieën worden niet verstuurd. Zettle accepteert maximaal 99 varianten per product. SumUp kan via zijn API geen producten ontvangen.

Voorraadcontrole en afstemming

Het tabblad Voorraad vergelijkt voor elk gekoppeld artikel de PrestaShop-voorraad met de kassavoorraad, en toont de verschillen. Voor elk verschil, of voor een selectie:

  • PrestaShop behouden: de kassa krijgt de PrestaShop-hoeveelheid.
  • Kassa behouden: PrestaShop krijgt de hoeveelheid van de kassa, met een voorraadbeweging.

De volledige nachtelijke synchronisatie start een afstemming en bewaart het rapport. Eerdere rapporten blijven beschikbaar. Alle kassaniveaus importeren overschrijft de PrestaShop-voorraad van elk gekoppeld product. Gebruik dit maar één keer, bij de installatie, als de kassavoorraad de betrouwbaarste is.

Voorraadafstemming tussen PrestaShop en de kassa met verschillenrapport
Voorraadafstemming tussen PrestaShop en de kassa met verschillenrapport

Kassaverkopen

Het tabblad Kassaverkopen toont elke bon met de regels, de kassa, de vestiging, de betaling, de btw per regel, de fooi en, indien van toepassing, de PrestaShop-bestelling. Filters: kassa, type (verkopen, retouren en terugbetalingen, PrestaShop-bestellingen), bedragverschillen, zoeken op bon, artikel, vestiging of bestelnummer, en datumbereik. CSV exporteren exporteert de selectie.

Logboek van kassaverkopen met PrestaShop-bestelling, btw en fooi
Logboek van kassaverkopen met PrestaShop-bestelling, btw en fooi

De import is idempotent: een al geïmporteerde verkoop wordt nooit dubbel opgenomen, ook niet als hij tegelijk via meerdere webhooks en via de cron binnenkomt. Bonnen die offline aan de kassa zijn geregistreerd en later worden doorgestuurd, worden ook geïmporteerd. Verkopen van vóór de datum in Kassaverkopen importeren vanaf worden genegeerd.

PrestaShop-bestellingen voor winkelverkopen

In Instellingen > Bestellingen en terugbetalingen staat de optie Een PrestaShop-bestelling aanmaken voor elke kassaverkoop waarvan alle artikelen gekoppeld zijn standaard uit. Zodra je ze inschakelt:

  • één passant per winkel, op het adres van de winkel;
  • een gratis vervoerder „Kassaverkoop”, nooit aangeboden bij het afrekenen;
  • de betaalmethode „Kassa – Square / Zettle / SumUp”, één enkele betaling, en een bestelling gedateerd op het tijdstip van de verkoop;
  • de prijzen en kortingen van de bon, verdeeld over de regels;
  • de fooi buiten het totaal van de bestelling, vermeld in de notitie;
  • geen e-mail, niet naar de klant en niet naar jou.

De standaardstatus is „Kassaverkoop” (betaald, geleverd, zonder e-mail en zonder factuur). Berekent PrestaShop een ander totaal dan de bon (belastingregels, afrondingen), dan wordt het verschil bij de verkoop getoond en in het logboek genoteerd.

Instellingen voor bestellingen, facturen, terugbetalingen en herkende klanten
Instellingen voor bestellingen, facturen, terugbetalingen en herkende klanten
  • Facturen toestaan voor kassabestellingen: standaard uit, omdat de kassa de bon al levert. Zonder deze optie wordt een status die een factuur aanmaakt geweigerd. Met deze optie wordt de factuur aangemaakt op de bestaande betaling en in het logboek gemeld.
  • Geïdentificeerde klanten (Square): de bestelling kan worden gekoppeld aan de bestaande PrestaShop-klant met hetzelfde e-mailadres als de Square-klant. Alleen een bestaande klant met een adres wordt gebruikt: er wordt geen klant en geen adres aangemaakt.
PrestaShop-bestelling aangemaakt voor een kassaverkoop, met het bonoverzicht
PrestaShop-bestelling aangemaakt voor een kassaverkoop, met het bonoverzicht

Een verkoop met niet-gekoppelde artikelen krijgt geen bestelling: de gekoppelde artikelen worden rechtstreeks van de voorraad afgeboekt.

Retouren en terugbetalingen

Retouren van Square, terugbetalingen van Zettle en terugbetalingen van SumUp worden geïmporteerd, gedeeltelijke inbegrepen. Geretourneerde artikelen gaan één keer terug in voorraad, via de retourregel. Een terugbetaling zonder geretourneerd artikel wijzigt de voorraad niet. Kies voor de oorspronkelijke bestelling:

  • Alleen een notitie in de bestelling (standaard);
  • Creditnota voor de geretourneerde artikelen of het terugbetaalde bedrag;
  • Creditnota, en status „Terugbetaald” zodra de bestelling volledig is terugbetaald.
Gedeeltelijke kassaretour terug in voorraad met creditnota
Gedeeltelijke kassaretour terug in voorraad met creditnota

Geplande taken en webhooks

Instellingen > Geplande taken toont de URL van de cron. Roep die elke 5 minuten aan, en dezelfde URL 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 verwerkt de wachtrij van de webhooks, importeert nieuwe verkopen, vernieuwt de tokens en verstuurt de wachtende voorraadniveaus. Twee uitvoeringen overlappen nooit. De nachtelijke uitvoering verstuurt alle gekoppelde niveaus opnieuw en maakt het afstemmingsrapport.

Elke webhook wordt gecontroleerd voordat hij wordt geaccepteerd:

  • de eigen URL-sleutel van de webhooks, los van het token van de cron;
  • de handtekening van de kassa;
  • een maximale grootte van 256 KB;
  • een maximale leeftijd van 96 uur;
  • een event-ID die nog nooit is gezien.

De module antwoordt meteen en verwerkt het event daarna. Een notificatie zonder handtekening, met een foute handtekening of die opnieuw wordt afgespeeld, wordt geweigerd en in het logboek genoteerd.

Technisch logboek

Het tabblad Logboek toont fouten, waarschuwingen en informatie, te filteren op kassa, niveau, probleem, tekst en datum. Elke bekende fout vermeldt de oorzaak en de oplossing, met een link naar het betreffende scherm. Tokens, sleutels en handtekeningen worden gemaskeerd voordat ze worden weggeschreven. De vermeldingen worden standaard 30 dagen bewaard (instelbaar), en de laatst ontvangen webhook-events worden getoond.

Filterbaar technisch logboek met oorzaak en oplossing van elke fout
Filterbaar technisch logboek met oorzaak en oplossing van elke fout

Meldingen

Het tabblad Meldingen verzamelt de lopende problemen met hun oorzaak, hun oplossing en een knop Nu oplossen. Een melding sluit vanzelf zodra het probleem verdwijnt.

  • synchronisatie mislukt bij 3 uitvoeringen op rij, en daarna een bericht zodra ze weer werkt;
  • token geweigerd of niet te vernieuwen, ontbrekend recht, geweigerde webhook-handtekeningen;
  • opgegeven voorraadupdates, cron die niet meer draait;
  • artikelen verkocht aan de kassa zonder PrestaShop-product;
  • verschillen gevonden bij de nachtelijke afstemming.
Meldingencentrum met oorzaak, oplossing en e-mails
Meldingencentrum met oorzaak, oplossing en e-mails

Meldingen kunnen ook per e-mail worden verstuurd, hooguit één per 6 uur per melding. Laat het adres leeg om het adres van de winkel te gebruiken. Testmelding versturen controleert de verzending.

Meldingsmail van de kassakoppeling met uitleg en oplossing
Meldingsmail van de kassakoppeling met uitleg en oplossing

Problemen oplossen

„Inventaris niet geïnitialiseerd” bij Zettle

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

Square-webhook geweigerd (ongeldige handtekening)

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

Token geweigerd of ontbrekend recht

Open Verbindingen, koppel de kassa opnieuw met haar wizard en accepteer alle vermelde rechten.

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. In de richting van winkel naar kassa vangt de verschilcontrole van de cron die wijzigingen op bij de volgende uitvoering. Je kunt het recht ook toekennen in Geavanceerde instellingen > Team > Rechten.

Een verkoop heeft geen bestelling aangemaakt

Het logboek vermeldt de reden: niet-gekoppelde artikelen, valuta van de verkoop niet actief in PrestaShop, product beperkt tot bepaalde vervoerders, of een hoeveelheid onder één eenheid. De voorraad is dan rechtstreeks verwerkt. Los de oorzaak op voor de volgende verkopen. De knop PrestaShop-bestelling aanmaken wordt alleen aangeboden voor een verkoop waarvan de voorraad nog niet is afgeboekt, zodat die nooit twee keer wordt afgeboekt.

Het totaal van de bestelling wijkt af van de bon

Controleer of de PrestaShop-belastingregel van de producten overeenkomt met het btw-tarief dat aan de kassa wordt gebruikt. Het verschil wordt bij de verkoop getoond.

Verwijderen

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

Was deze pagina nuttig?

Loopt u nog vast? Neem contact op met support