Can you get from our till what was sold per item this week, and lay that
next to the stock in the accounting?
The till is where a shop or restaurant makes its real figures. What was sold, with which VAT, paid by card or cash. If you want to tie the till to the accounting or the stock, you have to get into the till.
For a client with a shop that runs on MplusKASSA, we took a developer account with Mplus and tested the API from front to back for a week on a test till of our own. In the client's app the integration only reads. Everything that writes, we tested separately on our own test till, not on the client's. The client stays anonymous and there are no amounts, prices or margins here.
Access: allow for a few days
A developer account gives you a partner page with an identifier, a secret key and a development database of your own with a till licence for two branches. The till software itself is a Windows program that you install alongside.
After that it did not work straight away. First the API gave a 503: the API server of an administration only comes online after the till software has been connected to that database once. Once that was done, we got "Credentials not accepted!" for a few days, with credentials that were correct. That was fixed on the Mplus side, and from then on everything worked.
For a real client, access to their own administration usually goes through their Mplus dealer. So plan time for that, and start on it before you start building.
SOAP, with 388 operations
The API is SOAP. The description has 388 operations, and in practice you use a handful. You do not need a heavy SOAP library for it: we build the message ourselves and read the response as plain XML. Mplus has a PHP example client of its own on GitHub, and it is useful to see what a message should look like.
One thing to watch: the identifier and the secret key go in the address of every call, not in a header. So if you log your calls, you also log your key. We always show and store the address without the key.
Numbers without a decimal point
Amounts come in cents. An item of € 2.09 is 209 in the API. Quantities come as a whole number with a separate field for the number of decimals: 530 with three decimals is 0.530.
That is fine, as long as you convert it once at the edge of your code and never again. It goes wrong when one part of your code calculates in cents and another in euros.
Another classic: a list with one element does not come back as a list, but as a single element. Two receipts is a list, one receipt is an object. Always turn every "one or more" in your code into a list, even if you think there are always more.
Fetch only what has changed
For items, relations, receipts, orders and invoices the till keeps a counter, the syncMarker. You ask, for example, for the products from a certain marker onwards, with a maximum per response. The highest marker in the response plus one is your next starting point.
That is the same pattern as for stock in Exact Online: fetch everything once, after that only the changes. It keeps your integration fast, and the till calm.
What is in there
More than you expect. Branches with their workstations. Item groups as a tree. Products with one or more items, including barcodes and prices. Stock per branch: the till keeps stock itself, and a sale takes it off. When we sold our test item at the till, the stock went from 0 to -1.
Further the receipts per day, with VAT per rate and payment method, and the daily journal: per day and branch the revenue per revenue group, the payments per method and the VAT per rate, with the ledger account alongside. That last one is exactly what an accountant wants to see per day.
And the most important field for an integration: for every item you can store an item code of your own. At our client that holds the item code from Exact. That is the glue between till and accounting.
Reading in the app, writing tested separately
In the client's app the integration can only call operations that start with "get". A test guards that, just like with the write actions to the accounting, see eight write actions and no ninth.
Writing (creating items, setting stock, changing buttons on the till screen) we tried out on our own test till. There are a few pitfalls in there that can really make a till stall. We will write about those separately.
Common mistakes
"We'll arrange access once the integration is finished." Then your project waits for a dealer and a till that has to be online. Start with access.
"Reading prices as euros." They are cents. Convert once, at the edge.
"Fetching everything every time." Use the syncMarkers. A till with thousands of items does not need to go over the line in full every quarter of an hour.
"A list is always a list." Not with one element. Normalise every response.
"The address with the key in the logs." The key is in the URL. Strip it out before you log anything or put it on a screen.
What you can do with a connected till, from stock to cash book, is on connecting MplusKASSA.