I will give an example of setting up a software PPO Checkbox in the ABillS billing system.
The purchased Checkbox.pm module must be copied to the /usr/abills/Abills/modules/Extreceipt/API/ folder and install the Extreceipt module:
cp Extreceipt.pm /usr/abills/Abills/modules/Extreceipt/db/
mysql --default-character-set=utf8 -D abills < /usr/abills/Abills/modules/Extreceipt/Extreceipt.sql
ln -s /usr/abills/Abills/modules/Extreceipt/extreceipt_payments_reg.pm /usr/abills/libexec/billd.plugins/extreceipt_payments_reg.pm
First, you need to register an organization in the Checkbox, if there are several of them, then you need to register in different accounts with different emails.
Then you need to add outlets using the EDS key, we indicated the type of outlet as “Settlement center”, after adding the form 20-OPP went to the tax office for confirmation, which lasted about 10 minutes.
Add cash registers using the EDS key, cash desks were also confirmed in the tax office for about 10 minutes (form 1-PRRO sent).
Add cashiers, first specify the EDS key of the cashier (individual) and then confirm the EDS with the director’s key, after that, the form 5-PRRO will be sent to the tax office. The director can also work as a cashier (as they answered in Checkbox support), that is, the director can be added as one cashier. If the director’s key has just been generated, then with its help it will be possible to add a cashier in about 1-2 days or you can make a report in private24 to speed up, otherwise there will be an error: “Invalid signature – the certificate is daily in the register of registered certificates”. The new generated key of the director should appear in the DFS office cabinet.tax.gov.ua.
When the cashier becomes active after confirming the DFS, it is also necessary to upload his key to the Checkbox server (by clicking on the right opposite the cashier …), otherwise, when opening the shift through the API, there will be an error: “CheckBox Signature inactive, please run it”.
If several outlets are used, then for each outlet it is necessary to add a cash desk and at least one cashier for each cash desk. One cashier cannot work at several cash desks at the same time (this is how Checkbox support answered). All outlets must be added, since the address of the outlet is displayed on the receipt.
If you wish, you can write to the Checkbox support telegram to add the FOP before the full name.
In billing, I had to add several types of payments in the menu Settings>Other>Type of payment. If earlier, for example, there were types of payments: Subscription fee, Connection, Connection (terminal), then I had to rename them by adding the name of the point and add a few more, for example:
Subscription fee (point 1)
Subscription fee (point 2)
Subscription fee (point 3)
Subscription fee terminal (point 1)
Subscription fee terminal (point 2)
Subscription fee terminal (point 3)
Connection terminal (point 1)
Connection terminal (point 2)
Connection terminal (point 3)
You can edit the template so that the Wage type field is empty and required by default, for example, to force operators to select a wage type and not accidentally add a payment with a default wage type.
In the Settings>Checks>API menu, I specified:
Name: Checkbox_TOV_ixnfo_com
API plugin: Checkbox
Login: specified cashier login
Password: Specified cashier password
URL: https://api.checkbox.ua/api/v1/
Item: Internet Services
And thus we add an API for each outlet, for example, I added 3 points + 1 test point for test payments.
In the menu Settings>Checks>KKT I indicated:
API: chose Checkbox_TOV_ixnfo_com
KKT License: specified cash register license key
Check Header: tel.: 12345, 123 \n Cashier: Ivanov I.
Receipt Desc: Internet Payment, Customer &UID& \n &FIO& \n &ADDRESS_DISTRICT&, &ADDRESS_STREET&, &ADDRESS_BUILD&, &ADDRESS_FLAT& \n
Payment type: ‘0’,3,11
Administrator: chose administrators who accept payments
For example, there are three cash desks, there are three types of payment, it turns out 3*3=9 added cash registers + 1 for test payments. For test payments, I specified the Bonus payment type, since it was not used.
IDs of some of my payment types:
0 – Subscription fee (point 1)
3 – Subscription fee terminal (point 1)
11 – Connection terminal (point 1)
Accordingly, 0 should be added to the checkbox as Cash, and 3 and 11 as a Card, for this I specified in the config.pl configuration:
$conf{CHECKBOX_CARD_PAYMENT}='3, 11';
For official cash withdrawal, the chief cashier logged into the Checkbox, clicked the “Sales” menu, logged in as a cashier and clicked “View preparation”, at the end of the shift in the same menu, clicked to end the shift and printed a Z-report, in the same menu you can print X- report and open a shift, but billing opened it for me, for this I specified in /etc/crontab:
0 22 * * * root /usr/abills/libexec/billd extreceipt_payments_reg CLOSE_SHIFT=1
0 7 * * * root /usr/abills/libexec/billd extreceipt_payments_reg OPEN_SHIFT=1
That is, he opens all shifts at 7 in the morning, and closes at 22:00, well, he closed the test shifts mainly, since the cashiers themselves closed the working shifts.
An example of crontab jobs for automatically opening and closing shifts from Monday to Saturday, except Sunday:
0 22 * * 1 root /usr/abills/libexec/billd extreceipt_payments_reg CLOSE_SHIFT=1
0 7 * * 1 root /usr/abills/libexec/billd extreceipt_payments_reg OPEN_SHIFT=1
0 22 * * 2 root /usr/abills/libexec/billd extreceipt_payments_reg CLOSE_SHIFT=1
0 7 * * 2 root /usr/abills/libexec/billd extreceipt_payments_reg OPEN_SHIFT=1
0 22 * * 3 root /usr/abills/libexec/billd extreceipt_payments_reg CLOSE_SHIFT=1
0 7 * * 3 root /usr/abills/libexec/billd extreceipt_payments_reg OPEN_SHIFT=1
0 22 * * 4 root /usr/abills/libexec/billd extreceipt_payments_reg CLOSE_SHIFT=1
0 7 * * 4 root /usr/abills/libexec/billd extreceipt_payments_reg OPEN_SHIFT=1
0 22 * * 5 root /usr/abills/libexec/billd extreceipt_payments_reg CLOSE_SHIFT=1
0 7 * * 5 root /usr/abills/libexec/billd extreceipt_payments_reg OPEN_SHIFT=1
0 22 * * 6 root /usr/abills/libexec/billd extreceipt_payments_reg CLOSE_SHIFT=1
0 7 * * 6 root /usr/abills/libexec/billd extreceipt_payments_reg OPEN_SHIFT=1
You can also use another team (but if there are several cash registers or companies, then there may be a problem – closed shifts will open, and open ones will close, so it’s better with teams as shown above):
0 1 * * * /usr/abills/libexec/billd extreceipt_payments_reg RENEW_SHIFT=1
For debugging, you can start it manually by adding DEBUG at the end of the command:
/usr/abills/libexec/billd extreceipt_payments_reg OPEN_SHIFT=1 DEBUG=2
If billing was without the Internet, for example, and payments were accepted, then in order not to send them one by one in the Service>Checks>Checks menu, you can send all the unsent ones at once to the Checkbox with the command:
/usr/abills/libexec/billd extreceipt_payments_reg
In the database, unsent checks can be viewed with the following SQL query, and for example, add to Zabbix monitoring to find out when an unsent check appears:
SELECT * FROM extreceipts where status=0
UserParameter=extreceipts_not_sent,mysql --defaults-extra-file=/etc/zabbix/.mysql.cnf -D abills -e "SELECT count(*) FROM extreceipts where status=0;" -s -N
Once there was a bug when adding kkt, and in order not to wait until technical support fixes it, I added via SQL queries:
INSERT INTO extreceipts_kkt (kkt_id, api_id, shift_uuid, kkt_group, kkt_key, methods, groups, admins, aid, check_header, check_desc, check_footer) VALUES ('', 5, 0, '', 'ixnfo.com', 4, '', '', 14, 'tel.: 000', 'CCB services, User &UID& \\n &FIO& \\n &ADDRESS_DISTRICT&, &ADDRESS_STREET&, &ADDRESS_BUILD&, &ADDRESS_FLAT& \\n', '');
INSERT INTO extreceipts_kkt (kkt_id, api_id, shift_uuid, kkt_group, kkt_key, methods, groups, admins, aid, check_header, check_desc, check_footer) VALUES ('', 6, 0, '', 'ixnfo.com', 4, '', '', 14, 'tel.: 000', 'CCB services, User &UID& \\n &FIO& \\n &ADDRESS_DISTRICT&, &ADDRESS_STREET&, &ADDRESS_BUILD&, &ADDRESS_FLAT& \\n', '');
Once, the Checkbox had delays, due to which, when adding a payment, the check image was not displayed, it appeared later, after 1 minute, for example, that is, the check went through, was fiscalized, it received the DONE status, but the check image was not displayed. To diagnose this problem, I asked the ABillS developers to add request logs and their duration, which can be found here /usr/abills/var/log/extreceipt.log.
When I needed to change the URL to the API, and I have more than 10 of them, I would execute the following request:
SELECT * FROM extreceipts_api LIMIT 200;
UPDATE extreceipts_api SET url="https://api.checkbox.ua/api/v1/" WHERE url="https://api.checkbox.in.ua/api/v1/";
See also my other articles about ABillS