ATOL Online Ticket Service Online: API and CMS Integration
We reveal the general details of working with a network service of online cash desks, the nuances of integration with CMS and pitfalls that you will stumble about if you do not start using ready-made solutions and will do the integration yourself.
According to 54-FZ, all trading and service sites accepting payments via the Internet must go to online cash desks that send real-time electronic checks to the Federal Tax Service. 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 alternative payment methods (online purses) - Webmoney, Yandex.Money, etc.
Although the transition to new cash desks should have already taken place, the Federal Tax Service says that the lion's share of trading and service sites on the Internet has not yet legalized online payments with consumers. According to official statistics, about 14 thousand cash registers with the sign “Internet settlements” are registered, while the market segment, according to various sources, has at least 50 thousand enterprises (here we are talking only about those companies that accept payments via the Internet from individuals).
Thus, more than half of the companies have not yet taken care of the fiscalization of settlements. Some online sites remain in the background, hoping that during the transition period they will not be of interest to the Federal Tax Service, while others, in order not to violate the law, simply turned off the acceptance of online payments.
We write a lot about how to do everything legally. Today we’ll talk about the details of the interaction of our cash desks within the framework of the ATOL Online service with internal systems of online stores.
Buying online cash registers is not a cheap event. An affordable alternative to buying is rent (“online cashier as a service”). It is this service that ATOL Online provides.
The idea of the service is similar to SaaS, but in this case, due to the limitations of 54-FZ, this is not about renting virtual capacities, but about temporarily using a very real (physical) cash desk located in our data center.
Under the agreement, one or several cash desks are reserved for the client and registered by him through the personal account of the taxpayer on the website of the Federal Tax Service.
Although alternative rental services exist today, ATOL Online in 2017 was the first in this market segment. At the moment, approximately every third cash register registered with the Federal Tax Service for payments on the Internet is leased from ATOL.
The number of cash desks needed for each particular store depends on the volume of information transmitted to the Federal Tax Service - that is, in fact, on the number of orders processed per unit of time. The queue of documents for cash desks is managed on the service side - they are evenly distributed among the available hardware resources. Recommendations and a calculator for calculating the approximate number of pieces of equipment are on our website.
The service allows you to evaluate the queue parameters from documents at the ticket office (processing speed of each document), from which we can draw conclusions about whether the number of cash registers was calculated correctly. The growth in the queue of unprocessed documents is a clear sign that the volume of leased resources should be increased.
Like the “classic” software or infrastructure rental services, the service allows flexible scaling of resources available to the end user. However, due to the requirements for registering each cash desk in the Federal Tax Service for a particular company, the scaling procedure has some features.
In case of refusal of excess resources, the procedure is quick. However, the archive of the FN used in the “extra” cash register will have to be closed, and the cash register should be deregistered by the Federal Tax Service (an unused cash register will most likely be transferred to another client, and the financial tax, although it is valid for 13 months, is strictly assigned to the company and the physical cash register - thus, it cannot be used with another cash desk to expand the fleet of leased equipment at the expense of an arbitrary cash desk).
With an increase in the number of cash registers, the procedure stretches a little in time. Since the subject of taxation is required to register each checkout independently at the FTS (through a personal account on nalog.ru), the speed with which additional resources will be provided depends on the store itself. In principle, this can be done within 24 hours.
Scaling opens the possibility to flexibly vary the number of cash registers, predicting peak loads. Although this is only one of the options. Most stores prefer a different approach - to calculate the number of constantly rented cash desks, including peak loads. Outside the peaks, the equipment is not used to its full potential, but such a scheme provides greater fault tolerance.
In addition to the use of online cash registers, 54-ФЗ regulates the new parameters of a cash register receipt - additional details and mandatory reflection in the document of all commodity items with the corresponding tax rates. Regardless of whether the box office was acquired by the company or leased, information on the product items and their total value (with all discounts and surcharges, and at the same time with the tax rate) should come into it from an 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 CMS and the online cash register, both in the presence of a payment aggregator and without it, 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 ready-made integration out of the box (and the list of partners is constantly updated). That is, for a store that has just decided to bring its activities in line with current legislation, this simplifies the procedure: if you use the popular CMS, you will most likely not need to understand the details of the API, you can use the ready-made module. And buying from scratch a ready-made solution (CMS) or choosing a payment aggregator, you can choose a tool with already implemented integration with an online cashier.
Integrated Payment Aggregators and Banks:Sberbank, Yandex Cash, RoboKassa, RBKmoney, RaiffeisenBank, Tinkoff, Gazprombank and others.
The API itself will be of interest to those who use self-written tools. At one time, a number of companies (mostly large) 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 process processes a little differently, they can give out the wrong information, etc. And with each client there is a separate project.
Let’s try, without going 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 those parameters that are really necessary for check fiscalization are required from the online platform - no complicated additional systems, such as calculating discounts and promotions, are provided here. In strict accordance with 54-FZ, the API allows you to transfer from the online store to the online cash register a list of goods in the basket with all the related information:
The protocols for exchanging information at the online cash desk with the OFD and the Federal Tax Service provide for a limit on the total size of an electronic check of 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 name of the goods and service information adding about 15% of the volume), therefore, in the general case, it is impossible to make a forecast about the number of goods “placed” in one check.
Until recently, the ATOL Online API had its own restriction of 100 commodity 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, stores need to independently control the check overflow - that is, they need to accept and process the corresponding error from ATOL online. This is especially true of stores where the buyer can pick up a large number of small piece goods (fasteners, electronic components, etc.), or sites 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. store, because ATOL Online can only give an error that fiscalization has not been completed (by law, you cannot pay two checks in one transaction).
In addition to the above information through the API, the store must provide the phone or email of the user where the electronic check will be sent.
According to the law, it is the online store that must ensure the possibility of delivering an electronic check to the buyer, that is, it is his responsibility to find out the address for delivery (although, of course, the retailer will be liable if the user specified deliberately incorrect data). Directly, he can delegate the CRF or carry out independently. In the latter case, signs of a fiscal document are transmitted back through the API after fiscalization, by which an electronic check can be found at the Federal Tax Service or the OFD.
The API delivers notifications that the document was submitted for fiscalization - that is, it stood in line and went to the cashier - or, conversely, returned with an error, for example, by timeout (if the queue is too long and it takes five minutes never reached the box office). The average amount of time that documents spend in line is a good marker of whether the box office has rented enough stores.
It should be noted that the ATOL Online service provides wider functionality through a personal account. Various statistics are available there, as well as the fiscalized checks themselves. Later, similar functionality will appear in the API. In addition, it is proposed 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 as on changing some business processes inside the store.
First of all, it is necessary 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 no longer legal to continue working under such a scheme. You must specify the entire list of goods in the basket. And if customers in an intimate services store will be happy to replace the names of real services with the abstract “service 1”, “service 2”, and so on, then consumers in the household appliance store are unlikely to be happy when there is nothing in the check instead of real goods.
Each item on the check must have a final price after applying all the discounts and allowances. Previously, the cashier could calculate the discount herself, but now this cannot be done. In addition, in many CMS this logic is simply not incorporated, therefore, 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 in large offline stores. This was a real challenge for their internal automation system, since before such information was not required anywhere and was not taken into account, and, accordingly, was not controlled. Sometimes the logistician who accepts the goods simply out of habit left tax rates by default, because he was used to working like that. But for the correct operation of the CMS bundle with the online cashier, it is necessary that the “correct” math (corresponding to the 54-ФЗ models) be laid down 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 or even five characters. ATOL Online discards extra characters, while in the store’s own system, when calculating the total amount, rounding can be done according to mathematical rules. So a discrepancy of a few cents is shown, which will not go through the cash register. And such errors are very difficult to catch.
Another mandatory change is the aforementioned requirement of the user's mobile phone number or email address. Without this data, there will be no fiscalization. Until now, quite a lot of checks without identification data have arrived in our system (their share reaches units of percent). After sending such an “anonymous” check, the online store receives an error message, but can not do anything, because the transaction has already passed. In this case, everything is “clean” can only be done by canceling the payment transaction (or the check can be sent later with the correct details).
As a result, the costs of integrating CMS and online cash registers themselves can be much less than restructuring the entire information system to the requirements of federal law. And one must be prepared for this.
According to 54-FZ, all trading and service sites accepting payments via the Internet must go to online cash desks that send real-time electronic checks to the Federal Tax Service. 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 alternative payment methods (online purses) - Webmoney, Yandex.Money, etc.
Although the transition to new cash desks should have already taken place, the Federal Tax Service says that the lion's share of trading and service sites on the Internet has not yet legalized online payments with consumers. According to official statistics, about 14 thousand cash registers with the sign “Internet settlements” are registered, while the market segment, according to various sources, has at least 50 thousand enterprises (here we are talking only about those companies that accept payments via the Internet from individuals).
Thus, more than half of the companies have not yet taken care of the fiscalization of settlements. Some online sites remain in the background, hoping that during the transition period they will not be of interest to the Federal Tax Service, while others, in order not to violate the law, simply turned off the acceptance of online payments.
We write a lot about how to do everything legally. Today we’ll talk about the details of the interaction of our cash desks within the framework of the ATOL Online service with internal systems of online stores.
Briefly about the service
Buying online cash registers is not a cheap event. An affordable alternative to buying is rent (“online cashier as a service”). It is this service that ATOL Online provides.
The idea of the service is similar to SaaS, but in this case, due to the limitations of 54-FZ, this is not about renting virtual capacities, but about temporarily using a very real (physical) cash desk located in our data center.
Under the agreement, one or several cash desks are reserved for the client and registered by him through the personal account of the taxpayer on the website of the Federal Tax Service.
Although alternative rental services exist today, ATOL Online in 2017 was the first in this market segment. At the moment, approximately every third cash register registered with the Federal Tax Service for payments on the Internet is leased from ATOL.
The number of cash desks needed for each particular store depends on the volume of information transmitted to the Federal Tax Service - that is, in fact, on the number of orders processed per unit of time. The queue of documents for cash desks is managed on the service side - they are evenly distributed among the available hardware resources. Recommendations and a calculator for calculating the approximate number of pieces of equipment are on our website.
The service allows you to evaluate the queue parameters from documents at the ticket office (processing speed of each document), from which we can draw conclusions about whether the number of cash registers was calculated correctly. The growth in the queue of unprocessed documents is a clear sign that the volume of leased resources should be increased.
Like the “classic” software or infrastructure rental services, the service allows flexible scaling of resources available to the end user. However, due to the requirements for registering each cash desk in the Federal Tax Service for a particular company, the scaling procedure has some features.
In case of refusal of excess resources, the procedure is quick. However, the archive of the FN used in the “extra” cash register will have to be closed, and the cash register should be deregistered by the Federal Tax Service (an unused cash register will most likely be transferred to another client, and the financial tax, although it is valid for 13 months, is strictly assigned to the company and the physical cash register - thus, it cannot be used with another cash desk to expand the fleet of leased equipment at the expense of an arbitrary cash desk).
With an increase in the number of cash registers, the procedure stretches a little in time. Since the subject of taxation is required to register each checkout independently at the FTS (through a personal account on nalog.ru), the speed with which additional resources will be provided depends on the store itself. In principle, this can be done within 24 hours.
Scaling opens the possibility to flexibly vary the number of cash registers, predicting peak loads. Although this is only one of the options. Most stores prefer a different approach - to calculate the number of constantly rented cash desks, including peak loads. Outside the peaks, the equipment is not used to its full potential, but such a scheme provides greater fault tolerance.
Why and who needs an API
In addition to the use of online cash registers, 54-ФЗ regulates the new parameters of a cash register receipt - additional details and mandatory reflection in the document of all commodity items with the corresponding tax rates. Regardless of whether the box office was acquired by the company or leased, information on the product items and their total value (with all discounts and surcharges, and at the same time with the tax rate) should come into it from an 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 CMS and the online cash register, both in the presence of a payment aggregator and without it, 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 ready-made integration out of the box (and the list of partners is constantly updated). That is, for a store that has just decided to bring its activities in line with current legislation, this simplifies the procedure: if you use the popular CMS, you will most likely not need to understand the details of the API, you can use the ready-made module. And buying from scratch a ready-made solution (CMS) or choosing a payment aggregator, you can choose a tool with already implemented integration with an online cashier.
Integrated Payment Aggregators and Banks:Sberbank, Yandex Cash, RoboKassa, RBKmoney, RaiffeisenBank, Tinkoff, Gazprombank and others.
The API itself will be of interest to those who use self-written tools. At one time, a number of companies (mostly large) 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 process processes a little differently, they can give out the wrong information, etc. And with each client there is a separate project.
API Details
Let’s try, without going into details, to tell what the ATOL Online API is.
Communication with the online cashier within the API consists of three parts:
- authorization (receiving a token);
- sending a check for fiscalization;
- getting the result of fiscalization.
In the course of interaction, only those parameters that are really necessary for check fiscalization are required from the online platform - no complicated additional systems, such as calculating discounts and promotions, are provided here. In strict accordance with 54-FZ, the API allows you to transfer from the online store to the online cash register a list of goods in the basket with all the related information:
- names of commodity items - within 128 characters under the law (at the moment, the API has a name length of 64 characters, but the service will also process 128 characters);
- unit price;
- number of units (for each commodity item);
- full cost;
- tax rate for each commodity item (if you wish, you can transfer the amount of VAT, but this is not necessary).
The protocols for exchanging information at the online cash desk with the OFD and the Federal Tax Service provide for a limit on the total size of an electronic check of 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 name of the goods and service information adding about 15% of the volume), therefore, in the general case, it is impossible to make a forecast about the number of goods “placed” in one check.
Until recently, the ATOL Online API had its own restriction of 100 commodity 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, stores need to independently control the check overflow - that is, they need to accept and process the corresponding error from ATOL online. This is especially true of stores where the buyer can pick up a large number of small piece goods (fasteners, electronic components, etc.), or sites 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. store, because ATOL Online can only give an error that fiscalization has not been completed (by law, you cannot pay two checks in one transaction).
In addition to the above information through the API, the store must provide the phone or email of the user where the electronic check will be sent.
According to the law, it is the online store that must ensure the possibility of delivering an electronic check to the buyer, that is, it is his responsibility to find out the address for delivery (although, of course, the retailer will be liable if the user specified deliberately incorrect data). Directly, he can delegate the CRF or carry out independently. In the latter case, signs of a fiscal document are transmitted back through the API after fiscalization, by which an electronic check can be found at the Federal Tax Service or the OFD.
The API delivers notifications that the document was submitted for fiscalization - that is, it stood in line and went to the cashier - or, conversely, returned with an error, for example, by timeout (if the queue is too long and it takes five minutes never reached the box office). The average amount of time that documents spend in line is a good marker of whether the box office has rented enough stores.
It should be noted that the ATOL Online service provides wider functionality through a personal account. Various statistics are available there, as well as the fiscalized checks themselves. Later, similar functionality will appear in the API. In addition, it is proposed to make a reconciliation mechanism.
What an online store needs besides the API
Working with online cash registers in practice rests not so much on finding equipment and setting up interaction by API as on changing some business processes inside the store.
First of all, it is necessary 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 no longer legal to continue working under such a scheme. You must specify the entire list of goods in the basket. And if customers in an intimate services store will be happy to replace the names of real services with the abstract “service 1”, “service 2”, and so on, then consumers in the household appliance store are unlikely to be happy when there is nothing in the check instead of real goods.
Each item on the check must have a final price after applying all the discounts and allowances. Previously, the cashier could calculate the discount herself, but now this cannot be done. In addition, in many CMS this logic is simply not incorporated, therefore, 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 in large offline stores. This was a real challenge for their internal automation system, since before such information was not required anywhere and was not taken into account, and, accordingly, was not controlled. Sometimes the logistician who accepts the goods simply out of habit left tax rates by default, because he was used to working like that. But for the correct operation of the CMS bundle with the online cashier, it is necessary that the “correct” math (corresponding to the 54-ФЗ models) be laid down 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 or even five characters. ATOL Online discards extra characters, while in the store’s own system, when calculating the total amount, rounding can be done according to mathematical rules. So a discrepancy of a few cents is shown, which will not go through the cash register. And such errors are very difficult to catch.
Another mandatory change is the aforementioned requirement of the user's mobile phone number or email address. Without this data, there will be no fiscalization. Until now, quite a lot of checks without identification data have arrived in our system (their share reaches units of percent). After sending such an “anonymous” check, the online store receives an error message, but can not do anything, because the transaction has already passed. In this case, everything is “clean” can only be done by canceling the payment transaction (or the check can be sent later with the correct details).
As a result, the costs of integrating CMS and online cash registers themselves can be much less than restructuring the entire information system to the requirements of federal law. And one must be prepared for this.