Zet onze artikelen en knoppen via de API in de kassa en houd de prijzen
gelijk met wat er in de boekhouding staat.
Lezen uit een kassa is overzichtelijk: je vraagt wat er veranderd is en je krijgt het. Schrijven is een ander spel. Een kassa is een apparaat waar iemand over tien minuten een klant mee afrekent, en een API die netjes "gelukt" zegt, kan dat afrekenen ondertussen onmogelijk hebben gemaakt.
Wij hebben dat uitgezocht op onze eigen testkassa, een proefopstelling met demogegevens. Nooit op de kassa van een klant. Dit is wat we daar stukmaakten, en hoe je het voorkomt. Er staan hier geen bedragen, prijzen of marges.
Hoe we de API in de eerste week leerden kennen, staat in de MplusKASSA-API: wat we leerden.
1. Een lijst bijwerken die in zijn geheel wordt vervangen
De omzetgroepen van de kassa zijn bij te werken met één operatie. Die heet naar "bijwerken", en dat is misleidend. Hij vervangt de hele lijst door wat jij meestuurt.
Stuur je drie groepen omdat je er drie wil toevoegen, dan zijn alle andere groepen weg. Bij ons verdwenen er zeven in één aanroep. Het gevolg was niet een foutmelding maar iets veel ergers: afrekenen op de kassa faalde daarna. Artikelen hingen aan groepen die niet meer bestonden.
Herstellen ging door de volledige lijst opnieuw te sturen, inclusief de groepen die we nooit hadden willen aanraken. Dat kon alleen omdat we de oude lijst eerst hadden uitgelezen en bewaard.
De regel: lees de lijst, voeg je wijziging toe aan wat er al staat, stuur alles terug. En bewaar het antwoord van voor de wijziging, zodat terugdraaien één aanroep is.
2. Hetzelfde, maar dan met het hoofdscherm
De knoppenindeling van de kassa werkt precies zo. De operatie om een knoppengroep op te slaan verwacht de hele groep, met alle hoofdgroepen, tabbladen en knoppen erin.
Wil je één knop op één plek zetten, dan lees je eerst de hele indeling voor die vestiging en kassa uit, zet je jouw knop op zijn plek in dat bouwwerk en stuur je het geheel terug. Vergeet je de helft, dan is die helft verdwenen van het scherm waar iemand mee werkt.
Dit is de pijnlijkste van de vijf, want je ziet het niet in een foutmelding. Je ziet het pas als iemand voor de kassa staat en een tabblad leeg is.
3. Een product bijwerken dat alles wil hebben
Een product bijwerken vraagt niet het veld dat je wil veranderen, maar het hele product. Je leest het uit, je past één ding aan, je stuurt alles terug.
Daar zit een val in. In de productgegevens kan een lijst met eigen velden staan. Komt die lijst leeg of halfgevuld terug mee, dan weigert de kassa het product. Wij moesten dat ene lege veld uit de gegevens halen voordat het bijwerken lukte.
De regel: sturen wat je las is niet genoeg. Strip de velden die leeg terugkomen voordat je ze weer aanbiedt.
4. Verwijderen bestaat niet, en groepen komen apart
Twee dingen die je verwacht en die er niet zijn.
Er is geen operatie om een product te verwijderen. Je zet het op inactief. Dat is logisch voor een kassa, want een verwijderd artikel zou de bonnen van vorig jaar onleesbaar maken, maar het betekent dat een misgelopen testronde zichtbaar in de lijst blijft staan. Ruim je eigen proefartikelen dus bewust op.
En bij het aanmaken van een product kun je artikelgroepen meesturen. Die worden genegeerd. Zonder foutmelding. Het product wordt aangemaakt, de groep blijft leeg, en je artikel staat nergens op het scherm. Een product in een groep zetten gaat met een eigen operatie, achteraf.
5. Een koppeling die wordt geaccepteerd maar niet bewaard
Dit was de leerzaamste. Bij een artikel kun je een lijst met gekoppelde artikelen meegeven, bijvoorbeeld om statiegeld automatisch mee te laten rekenen bij een blikje.
Het aanmaken slikt die lijst. Het bijwerken ook. Geen foutmelding, geen waarschuwing. Maar vraag het product daarna op en de lijst is er niet. En belangrijker: reken op de kassa een paar van die artikelen af, en op de bon staat geen statiegeld. De kassa heeft de koppeling nooit opgeslagen.
Wij kwamen daar alleen achter door echt af te rekenen en naar de bon te kijken. Een test die alleen controleert of de aanroep gelukt is, zou hier groen blijven.
De regel: controleer na elke schrijfactie wat de kassa ervan bewaard heeft, door het terug te lezen. En controleer bij alles wat de bon raakt de bon zelf.
En dan nog de kassa die niets meer doet
Nog een les van diezelfde avond, zijdelings: na het herstellen van de omzetgroepen bleef afrekenen falen, met een melding over een onbekend webadres. De oorzaak was een webhook die op de kassa stond ingesteld, met blokkerende gebeurtenissen en een adres dat nergens heen wees. Daarover schreven we apart in een webhook die je kassa kan blokkeren.
Dat hoort in dit rijtje omdat het dezelfde vorm heeft: de instelling zelf is geldig, de gevolgen staan ergens anders.
Veelgemaakte fouten
Een "bijwerken" vertrouwen zonder te weten of hij vervangt. Lees eerst, stuur dan alles terug. Bij lijsten is dat het verschil tussen een wijziging en een leegruiming.
Testen op een kassa die iemand gebruikt. Vraag een proefopstelling aan en maak daar je fouten. Een kassa die niet afrekent, is geen gewone storing.
Alleen controleren of de aanroep gelukt is. Lees terug wat er bewaard is. Een geaccepteerd veld is niet hetzelfde als een opgeslagen veld.
Geen kopie van de oude toestand bewaren. Sla uit wat je gaat overschrijven op, voordat je schrijft. Herstellen is dan één stap.
Eén script alles in één keer laten doen. Bouw het op in stappen die je apart kunt terugdraaien, en kijk tussendoor op het scherm van de kassa.
Wat een gekoppelde kassa kan, staat op MplusKASSA koppelen. Wil je zoiets voor je eigen winkel of horeca, kijk dan op maatwerk.