Fehler- und Timeout-Behandlung

Die oberste Priorität bei der Implementierung der fiskaly SIGN DE API ist es, das Kassensystem jederzeit in Betrieb zu halten.

⚠️Kasse nicht blockieren

Es besteht keine Verpflichtung, dass die Kasse ihren Betrieb einstellt oder zu irgendeinem Zeitpunkt stark beeinträchtigt wird. Stellen Sie sicher, dass Ihre Integration die Bediener nicht blockiert.

Im optimalen Fall ist die API so implementiert, dass der reibungslose Betrieb der Kasse jederzeit gewährleistet werden kann. So erreichen Sie dies.

Timeouts richtig setzen

Im Falle einer Nichtverfügbarkeit oder vorübergehenden Instabilität der TSS darf der Kassiervorgang nicht unterbrochen werden. Timeouts hängen stark von der Häufigkeit des Kassensystems ab. Als Hersteller sollten Sie entscheiden, welche Timeout-Länge Sie für angemessen halten. Keine Anfrage sollte jemals so lange offen sein, dass der reibungslose Kassenbetrieb gefährdet wird.

Empfohlene Timeout-Werte

Endpunkt	Empfohlener Timeout	Hinweise
Transaktionsendpunkte	3 - 5 Sekunden	Am kritischsten für den Kassenvorgang
TSS-Erstellung & Personalisierung	Mindestens 30 Sek.	Einmaliger Einrichtungsvorgang
Autorisierung	3 - 4 Sekunden	Token-Aktualisierung, nicht bei jeder Anfrage
DSFinV-K-Endpunkte	Bis zu 10 Minuten	Umfangreiche Verarbeitung / Datenexporte

💡Timeouts konfigurierbar machen

Wir empfehlen, die Möglichkeit zu schaffen, Timeouts (z. B. einen Wert zwischen 1,5 - 3 Sekunden) von einem Administrator einstellen zu lassen. Auf diese Weise können wertvolle Entwicklungsressourcen gespart und ein reibungsloser Kassenbetrieb ermöglicht werden.

📘Note

Wenn ein Problem zu bestehen scheint, überprüfen Sie bitte status.fiskaly.com sowie die Supportseite.

Fehler elegant behandeln

Wenn eine Anfrage fehlschlägt oder ein Timeout auftritt, folgen Sie diesem Ansatz:

1. Fehler erkennen

   Setzen Sie geeignete Timeouts pro Endpunkttyp (siehe Tabelle oben). Wenn ein Timeout oder HTTP-Fehler auftritt, fangen Sie ihn elegant ab, ohne den Kassiervorgang zu blockieren.

2. Kassenvorgang fortsetzen

   Erlauben Sie der Transaktion fortzufahren, auch ohne TSS-Signatur. Erfassen Sie die Transaktion lokal mit allen verfügbaren Daten.

3. Beleg kennzeichnen

   Fügen Sie einen klaren Hinweis auf dem Beleg hinzu, wie „TSS nicht verfügbar” oder „TSS- Signierung fehlgeschlagen”, wie von den Finanzbehörden empfohlen.

4. In DSFinV-K erfassen

   Stellen Sie sicher, dass die unsignierte Transaktion im DSFinV-K-Export erscheint, indem Sie das Feld transactions.security.error_message anstelle von transactions.security.tss_tx_id verwenden.

Fehlende Signaturen

Eine fehlende Signatur auf dem Dokument bedeutet nicht, dass das Dokument nicht gesetzeskonform ist (siehe Punkt 7 AEAO zu § 146a). Allerdings muss die fiskaly API so implementiert sein, dass jede Transaktion eine Signatur anfordert. Wenn es nicht möglich ist, eine zu erhalten, gelten die DSFinV-K-Regeln.

⚠️Unsignierte Transaktionen müssen trotzdem erfasst werden

Alle Transaktionen, einschließlich derjenigen ohne Signatur, müssen im DSFinV-K-Export erscheinen. Bei Transaktionen ohne Signatur werden alle bekannten Daten an den DSFinV-K-Export übertragen.

DSFinV-K und Transaktionen

Die Finanzbehörden empfehlen, einen klaren Hinweis auf dem Beleg für unsignierte Transaktionen hinzuzufügen, wie z. B.:

„TSS nicht verfügbar” oder „TSS-Signierung fehlgeschlagen”

📘Note

Bei Verwendung der fiskaly DSFinV-K API sollte das Feld transactions.security.error_message anstelle von transactions.security.tss_tx_id am insertCashPointClosing-Endpunkt im Falle von unsignierten Transaktionen verwendet werden.

Autorisierung

Die Autorisierung erfolgt zunächst über API-Schlüssel und API-Geheimnis. Sie erhalten:

Token	Gültigkeit
access_token	24 Stunden
refresh_token	48 Stunden

Sie können diese Token verwenden, um sich fortlaufend neu zu autorisieren. Wenn Sie eine 401-Antwort erhalten, autorisieren Sie sich einfach erneut über API-Schlüssel und -Geheimnis.

⚠️Nicht bei jeder Anfrage neu autorisieren

Die Neuautorisierung sollte nicht bei jeder Anfrage erfolgen, da dies unnötigen Overhead für Ihren Kassiervorgang bedeuten würde. Die Gültigkeit der Token gilt für mehrere Stunden.

💡Zusammenfassung der Best Practices

1. Geeignete Timeouts für jeden Endpunkttyp festlegen
2. Timeouts durch einen Administrator konfigurierbar machen
3. Kasse niemals blockieren – Kassiervorgang immer fortführen lassen
4. Alle Transaktionen im DSFinV-K-Export erfassen, auch unsignierte
5. Klaren Hinweis auf Kassenbons hinzufügen, wenn eine Signatur fehlt
6. Autorisierungstoken zwischenspeichern und innerhalb ihrer Gültigkeitsdauer wiederverwenden

Verwandte Seiten

Leitfaden für Neukunden

Vollständige Einrichtungsanleitung einschließlich Authentifizierung

Unterstützung

So melden Sie ein Problem und kontaktieren das Support-Team