ATOL Online Online Cash Desk Service: API and CMS Integration
We reveal the general details of working with the online service of online cash registers, the nuances of integration with CMS and the pitfalls that you stumble upon if you don’t use ready-made solutions and will be engaged in the integration yourself.
According to 54-FZ, all trade and service platforms accepting payment via the Internet should go to online cash desks, sending real-time electronic checks to the FTS. From July 1, 2017, this requirement applies not only to online stores, but also to a wide variety of online services that collect payments from individuals using bank cards, and from July 1, 2018, changes will also affect those who use the services of alternative means of payment (online wallets) - Webmoney, Yandex, Money, etc.
')
Although the transition to the new cash registers had to take place, the FTS data suggest that the lion's share of the online trading and service platforms on the Internet has not yet legalized online payments to consumers. According to official statistics, about 14 thousand cash registers are registered with a sign of “payments on the Internet”, while the market segment, according to various sources, has at least 50 thousand enterprises (here we are talking only about companies that accept payments via the Internet from individuals).
Thus, more than half of the companies have not yet bothered with the fiscalization of settlements. Some online sites remain in the shadows, hoping that in the transition period they will not be interested in the FTS, while others, in order not to violate the law, simply turned off the reception of online payments.
We write a lot about how to do everything legally. Today we will talk about the details of the interaction of our cash desks within the framework of the ATOL Online service with the internal systems of online stores.
Buying an online ticket office is not a cheap event. An available alternative to buying is renting (“online booking as a service”). This service is what ATOL Online provides.
The idea of ​​the service is similar to SaaS, but in this case, due to the limitations of 54-, this is not about renting virtual capacities, but about temporary use of quite real (physical) cash desk located in our data center.
Under the contract, one or several cash desks are reserved for the client and are registered by him through the personal account of the taxpayer on the FTS website.
Although today there are alternative rental services, ATOL Online in 2017 was the first in this market segment. Currently, approximately every third cash desk registered with the Federal Tax Service for payments on the Internet is rented from ATOL.
The number of cash desks required for each specific store depends on the amount of information transmitted to the FTS - that is, in fact, on the number of orders processed per unit of time. The queue of documents at the cash desk is managed on the service side - they are evenly distributed among the available hardware resources. Recommendations and calculator for calculating the approximate number of units of equipment are on our website.
The service allows to evaluate the parameters of the queue from the documents at the cash desks (processing speed of each document), from which it is possible to draw conclusions about whether the number of cash desks was correctly calculated. The growth of the queue of the raw documents is a clear sign that the volume of leased resources should be increased.
Like the "classic" software rental services or infrastructure services, the service allows for flexible scaling of resources available to the end user. However, due to the registration requirements of each cash register in the Federal Tax Service for a particular company, the scaling procedure has some peculiarities.
In case of failure of excessive resources, the procedure is performed quickly. However, the FN archive used in the “extra cash” will have to be closed and the cash register itself deregistered (the unused cash desk will most likely be transferred to another client, and the FN, although it is valid for 13 months, is firmly assigned to the company and the physical cash desk - thus, with another cashier for expanding the fleet of leased vehicles at the expense of an arbitrary cash desk, it cannot be used).
With an increase in the number of cash registers, the procedure is slightly stretched in time. Since the subject of taxation is required to register with the FTS each cash desk independently (through a personal account at nalog.ru), the speed with which additional resources will be provided depends, among other things, on the store itself. In principle, it is possible to do it within a day.
Scaling opens up the possibility to flexibly vary the number of cash registers, predicting peak loads. Although this is only one of the options for work. Most of the stores prefer a different approach - to count the number of constantly rented cash desks, including the peak loads. Outside of the peaks, the equipment is not used to its full capacity, but this scheme provides greater fault tolerance.
In addition to the use of online cash registers, 54-FZ regulates the new parameters of the cash voucher - additional details and a mandatory reflection in the document of all commodity items with the corresponding tax rates. Regardless of whether the cash register was acquired by the company or leased, information on product positions and their total value (with all discounts and surcharges, along with the tax rate) must be received from the external system - from the CMS store or service platform . The subtleties of this process depend on the details of the task, but in the general case, ensuring the integration of the CMS and the online cash register, both in the presence and absence of the payment aggregator, is a technically non-trivial task.
From the very beginning, ATOL Online offered an open, universal API for interacting with third-party systems. With a number of popular CMS and payment aggregators, the service already has a ready-made integration out of the box (and the list of partners is constantly growing). That is, for a store that has just decided to align its activities with current legislation, this simplifies the procedure: if you use a popular CMS, you will not have to understand the details of the API, you can use a ready-made module. And buying a ready-made solution (CMS) from scratch or choosing a payment aggregator, you can pick up a tool with integration with the online cash register already implemented.
Integrated payment aggregators and banks: Sberbank, Yandex Cash, RoboKassa, RBKmoney, Raiffeisen Bank, Tinkoff, Gazprombank and others.
The API as such will be of interest to those who use handwriting tools. At one time, a number of companies (mostly large ones), instead of acquiring a third-party CMS system, chose the way of writing their own. They have to work with the API directly. From our point of view, this segment of users is the most difficult, since self-written CMS processes processes a little differently, can give out wrong information, etc. And with each client there is a separate project.
Let's try, without plunging into details, to tell what the ATOL Online API is.
Communication with the online cashier within the API consists of three parts:
In the course of interaction, only the parameters that are really needed for fiscalization of checks are required from the Internet site - no complicated additional systems, such as the calculation of discounts and promotions, are provided here. In strict accordance with the 54-FZ API, it is possible to transfer from the online store to the online cash desk a list of goods in the basket with all the related information:
Protocols exchange information online cash with CRF and the FTS provide for a limit on the total size of the electronic check in 30 KB. The number of goods that can be placed in such a check depends on a whole set of parameters (such as the length of the product name and service information, which adds about 15% of the volume), therefore, in general, it is impossible to forecast the number of goods that fit in one check.
Until recently, the ATOL Online API had its own limit of 100 items in a check, which allowed it to meet the prescribed 30 KB with a margin. But since the operation of the service showed that for some customers the restriction of 100 products plays a significant role, it was removed. Now the stores need to independently control the check overflow - that is, it is required to accept and process the corresponding error from ATOL online. This is especially true of shops where the buyer can collect a large number of small piece goods (fasteners, electronic components, etc.) into the basket, or platforms where collective purchases are popular (textbooks and office for the whole school class).
Technically, checks of more than 30 Kbytes in online trading are processed in the same way as in offline trading, where the cashier simply splits the basket into two checks. However, this logic must be on the side of the external system — i.e. the store, since ATOL Online can only give an error that fiscalization is not performed (by law, you can not pay two checks through a single transaction).
In addition to the above information through the API, the store must provide the user's phone or email where the electronic check will be sent.
By law, it is the online store that must ensure the delivery of the electronic check to the buyer, that is, his duty is to find out the delivery address (although, of course, the retailer will be liable if the user has provided deliberately incorrect data). Directly delivery, he can delegate the OFD or carry out independently. In the latter case, signs of a fiscal document are transferred back through the API after fiscalization, for which an electronic check can be found at the FTS or at the CRF.
The API delivers notifications that the document has been transferred for fiscalization - that is, it stood in a queue and went to the cashier - or, on the contrary, returned with an error, for example, by timeout (if the queue is too large and it is five minutes never got to the ticket office). The time that the average documents spend in the queue is a good marker of whether the bank has leased the store.
It should be noted that the ATOL Online service provides a wider functionality through a personal account. Various statistics are available there, as well as fiscalized checks themselves. Later similar functionality will appear in the API. In addition, it is planned to make a reconciliation mechanism.
Working with online cash registers in practice rests not so much on finding equipment and setting up interaction by API, but on changing some business processes inside the store.
The first step is to prepare for the transfer of the basket to the side for fiscalization. Until now, many stores work with payment systems, simply transferring the amount to be paid. It is impossible to continue working legally according to this scheme. It is necessary to specify the entire list of goods in the basket. And if the buyers in the sex shop will be happy to replace the names of real services with abstract “service 1”, “service 2” and so on, then consumers in the home appliance store will hardly be happy when nonsense appears in the check instead of real goods.
Each item in the check must have a final price after the application of all discounts and surcharges. Previously, the ticket office could itself calculate the discount, but now this can not be done. In addition, in many CMS this logic is simply not embedded, so serious improvements are required here.
In addition to the names and prices, as mentioned above, it is necessary to transfer the tax rate. With this, there were difficulties even with large offline stores. It was a real challenge for their internal automation system, since previously such information was not required or taken into account, and, accordingly, was not monitored. Sometimes the logistician who takes the goods, simply out of habit, left the tax rates by default, because I was used to working like that. But for the correct operation of the CMS bundle with the online cash register, it is necessary that the “correct” mathematics everywhere (corresponding to the 54- models) be laid everywhere. Without this, checks simply will not be fiscalized.
A good example of non-compliance with mat-models is rounding. The specification implies the transfer of kopecks in the form of two decimal places. But many of their own systems transmit four and even five characters. ATOL Online discards extra characters, while in the store’s own system, when calculating the total amount, it can be rounded off according to mathematical rules. This is how the discrepancy of a few kopecks appears, which will not pass through the checkout And such errors are very hard to catch.
Another mandatory change is the said requirement for a mobile phone number or email address with the user. Without this data there will be no fiscalization. Until now, quite a lot of checks without identification data have been received in our system (their share reaches a few percent). After sending such an “anonymous” check, the online store receives an error message, but cannot do anything, because the transaction has already passed. In this case, everything “cleanly” can be done only through cancellation of the payment transaction (or the check can be sent later - with the correct details).
As a result, the cost of the integration of the CMS and the online cash registers may be much less than the restructuring of the entire information system to the requirements of the federal law. And this must be prepared.
According to 54-FZ, all trade and service platforms accepting payment via the Internet should go to online cash desks, sending real-time electronic checks to the FTS. From July 1, 2017, this requirement applies not only to online stores, but also to a wide variety of online services that collect payments from individuals using bank cards, and from July 1, 2018, changes will also affect those who use the services of alternative means of payment (online wallets) - Webmoney, Yandex, Money, etc.
')
Although the transition to the new cash registers had to take place, the FTS data suggest that the lion's share of the online trading and service platforms on the Internet has not yet legalized online payments to consumers. According to official statistics, about 14 thousand cash registers are registered with a sign of “payments on the Internet”, while the market segment, according to various sources, has at least 50 thousand enterprises (here we are talking only about companies that accept payments via the Internet from individuals).
Thus, more than half of the companies have not yet bothered with the fiscalization of settlements. Some online sites remain in the shadows, hoping that in the transition period they will not be interested in the FTS, while others, in order not to violate the law, simply turned off the reception of online payments.
We write a lot about how to do everything legally. Today we will talk about the details of the interaction of our cash desks within the framework of the ATOL Online service with the internal systems of online stores.
Briefly about the service
Buying an online ticket office is not a cheap event. An available alternative to buying is renting (“online booking as a service”). This service is what ATOL Online provides.
The idea of ​​the service is similar to SaaS, but in this case, due to the limitations of 54-, this is not about renting virtual capacities, but about temporary use of quite real (physical) cash desk located in our data center.
Under the contract, one or several cash desks are reserved for the client and are registered by him through the personal account of the taxpayer on the FTS website.
Although today there are alternative rental services, ATOL Online in 2017 was the first in this market segment. Currently, approximately every third cash desk registered with the Federal Tax Service for payments on the Internet is rented from ATOL.
The number of cash desks required for each specific store depends on the amount of information transmitted to the FTS - that is, in fact, on the number of orders processed per unit of time. The queue of documents at the cash desk is managed on the service side - they are evenly distributed among the available hardware resources. Recommendations and calculator for calculating the approximate number of units of equipment are on our website.
The service allows to evaluate the parameters of the queue from the documents at the cash desks (processing speed of each document), from which it is possible to draw conclusions about whether the number of cash desks was correctly calculated. The growth of the queue of the raw documents is a clear sign that the volume of leased resources should be increased.
Like the "classic" software rental services or infrastructure services, the service allows for flexible scaling of resources available to the end user. However, due to the registration requirements of each cash register in the Federal Tax Service for a particular company, the scaling procedure has some peculiarities.
In case of failure of excessive resources, the procedure is performed quickly. However, the FN archive used in the “extra cash” will have to be closed and the cash register itself deregistered (the unused cash desk will most likely be transferred to another client, and the FN, although it is valid for 13 months, is firmly assigned to the company and the physical cash desk - thus, with another cashier for expanding the fleet of leased vehicles at the expense of an arbitrary cash desk, it cannot be used).
With an increase in the number of cash registers, the procedure is slightly stretched in time. Since the subject of taxation is required to register with the FTS each cash desk independently (through a personal account at nalog.ru), the speed with which additional resources will be provided depends, among other things, on the store itself. In principle, it is possible to do it within a day.
Scaling opens up the possibility to flexibly vary the number of cash registers, predicting peak loads. Although this is only one of the options for work. Most of the stores prefer a different approach - to count the number of constantly rented cash desks, including the peak loads. Outside of the peaks, the equipment is not used to its full capacity, but this scheme provides greater fault tolerance.
Why and who needs API
In addition to the use of online cash registers, 54-FZ regulates the new parameters of the cash voucher - additional details and a mandatory reflection in the document of all commodity items with the corresponding tax rates. Regardless of whether the cash register was acquired by the company or leased, information on product positions and their total value (with all discounts and surcharges, along with the tax rate) must be received from the external system - from the CMS store or service platform . The subtleties of this process depend on the details of the task, but in the general case, ensuring the integration of the CMS and the online cash register, both in the presence and absence of the payment aggregator, is a technically non-trivial task.
From the very beginning, ATOL Online offered an open, universal API for interacting with third-party systems. With a number of popular CMS and payment aggregators, the service already has a ready-made integration out of the box (and the list of partners is constantly growing). That is, for a store that has just decided to align its activities with current legislation, this simplifies the procedure: if you use a popular CMS, you will not have to understand the details of the API, you can use a ready-made module. And buying a ready-made solution (CMS) from scratch or choosing a payment aggregator, you can pick up a tool with integration with the online cash register already implemented.
Integrated payment aggregators and banks: Sberbank, Yandex Cash, RoboKassa, RBKmoney, Raiffeisen Bank, Tinkoff, Gazprombank and others.
The API as such will be of interest to those who use handwriting tools. At one time, a number of companies (mostly large ones), instead of acquiring a third-party CMS system, chose the way of writing their own. They have to work with the API directly. From our point of view, this segment of users is the most difficult, since self-written CMS processes processes a little differently, can give out wrong information, etc. And with each client there is a separate project.
API details
Let's try, without plunging into details, to tell what the ATOL Online API is.
Communication with the online cashier within the API consists of three parts:
- authorization (getting a token);
- sending checks for fiscalization;
- obtaining the result of fiscalization.
In the course of interaction, only the parameters that are really needed for fiscalization of checks are required from the Internet site - no complicated additional systems, such as the calculation of discounts and promotions, are provided here. In strict accordance with the 54-FZ API, it is possible to transfer from the online store to the online cash desk a list of goods in the basket with all the related information:
- the names of commodity items are within 128 characters according to the law (at the moment, the API has a length of 64 characters, but the service will process 128 characters);
- price per unit;
- the number of units (for each commodity item);
- full price;
- tax rate for each item (if you wish, you can transfer the amount of VAT, but this is not necessary).
Protocols exchange information online cash with CRF and the FTS provide for a limit on the total size of the electronic check in 30 KB. The number of goods that can be placed in such a check depends on a whole set of parameters (such as the length of the product name and service information, which adds about 15% of the volume), therefore, in general, it is impossible to forecast the number of goods that fit in one check.
Until recently, the ATOL Online API had its own limit of 100 items in a check, which allowed it to meet the prescribed 30 KB with a margin. But since the operation of the service showed that for some customers the restriction of 100 products plays a significant role, it was removed. Now the stores need to independently control the check overflow - that is, it is required to accept and process the corresponding error from ATOL online. This is especially true of shops where the buyer can collect a large number of small piece goods (fasteners, electronic components, etc.) into the basket, or platforms where collective purchases are popular (textbooks and office for the whole school class).
Technically, checks of more than 30 Kbytes in online trading are processed in the same way as in offline trading, where the cashier simply splits the basket into two checks. However, this logic must be on the side of the external system — i.e. the store, since ATOL Online can only give an error that fiscalization is not performed (by law, you can not pay two checks through a single transaction).
In addition to the above information through the API, the store must provide the user's phone or email where the electronic check will be sent.
By law, it is the online store that must ensure the delivery of the electronic check to the buyer, that is, his duty is to find out the delivery address (although, of course, the retailer will be liable if the user has provided deliberately incorrect data). Directly delivery, he can delegate the OFD or carry out independently. In the latter case, signs of a fiscal document are transferred back through the API after fiscalization, for which an electronic check can be found at the FTS or at the CRF.
The API delivers notifications that the document has been transferred for fiscalization - that is, it stood in a queue and went to the cashier - or, on the contrary, returned with an error, for example, by timeout (if the queue is too large and it is five minutes never got to the ticket office). The time that the average documents spend in the queue is a good marker of whether the bank has leased the store.
It should be noted that the ATOL Online service provides a wider functionality through a personal account. Various statistics are available there, as well as fiscalized checks themselves. Later similar functionality will appear in the API. In addition, it is planned to make a reconciliation mechanism.
What does an online store need besides API
Working with online cash registers in practice rests not so much on finding equipment and setting up interaction by API, but on changing some business processes inside the store.
The first step is to prepare for the transfer of the basket to the side for fiscalization. Until now, many stores work with payment systems, simply transferring the amount to be paid. It is impossible to continue working legally according to this scheme. It is necessary to specify the entire list of goods in the basket. And if the buyers in the sex shop will be happy to replace the names of real services with abstract “service 1”, “service 2” and so on, then consumers in the home appliance store will hardly be happy when nonsense appears in the check instead of real goods.
Each item in the check must have a final price after the application of all discounts and surcharges. Previously, the ticket office could itself calculate the discount, but now this can not be done. In addition, in many CMS this logic is simply not embedded, so serious improvements are required here.
In addition to the names and prices, as mentioned above, it is necessary to transfer the tax rate. With this, there were difficulties even with large offline stores. It was a real challenge for their internal automation system, since previously such information was not required or taken into account, and, accordingly, was not monitored. Sometimes the logistician who takes the goods, simply out of habit, left the tax rates by default, because I was used to working like that. But for the correct operation of the CMS bundle with the online cash register, it is necessary that the “correct” mathematics everywhere (corresponding to the 54- models) be laid everywhere. Without this, checks simply will not be fiscalized.
A good example of non-compliance with mat-models is rounding. The specification implies the transfer of kopecks in the form of two decimal places. But many of their own systems transmit four and even five characters. ATOL Online discards extra characters, while in the store’s own system, when calculating the total amount, it can be rounded off according to mathematical rules. This is how the discrepancy of a few kopecks appears, which will not pass through the checkout And such errors are very hard to catch.
Another mandatory change is the said requirement for a mobile phone number or email address with the user. Without this data there will be no fiscalization. Until now, quite a lot of checks without identification data have been received in our system (their share reaches a few percent). After sending such an “anonymous” check, the online store receives an error message, but cannot do anything, because the transaction has already passed. In this case, everything “cleanly” can be done only through cancellation of the payment transaction (or the check can be sent later - with the correct details).
As a result, the cost of the integration of the CMS and the online cash registers may be much less than the restructuring of the entire information system to the requirements of the federal law. And this must be prepared.
Source: https://habr.com/ru/post/344634/
All Articles