Our FAQ is currently in progress. Be aware that it might get updated over the course of the next few weeks.
Product & Tech
Which version of the API should I use?
We recommend always starting with the newest released version. Basically, the Semantic Versioning approach that we follow is: https://semver.org/. As soon as it is foreseeable that no breaking changes to the API are necessary, the API version 1.0.0 will be released.
What is the path for the other versions? If MAJOR is /api/v0, then MINOR is certainly /api/v1/ and patch /api/v2/, correct?
Currently the major version is 0 and the path is /api/v0. For a major upgrade to version 1, the path will be /api/v1. The minor and patch levels of the version are not represented in the path as they are backwards-compatible.
How often do major updates happen? When will I be informed that adjustments 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.
Do you have a sample receipt including information from the TSS?
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).
Does authentication have to be performed for each process?
Normally, this is what I do: Authentication > Generate and send your own TSS > Start transaction with TSS > Update with "DATA" for invoice (receipt) items > End transaction. Is this correct and does the authentication have to be reset for each partial process? I think so, because my ACCESS token expires in time.
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.
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,
What exactly do I need the Refresh Token for? In your opinion, is there a use case in which the refresh token is still needed?
The refresh token is valid longer than the access token. It is used to update an existing access token. This means that a session can be maintained. In principle, authentication and authorization are one of the things that our SDKs is taking over for you - you don't need to work yourself into the internals of JWT]! At GitHub they are published for the different programming languages.
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 fiskaly cloud-TSS integrated? How is the technical integration carried out?
The TSS is integrated into a POS system via an SDK (Software Development Kit). An SDK is a programming interface for a specific programming language or runtime environment.
Accordingly, the system integrator selects the SDK suitable for each POS system in order to integrate the functionality of the TSS (example: for a POS system implemented in Java, the Java SDK needs to be selected). Since an SDK is always specifically designed for one programming language, fiskaly provides an implementation for the most common languages. (see e.g. Node.js or Java) open source at github.com/fiskaly. Due to the free MIT license, the SDKs can be modified, extended and distributed at will.
How do you conceptually differentiate the solution of a local TSS connected to the POS (hardware approach) from your cloud TSS?
For the integrator, the distinction between a pure hardware solution and a cloud solution lies only in the architecture used. In order to address a hardware TSS, the library of the TSS must be installed, which provides the interfaces. In order to address a hardware TSS, the corresponding library must be used, which provides the individual interfaces. The communication with our Cloud TSS is ensured by our library (SDK).
Tthe cloud TSS has the additional advantage that maintenance does not have to be carried out on site, but can be controlled centrally.
We offer you to solve all your needs with one integration.
- Coverage of the entire national compliance if you integrate our SDK.
- Export to KassenSichV (mandatory), to DFKA and also to DSFinV-K, based on which further topics may be implemented.
- Unlike physical devices, you always have live access to your data. The data is also always imported live.
- Legislative-Monitoring on our part. If changes occur to the legal-landscape of TSS, they are implemented by us - Upgrades are free!
- In the worst case, you get a software update, in the best case, the implementation runs in our backend and you don't have to deal with it at all.
- Everything is remote updateable - you'll never physically touch a POS in order to install a TSS!
- With us everything is based on digital interfaces!
- No field management costs - 100% cloud- and software-based
- There's no hardware roll-out.
The TSS or 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?
We recommend to use one TSS per cash register (and vice versa: each TSS should be used by only one client). To be on the safe side, we recommend using one TSS per cash register (client) and vice versa. This will certainly reflect the current regulation.
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 possible for a TSS to have multiple clients. However, as the Security Module Application (SMA) of the TSS must be in the operational environment of the taxpayer, the current recommendation is to have only one client per TSS. This makes it possible to run the SMA directly on your POS.
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.
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 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 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!
What fields are logged by the TSS?
Visit the KassenSichV API Docs for further details.
What time will be printed on the receipt?
Visit the KassenSichV API Docs for further details.
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.
How do I download the packed TAR archives (how to log in and download exactly, automatically or manually)?
Here there are two/three 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.
How is the cash register ID assigned to the cloud TSS?
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 kassensichv 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.
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.
How many cash registers work together on one TSS?
We are working with virtual TSS. Both a 1:1 relationship and an n:1 relationship are possible (POS to TSS). As the nature of TSS only allows sequential signing of transactions, we highly recommend to keep your tx/s peak levels in mind if you opt for the n:1 relationship.
Are several organizations stored together in one TAR file?
No, this is not permitted according to KassenSichV. One Tar File per TSS.
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.
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 also live mode
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.