Frequently Asked Questions
this section is being revised and adapted for the certified version 2 of the the fiskaly Cloud-TSS!
API
Which version of the API should I use?
Use version 2. We recommend always starting with the newest released version.
What is the path for the different API versions?
For the current version 2, the path is /api/v2. For the older version 1 API, the path is /api/v1. The minor and patch levels of the version are not represented in the path as they are backwards-compatible.
Does authentication have to be performed for each process?
A valid access token must be passed each time the API is called. This does not mean that the auth endpoint must be contacted again and again before each request. However, the access token should be refreshed with the refresh token before it expires (see authenticate). The clients provided by us (see https://github.com/fiskaly) have already implemented the Authentication and Refresh Methods.
Is an active transaction automatically set to 'state=cancelled' if it has not been updated for X seconds/minutes?
The automatic termination of a transaction is currently not clearly defined in the Technical Guidelines or in the SMAERS protection profile, which is why this mechanism is not yet in effect.
I have the following error with the line items "FST_ERR_CTP_INVALID_CONTENT_LENGTH: Request body size did not match Content-Length".
The request body does not seem to be UTF-8 encoded (see "General Accessory). If the passed JSON string is correctly encoded, the problem should be solved.
TSS
How often do major updates happen? When will I be informed that changes may be necessary?
It is not foreseeable how often major updates will be necessary. We will do everything we can to ensure that there will never be a major update, but of course we can't rule this out. If major updates become necessary, there will be a transition period where both the old and the new API will be available in parallel. So it should be sufficient for the manufacturer to prepare for the upgrade and to distribute updates of the POS software.
What information comes from the TSS and what does the cash register system have to determine apart from the pure sales data (article, payment type, VAT), e.g. start and end time of the transaction?
Information on the start and end time comes from the cloud (start of the first transaction for the business case, can also differ greatly from the time of the cash receipt).
What is the difference between a local TSS connected to the POS, and the cloud TSS?
The difference lies only in the architecture. For a local solution, the TSS must be installed on-site. There are many advantages with the cloud TSS: there is no hardware rollout, since everything is software-based; maintenance does not have to be carried out on-site, but instead is controlled centrally; you always have access to your data; and much more...
The TSS/TSE consists of CSP and SMA and can be located in the cloud or on a local device such as a USB stick. Is this correct?
Correct! The following answer is given on the BSI FAQ page: : 'A technical implementation can take place in different ways, e.g. locally (e.g. via smartcard) or remotely (as a "cloud" solution), as long as the necessary security and interoperability requirements of the BSI are met and proven within the framework of certification. In principle, a remotely connected TSS must be accessible to all connected electronic recording systems.'
What is the CSP?
The CSP (Crypto Service Provider) is a CC-certified component that generates the signatures of the data to be secured. In the fiskaly cloud, the CSP is a HSM (Harware Security Module) specially adapted for the KassenSichV, which is developed and certified by our partner.
What is the difference between 'SMA' and 'SMAERS'?
The SMA (Security Module Application) is a CC-certified component that prepares the data to be secured within a transaction. The SMA communicates directly with the CSP (Crypto Service Provider) to sign the data to be secured. SMAERS is the name of the protection profile to be applied to the SMA.
How many TSS do I need in production?
Generally, you only need one TSS. It is capable of managing multiple cash register clients.
If I disable a TSS, are all the relative Clients disabled?
Disabling means that the clients can no longer use the TSS for the creation of log messages, so indirectly this disables the clients of this TSS as well.
What fields are logged by the TSS?
Visit the SIGN DE API Docs for further details.
Is a PIN still required to create a TSS if we use our own HTTP client (from our backend)?
No, creating a TSS doesn't require a PIN: https://developer.fiskaly.com/api/kassensichv/v2/#operation/createTss This is because the PIN (and also the PUK) is a property of a particular TSS, and prior to the creation of a TSS, neither the PIN nor the PUK exist.
Is the connection of the cloud only possible via Java-Connector/Java-SMAERS or also in C?
The SMAERS component is available as a C library, but a full client implementation would need to be ordered separately. A list of our client implementations is available as open source at github.com/fiskaly.
What error messages does the cloud TSS return to the POS as an answer (Topic: Documentation of the fault)?
You can find the documentation on SIGN DE API
How can it be ensured that requests from the SMAERS at the checkout to the Cloud-TSS and back are made very quickly?
Our architecture is idempotent and asynchronous. This means that you only have to wait for the answer during a FINISH transaction. Our response times are between 50 and 75 milliseconds in test mode in the complete round trip from Vienna to Frankfurt and back to Vienna. We are happy to provide you with a test application to test your data throughput.
How long are the response times in case of an error (e.g. if the cloud is reachable but the assigned TSS is defective/slow)?
The timeouts can be accepted by the calling cash register. The idempotent and asynchronous architecture ensures a robust connection.
How many dial-in points are there on the cloud TSS server (number of parallel and separate access/Internet nodes, e.g. in the event of Internet access failure)? How is one access automatically switched over to the other (e.g. via DNS?) in the event of a failure?
Our cloud system is designed to be highly scalable. Scaling and error compensation takes place via Kubernetes in our cloud environment. You therefore do not have to deal with this topic.
Clients
What is the Client? Is It possible to have one client for one POS (PC + Printer)?
A client basically is a cash register. Yes, one client per point of sale is the correct mapping.
How many clients are associated with TSS or TSE?
It is recommended that a TSS should have multiple clients.
How can I delete a client?
This is currently not possible. Please share a use case in your organization that demands the deletion of a client in our API.
Can I understand the client as the complete process that is created once for each receipt and serves as an identifier?
A client in the context of a transaction is an electronic recording system that starts, updates, or terminates a transaction. A client is created by calling the appropriate client endpoint and can be referenced by client_id in tx calls.
How is the cash register ID assigned to the cloud TSS?
Receipts
Do you have a sample receipt including information from the TSS?
What type of information must I retrieve from your system and print on the receipt?
According to Anwendungserlass zu § 146a AO (5.4), the receipt must contain:
- Your company name,
- Start and end date (from our system),
- The quantity and type of delivered items or the size and type of other services,
- Transaction number (from our system),
- The fee and the related tax amount,
- The serial number of the cash register or TSS (can come from our system),
- Amount per payment method,
- Signature Counter (from our system),
- Signature Value (from our system).
FYI: here the DSFinV-K 2.1 review is open
What time will be printed on the receipt?
Visit the SIGN DE API Docs for further details.
General questions
What is the binary scheme?
In the binary scheme, the expected formatting according to the application decree for § 146a AO and DSFinV-K would have to be carried out correctly by yourself. We recommend to use the aeoa scheme instead, which allows the formatting to be done automatically for you. The following values are permissible as processType according to the application decree for § 146a AO and DSFinV-K: Cash voucher V1, Purchase order V1, Other transaction
What is the export? Can I utilize this for retrieving past transactions?
The export is implemented according to BSI TR-03151. It is primarily meant for cash register inspection. If you are just interested in the transactions, you may also use the "list transactions" endpoints (listTransactions / listAllTransactions).
Is there a back office system (portal) for our customers, in order to perform an audit export?
The Dashboard is you go-to option here. We have all legal requirements implemented here, in an easy-to-use way also for your non-technical end-customers to use!
How do I download the packed TAR archives (how to log in and download exactly, automatically or manually)?
There are several possibilities:
- via the Data-Exports (automated)
- via the fiskaly-Dashboard (manual trigger)
- via PUSH to an archive system (also automated); this would have to be ordered separately, since an adaptation to your archive system is necessary.
Is a TAR archive created for each closing of a cash register (end of day)?
The connection to your archive via PUSH can be equipped with such a mechanism. Alternatively, you can export the data from our system as a TAR archive for any period of time.
Are several customers together on this physical machine?
Yes. However, there are several physical endpoints. Hardware Security Modules (HSM), which are designed for cloud operation (many clients want to sign simultaneously), are used as CSP components. In case you'd like to have a dedicated cluster for your transactions please contact us.
Are several organizations stored together in one TAR file?
No, this is not permitted according to KassenSichV. One Tar File per TSS.
Where are the data centers located?
All data centers are located in Germany (e.g. Frankfurt am Main).
How can I switch to live mode?
See live mode
DSFinV-K related
Can I only send the delta of new products added to the shopping cart or can I overwrite all the line_items that you have already sent in a previous update?
We would like to refer you to the explanations in the DSFinV-K regarding the possible types of transmission in the DSFinV-K. Whether processData is everything or just a delta is not clearly described. In the DSFinV-K it is now described that the completion of the transaction is the important aspect, and updates lose importance. As long as the processes are described in the procedural documentation, both delta and complete mapping of the data in the updates should be valid.
How can I handle discounts?
The handling of discounts is described in the DSFinV-K Chapter 4.2.4 "Preisnachlässe, Rabatte, Entgeltminderungen".
What part of the responses do we as cash register manufacturers have to store with us?
In principle, failures of the TSS must be recorded. Data that goes beyond the functionality of the TSS must also be recorded by the taxpayer (e.g. parts of the DSFinV-K that cannot be covered by a TSS). We are currently developing an API for the DSFinV-K which can support you in this area.
What additional functions does the cloud TSS solution offer when checking out cash at the branch (Access to TSS-TAR files)? What about the DSFinV-K?
Central administration via the fiskaly-Dashboard. Temporary access for inspection bodies is possible. Full support of the DSFinV-K is in progress.
What is the naming convention of the TSS-TAR archives (important for the retrieval in the cash archive for DSFinV-K)?
From our point of view, the naming convention is not relevant, since our system can be used to create exports over any period with any parameters. See also Data-Exports
How many and what types of transactions has the system?
The operations are either StartTransaction, UpdateTransaction, or FinishTransaction (according to BSI TR-03151). The process type can be either Kassenbeleg-V1, Bestellung-V1, or SonstigerVorgang (according to DSFinV-K 2.0 and Anwendungserlass zu 146a AO).
What information contains the field "binary" (base 64)? Does it have the same details on AEAO?
The binary field can be used in case you are confident that you are able to fulfill the format of process data according to DSFinV-K 2.0 and Anwendungserlass zu 146a AO yourself. The aeao schema will (this feature is currently in development) make it possible that we transform from the JSON structure to the required process data format.
In your example, a transaction starts with type "ORDER" and finishes with type "RECEIPT". Can you describe that to me?
Please see the DSFinV-K 2.0 appendix for examples how to cope with these process types (those are provided between page 104 and 105). There are several possibilities.