Laat de boekhouding meteen weten wat er aan de kassa verkocht is, niet pas
aan het eind van de week.
Bij een klant met een winkel gaat de kassaverkoop nu één keer per week naar de boekhouding: een export uit de kassa wordt een verplaatsing van het groothandelsmagazijn naar het winkelmagazijn. Dat werkt, maar het betekent dat de voorraad in de boekhouding tot zes dagen achterloopt.
De volgende stap is per bon. MplusKASSA kan daarvoor zelf aan de bel trekken met een webhook: na elke verkoop stuurt de kassa een bericht naar een adres dat jij opgeeft. Wij bouwden een ontvanger en hingen er onze eigen testkassa aan. Dit is wat er binnenkomt, en waar je voor oppast. Alles hieronder is getest op onze testkassa, niet op die van de klant.
Wat de kassa stuurt
Je stelt webhooks in de backoffice van Mplus in, onder Beheer > Instellingen > Webhooks: een adres, een geheime sleutel, de gebeurtenissen die je wil horen en of de kassa op je antwoord moet wachten. Via de API kun je ze alleen uitlezen, niet aanmaken of wijzigen.
De gebeurtenis die je voor voorraad en boekhouding wil, heet completeSession: een bon is afgerekend. Mplus plakt de naam van de gebeurtenis achter je adres, dus /hook wordt /hook/completeSession.
Bij ons kwam het bericht binnen een seconde na het afrekenen binnen. Het is JSON, met drie delen:
- event: of de kassa op je antwoord wacht, een volgnummer en een tijdstip.
- sender: welke vestiging, welke kassa, welke medewerker en welke versie van de kassasoftware.
- session: de bon, met totalen inclusief en exclusief btw, de betalingen per methode en alle regels.
Per regel staan het artikelnummer, je eigen artikelcode, de barcode, het aantal, de prijs met en zonder btw, de korting, de omzetgroep en het btw-percentage. Die eigen artikelcode is de sleutel: bij onze klant staat daar de artikelcode uit de boekhouding. Daarmee weet je per regel welk artikel in de boekhouding er minder op voorraad is.
Let op: een veld dat leeg is, ontbreekt gewoon. Een artikel zonder eigen code of barcode heeft die velden niet in het bericht. Je code moet dat aankunnen.
Ondertekend, en jij ondertekent terug
Elke aanroep heeft een handtekening in de kop X-Mplus-Signature: een HMAC-SHA256 over de ruwe inhoud, met de geheime sleutel. Klopt de handtekening, dan weet je dat het bericht van jouw kassa komt en onderweg niet veranderd is. Je antwoord onderteken je op dezelfde manier.
Bij ons klopte de handtekening bij elke aanroep. Hoe je hem controleert, met code in PHP en Python, staat in een MplusKASSA-webhook instellen.
Blokkerend of niet
Hier zit de valkuil. Een webhook is niet-blokkerend of blokkerend.
Bij niet-blokkerend gaat de kassa gewoon door en hoort jouw ontvanger achteraf wat er gebeurd is. Bij blokkerend wacht de kassa op je antwoord. Dat heeft een voordeel: je antwoord kan iets terugdoen aan de kassa. Bij completeSession kun je bijvoorbeeld een tekst meegeven die onderaan de bon komt.
Het nadeel ontdekten we op de harde manier. Op onze testkassa stond nog een webhook uit de voorbeeldinrichting, blokkerend, met als adres letterlijk "todo". Vanaf dat moment lukte afrekenen niet meer. De kassa meldde: "het webadres is onbekend (C6)". Pas toen die webhook uit stond, ging afrekenen weer.
Een blokkerende webhook is dus een afhankelijkheid van je kassa. Ligt je server eruit, is je certificaat verlopen of reageert je code traag, dan staat er een klant aan de toonbank te wachten.
Onze regels daarom:
- Standaard niet-blokkerend. Alleen blokkerend als je antwoord aan de kassa echt iets toevoegt.
- Altijd snel antwoorden. De ontvanger slaat het bericht op en antwoordt meteen. Het verwerken (voorraad bijwerken, boeken) gebeurt daarna, los van de kassa.
- Nooit de kassa straffen voor jouw probleem. Ook bij een foute handtekening antwoordt onze ontvanger netjes. Het bericht wordt dan niet verwerkt, maar de kassa merkt er niets van.
Wat je ermee kunt
De voor de hand liggende toepassing: per bon de voorraad in de boekhouding bijwerken in plaats van per week. Bij onze klant is dat de volgende stap.
Er kan meer, als mogelijkheid: een omzetoverzicht per uur dat zichzelf bijwerkt, een melding als een artikel bijna op is, of een signaal bij een barcode die de kassa niet kent. Het bericht bevat alles wat daarvoor nodig is.
Veelgemaakte fouten
Een blokkerende webhook voor iets wat ook later kan. Voorraad bijwerken kan een seconde later. Laat de kassa daar niet op wachten.
Eerst verwerken, dan antwoorden. Sla op, antwoord, en verwerk daarna. Zwaar werk voor het antwoord maakt je kassa traag.
Een bericht met een foute handtekening toch verwerken. Dan kan iedereen die je adres kent voorraad uit je boekhouding boeken.
Ervan uitgaan dat elk veld er is. Lege velden ontbreken. Een artikel zonder eigen code moet op een lijst voor een mens, niet je hele verwerking laten vastlopen.
Een bon twee keer verwerken. Sla per bon het ID op en sla een bon die je al kent over. Dan maakt het niet uit of een bericht ooit dubbel binnenkomt.
Meer over wat een gekoppelde kassa kan, staat op MplusKASSA koppelen. Hoe we de API zelf leerden kennen, lees je in de MplusKASSA-API: wat we leerden in de eerste week.