How to deal with timeouts / system problems
The top priority of the implementation of the fiskaly SIGN DE API is to keep the POS system up and running!
There is no obligation that the Till should stop its operation or be heavily affected at any point in time! - please make sure that your integration is not blocking the operators
In the optimal case, our API is implemented in such a way that the smooth operation of the cash register can be guaranteed at all times. How do you achieve this?
Set Timeouts correctly
Please note that in the event that the TSS is unavailable or temporarily instable, the checkout process will not be disrupted! The timeouts depend heavily on the frequency of the POS system. As a manufacturer, you should decide for yourself which timeout length you consider reasonable. No request should ever be open long enough to jeopardize the smooth operation of the cash register. From our experience we can say that tx-endpoints timeouts between 3 and 5 seconds are reasonable.
If there seems to be a Problem, please see status.fiskaly.com as well as the "how to raise an Issue" Guide
Pro Tipp: Make timeouts configurable We recommend to create the possibility that the timeouts can be set (e.g a value between 1,5-3 seconds) by an administrator. This way, valuable development resources can be saved and a smooth operation of the POS is possible.
For TSS creation and personalization we recommend a Timeout of at least 30 seconds.
Missing Signatures
A missing signature on the document does not mean the document is not in compliance with the law (see Punkt 7 AEAO to § 146a!). However, the fiskaly API must be implemented in such a way that each transaction requests a signature. If not possible to aquire one, the DSFinV-K rules apply.
DSFinV-K and Transactions
All transactions, including transactions without signature, must appear in the DSFinV-K export. For transactions without signature, all known data is transferred to the DSFinV-K export. The financial authorities recommend adding a clear note on the receipt such as
"TSS not available" or "TSS signing failed"
to a receipt without a signature.
For DSFinV-K Endpoints we recommend a timeout of up to 10 minutes, as this can be very heavy processing / inputs.
When you're using the fiskaly DSFinV-K API, the transactions.security.error_message field should be used instead of transactions.security.tss_tx_id at insertCashPointClosing endpoint in the case of unsigned transactions.
Authorization
Authorization is initially done via API Key and API Secret. You will receive an access_token which is valid for 24 hours and a refresh_token which is valid for 48 hours. You can use this to reauthorize yourself on an ongoing basis. If you run into a 401 response, simply reauthorize via API Key and Secret.
Reauthorization should not happen on every request! as this would add unnecessary markup to your checkout process, the validity of the tokens is given for multiple hours.
For Authorization we recommend a timeout of 3-4 seconds.