Kun je uit onze kassa halen wat er deze week per artikel verkocht is, en
dat naast de voorraad in de boekhouding leggen?
De kassa is de plek waar een winkel of horecazaak zijn echte cijfers maakt. Wat er verkocht is, met welke btw, betaald met pin of contant. Wie de kassa aan de boekhouding of de voorraad wil knopen, moet dus bij de kassa naar binnen.
Voor een klant met een winkel die op MplusKASSA draait, hebben wij een ontwikkelaarsaccount bij Mplus genomen en de API een week lang van voor naar achter getest op een eigen testkassa. In de app van de klant leest de koppeling alleen. Alles wat schrijft, hebben we los getest op onze eigen testkassa, niet op die van de klant. De klant blijft anoniem en er staan hier geen bedragen, prijzen of marges.
Toegang: reken op een paar dagen
Een ontwikkelaarsaccount geeft je een partnerpagina met een identificatie, een geheime sleutel en een eigen ontwikkeldatabase met een kassalicentie voor twee vestigingen. De kassasoftware zelf is een Windows-programma dat je erbij installeert.
Daarna ging het niet meteen. Eerst gaf de API een 503: de API-server van een administratie komt pas online nadat de kassasoftware een keer met die database verbonden is geweest. Toen dat gedaan was, kregen we een paar dagen "Credentials not accepted!", met gegevens die klopten. Dat werd aan de kant van Mplus opgelost, en vanaf toen werkte alles.
Voor een echte klant loopt de toegang tot zijn eigen administratie meestal via zijn Mplus-dealer. Plan daar dus tijd voor, en begin ermee voordat je gaat bouwen.
SOAP, met 388 operaties
De API is SOAP. De beschrijving telt 388 operaties, en je gebruikt er in de praktijk een handvol. Je hoeft er geen zware SOAP-bibliotheek voor te gebruiken: wij bouwen het bericht zelf op en lezen het antwoord als gewone XML. Mplus heeft zelf een PHP-voorbeeldclient op GitHub, en die is handig om te zien hoe een bericht eruit moet zien.
Eén ding om op te letten: de identificatie en de geheime sleutel gaan mee in het adres van elke aanroep, niet in een kop. Wie zijn aanroepen logt, logt dus ook zijn sleutel. Wij tonen en bewaren het adres altijd zonder sleutel.
Getallen zonder komma
Bedragen komen in centen. Een artikel van € 2,09 heet in de API 209. Aantallen komen als geheel getal met een apart veld voor het aantal decimalen: 530 met drie decimalen is 0,530.
Dat is prima, als je het één keer aan de rand van je code omrekent en daarna nooit meer. Het gaat mis als een deel van je code met centen rekent en een ander deel met euro's.
Nog een klassieker: een lijst met één element komt niet terug als lijst, maar als los element. Twee bonnen is een lijst, één bon is een object. Maak van elke "een of meer" in je code altijd een lijst, ook als je denkt dat het er altijd meer zijn.
Alleen ophalen wat veranderd is
Voor artikelen, relaties, bonnen, orders en facturen houdt de kassa een teller bij, de syncMarker. Je vraagt bijvoorbeeld de producten op vanaf een bepaalde marker, met een maximum per antwoord. De hoogste marker in het antwoord plus één is je volgende startpunt.
Dat is hetzelfde patroon als bij de voorraad in Exact Online: één keer alles ophalen, daarna alleen nog de wijzigingen. Het houdt je koppeling snel, en de kassa rustig.
Wat er allemaal in zit
Meer dan je verwacht. Vestigingen met hun werkplekken. Artikelgroepen als boom. Producten met een of meer artikelen, inclusief barcodes en prijzen. Voorraad per vestiging: de kassa houdt zelf voorraad bij, en een verkoop haalt die eraf. Toen we ons testartikel aan de kassa verkochten, ging de voorraad van 0 naar -1.
Verder de bonnen per dag, met btw per tarief en betaalwijze, en het dagjournaal: per dag en vestiging de omzet per omzetgroep, de betalingen per methode en de btw per tarief, met de grootboekrekening erbij. Dat laatste is precies wat een boekhouder per dag wil zien.
En het belangrijkste veld voor een koppeling: bij elk artikel kun je een eigen artikelcode opslaan. Bij onze klant staat daar de artikelcode uit Exact. Dat is de lijm tussen kassa en boekhouding.
Lezen in de app, schrijven apart getest
In de app van de klant kan de koppeling alleen operaties aanroepen die met "get" beginnen. Een test bewaakt dat, net zoals bij de schrijfacties naar de boekhouding, zie acht schrijfacties en geen negende.
Het schrijven (artikelen aanmaken, voorraad zetten, knoppen op het kassascherm wijzigen) hebben we op onze eigen testkassa uitgeprobeerd. Daar zitten een paar valkuilen in die een kassa echt kunnen laten haperen. Daarover schrijven we apart.
Veelgemaakte fouten
"De toegang regelen we wel als de koppeling af is." Dan wacht je project op een dealer en een kassa die online moet. Begin met de toegang.
"Prijzen lezen als euro's." Het zijn centen. Reken één keer om, aan de rand.
"Elke keer alles ophalen." Gebruik de syncMarkers. Een kassa met duizenden artikelen hoeft niet elk kwartier helemaal over de lijn.
"Een lijst is altijd een lijst." Niet bij één element. Normaliseer elk antwoord.
"Het adres met sleutel in de logboeken." De sleutel zit in de URL. Haal hem eruit voordat je iets logt of op een scherm zet.
Wat je met een gekoppelde kassa kunt, van voorraad tot kasboek, staat op MplusKASSA koppelen.