Let the accounting know right away what was sold at the till, not only at
the end of the week.
At a client with a shop, till sales now go to the accounting once a week: an export from the till becomes a transfer from the wholesale warehouse to the shop warehouse. That works, but it means the stock in the accounting lags behind by up to six days.
The next step is per receipt. MplusKASSA can ring the bell itself for this with a webhook: after every sale the till sends a message to an address that you give. We built a receiver and connected our own test till to it. This is what comes in, and what to watch out for. Everything below was tested on our test till, not on the client's.
What the till sends
You set up webhooks in the Mplus back office, under Beheer > Instellingen > Webhooks (management > settings > webhooks): an address, a secret key, the events you want to hear and whether the till has to wait for your response. Through the API you can only read them out, not create or change them.
The event you want for stock and accounting is called completeSession: a receipt has been paid. Mplus appends the name of the event to your address, so /hook becomes /hook/completeSession.
With us the message arrived within a second of checkout. It is JSON, with three parts:
- event: whether the till waits for your response, a sequence number and a timestamp.
- sender: which branch, which till, which employee and which version of the till software.
- session: the receipt, with totals including and excluding VAT, the payments per method and all lines.
Per line you get the item number, your own item code, the barcode, the quantity, the price with and without VAT, the discount, the revenue group and the VAT percentage. That own item code is the key: at our client it holds the item code from the accounting. With it you know per line which item in the accounting has less in stock.
Note: a field that is empty is simply missing. An item without an own code or barcode does not have those fields in the message. Your code has to cope with that.
Signed, and you sign back
Every call has a signature in the X-Mplus-Signature header: an HMAC-SHA256 over the raw body, with the secret key. If the signature is right, you know the message comes from your till and was not changed on the way. You sign your response in the same way.
With us the signature was right on every call. How you check it, with code in PHP and Python, is in setting up a MplusKASSA webhook.
Blocking or not
Here is the pitfall. A webhook is non-blocking or blocking.
With non-blocking, the till just carries on and your receiver hears afterwards what happened. With blocking, the till waits for your response. That has an advantage: your response can change something at the till. With completeSession, for example, you can return a text that appears at the bottom of the receipt.
The downside we found out the hard way. On our test till there was still a webhook from the example setup, blocking, with the address literally "todo". From that moment checkout no longer worked. The till reported: "het webadres is onbekend (C6)" ("the web address is unknown"). Only when that webhook was off did checkout work again.
A blocking webhook is therefore a dependency of your till. If your server is down, your certificate has expired or your code is slow, a customer is standing at the counter waiting.
Our rules:
- Non-blocking by default. Only blocking if your response to the till really adds something.
- Always answer quickly. The receiver stores the message and answers at once. The processing (updating stock, booking) happens afterwards, separate from the till.
- Never punish the till for your problem. Even with a wrong signature our receiver answers properly. The message is then not processed, but the till does not notice.
What you can do with it
The obvious use: update the stock in the accounting per receipt instead of per week. At our client that is the next step.
There is more, as a possibility: a revenue overview per hour that updates itself, a notification when an item is almost out, or a signal for a barcode the till does not know. The message contains everything needed for that.
Common mistakes
A blocking webhook for something that can also happen later. Updating stock can happen a second later. Do not make the till wait for it.
Processing first, answering after. Store, answer, and process afterwards. Heavy work before the response makes your till slow.
Processing a message with a wrong signature anyway. Then anyone who knows your address can book stock out of your accounting.
Assuming every field is there. Empty fields are missing. An item without an own code should go on a list for a person, not bring your whole processing to a halt.
Processing a receipt twice. Store the ID per receipt and skip a receipt you already know. Then it does not matter if a message ever arrives twice.
More about what a connected till can do is on connecting MplusKASSA. How we got to know the API itself, you can read in the MplusKASSA API: what we learned in the first week.