Error and Timeout Handling
The top priority when implementing the fiskaly SIGN DE API is to keep the POS system up and running at all times.
There is no obligation that the till should stop its operation or be heavily affected at any point in time. Make sure that your integration is not blocking the operators.
In the optimal case, the API is implemented in such a way that the smooth operation of the cash register can be guaranteed at all times. Here’s how to achieve this.
Set Timeouts Correctly
Section titled “Set Timeouts Correctly”In the event that the TSS is unavailable or temporarily unstable, the checkout process must not be disrupted. Timeouts depend heavily on the frequency of the POS system. As a manufacturer, you should decide which timeout length you consider reasonable. No request should ever be open long enough to jeopardize smooth cash register operation.
Recommended Timeout Values
Section titled “Recommended Timeout Values”| Endpoint | Recommended Timeout | Notes |
|---|---|---|
| Transaction endpoints | 3 - 5 seconds | Most critical for checkout flow |
| TSS creation & personalization | 30 seconds minimum | One-time setup operation |
| Authorization | 3 - 4 seconds | Token refresh, not every request |
| DSFinV-K endpoints | Up to 10 minutes | Heavy processing / data exports |
We recommend creating the possibility for timeouts to be set (e.g., a value between 1.5 - 3 seconds) by an administrator. This way, valuable development resources can be saved and smooth POS operation is possible.
If there seems to be a problem, please check status.fiskaly.com as well as the support page.
Handling Errors Gracefully
Section titled “Handling Errors Gracefully”When a request fails or times out, follow this approach:
Detect the failure
Set appropriate timeouts per endpoint type (see table above). When a timeout or HTTP error occurs, catch it gracefully without blocking the checkout.
Continue the checkout
Allow the transaction to proceed even without a TSS signature. Record the transaction locally with all available data.
Mark the receipt
Add a clear note on the receipt such as “TSS not available” or “TSS signing failed” as recommended by the financial authorities.
Record in DSFinV-K
Ensure the unsigned transaction appears in the DSFinV-K export using the
transactions.security.error_messagefield instead oftransactions.security.tss_tx_id.
Missing Signatures
Section titled “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 it is not possible to acquire one, the DSFinV-K rules apply.
All transactions, including those without a signature, must appear in the DSFinV-K export. For transactions without a signature, all known data is transferred to the DSFinV-K export.
DSFinV-K and Transactions
Section titled “DSFinV-K and Transactions”The financial authorities recommend adding a clear note on the receipt for unsigned transactions, such as:
“TSS not available” or “TSS signing failed”
When using the fiskaly DSFinV-K API, the transactions.security.error_message
field should be used instead of transactions.security.tss_tx_id at the
insertCashPointClosing endpoint in the case of unsigned transactions.
Authorization
Section titled “Authorization”Authorization is initially done via API Key and API Secret. You will receive:
| Token | Validity |
|---|---|
access_token | 24 hours |
refresh_token | 48 hours |
You can use these tokens to reauthorize yourself on an ongoing basis. If you receive a 401 response, simply reauthorize via API Key and Secret.
Reauthorization should not happen on every request, as this would add unnecessary overhead to your checkout process. The validity of the tokens is given for multiple hours.
- Set appropriate timeouts for each endpoint type
- Make timeouts configurable by an administrator
- Never block the till — always allow the checkout to proceed
- Record all transactions in the DSFinV-K export, even unsigned ones
- Add a clear note to receipts when a signature is missing
- Cache authorization tokens and reuse them within their validity period