FAQ

Hier finden Sie Antworten auf 43 häufig gestellte Fragen rund um SIGN DE, organisiert nach Themenbereichen.

Allgemein (14)

Was ist das DSFinV-TW Transaktionsschema und wer sollte es verwenden?

Das DSFinV-TW Transaktionsdatenschema basiert auf den gesetzlichen Vorschriften für Taxameter und Wegstreckenzähler und ist ausschließlich für Unternehmen relevant, die diese Geräte nutzen. Ziel ist es, standardisierte Datenexporte für Steuerprüfungen in Deutschland bereitzustellen.

Zu diesem Zweck sollte das dsfinvtw_v1 Schema im SIGN DE V2 API-Endpunkt Start, update or finish a transaction verwendet werden.

Die offiziellen DSFinV-TW Dokumente können über die Website des Bundeszentralamts für Steuern heruntergeladen werden.

Wie hinterlege ich das aktuelle SSL Zertifikat der SIGN DE V2 manuell?

Bei Betriebssystemen die auf aktuellem Stand gehalten werden, müssen SSL-Zertifikate nicht manuell hinterlegt werden.

Sollte Ihr System bei der Verbindung zur SIGN DE V2 Probleme haben, kann es jedoch notwendig sein die Zertifikate manuell zu hinterlegen.

Hier finden Sie eine Anleitung, wie das aktuelle SSL Zertifikat hinterlegt wird wenn es noch nicht vorhanden sein sollte:

zip-File 2023-09-04-fiskaly-root-certificates herunterladen und entpacken
im Terminal die folgenden Befehle eingeben (das sorgt dafür, dass die Cert Chain im System hinterlegt wird):

certutil -addstore -f "Root" gsr4.pem
certutil -addstore -f "Root" gtsr1.pem
certutil -addstore -f "Root" gtsr2.pem
certutil -addstore -f "Root" gtsr3.pem
certutil -addstore -f "Root" gtsr4.pem
certutil -addstore -f "Root" isrgrootx1.pem
certutil -addstore -f "Root" isrg-root-x2.pem

Wie viele verwaltete Organisationen und TSEs soll ich anlegen?

Für jeden Standort sollte über den Management API Endpunkt createOrganization eine separate managed_organization angelegt werden.

In jeder managed_organization muss mindestens 1 TSE über den SIGN DE API V2 Endpunkt createTss kreiert werden. Eine TSE kann jeweils nur eine Transaktion verarbeiten. In bestimmten Szenarien kann es also ratsam sein, mehr als eine TSE anzulegen.

Für jedes verwendete Kassengerät muss ein separater Client (verbunden mit einer TSE) über den SIGN DE API V2 Endpunkt createClient angelegt werden.

Was ist der Unterschied zwischen receipt (Kassenbeleg-V1) und order (Bestellung-V1)?

Der processType receipt (Kassenbeleg-V1) wird für Transaktionen verwendet, bei denen die Zahlung unmittelbar erfolgt, z.B. im klassischen Einzelhandel.

Für lang anhaltende Transaktionen, z.B. in der Gastronomie, sollten zusätzlich auch Transaktionen des processType order (Bestellung-V1) erstellt werden.

Gute Beispiele und Erläuterungen zu den verschiedenen Szenarien für die Verwendung von order Transaktionen finden Sie im Anhang H Erleichterungsregelungen der offiziellen DSFinV-K-Unterlagen des Bundeszentralamtes für Steuern, die hier heruntergeladen werden können.

Wie kann der QR-Code einer Quittung validiert werden?

fiskalcheck App

Mit der von fiskaly entwickelten App **fiskalcheck **können Sie einfach QR-Codes von Quittungen, eReceipts, und mehr validieren.

Die Prüfung berücksichtigt die Anforderungen an Belege aus der KassenSichV (Kassensicherungsverordnung) sowie der DSFinV-K (Digitale Schnittstelle der Finanzverwaltung für Kassensysteme).

Die Validierungs-App **fiskalcheck **ist kostenlos erhältlich und wird von fiskaly entwickelt.

Wie funktioniert die App?

Die App ist leicht zu bedienen. Scannen Sie einfach den QR-Code und der Validierungsbericht wird sofort angezeigt. So können Sie Ihre TSE-Signatur schnell und sicher überprüfen.

Überblick über die Funktionen

Einfache Bedienung: QR-Code scannen und Validierungsbericht anzeigen lassen

Signaturprüfung der Transaktion gemäß BSI TR-03151
Validierung des processType und der processData nach DSFinV-K
Validierung einzelner Felder nach DSFinV-K-Vorgaben für QR-Codes auf Belegen
Ableitung der TSE-Seriennummer
Einfache Visualisierung der einzelnen Datenfelder
Schnelle Darstellung von Validierungsfehlern
Übernahme von Informationen aus dem Validierungsbericht in andere Anwendungen per Copy/Paste

Download

Die App **fiskalcheck **kann kostenlos unter den folgenden Links im Google Play Store (Android) und im Apple App Store (iOS) heruntergeladen werden:

Kann ich fiskaly SDK, fiskaly Client oder fiskaly Service der V1 auch für die V2 verwenden?

Nein. In der SIGN DE V2 sollten Sie einen HTTP Client Ihrer Wahl zur Ansprache der API verwenden.

fiskaly SDK, fiskaly Client und fiskaly Service aus V1 werden nicht mehr gewartet und können für die V2 nicht mehr verwendet werden.

Wo finde ich eine Anleitung zur Migration von SIGN DE V1 zur V2?

Die SIGN DE V1 ist operativ nur mehr bis zum 30.12.2022 verfügbar. Da ausschließlich die SIGN DE V2 zertifizierte Komponenten verwendet, sollte auf diese upgedatet werden.

Sie finden die Anleitung zur Migration auf unserer Developer Seite.

Wie hinterlege ich manuell das TLS Zertifikat für kassensichv.io der SIGN DE V1?

Bei Betriebssystemen die auf aktuellem Stand gehalten werden, müssen TLS-Zertifikate nicht manuell hinterlegt werden.

Sollte Ihr System jedoch bei der Verbindung zur SIGN DE V1 über www.kassensichv.io Probleme haben, kann es notwendig sein die Zertifikate manuell zu hinterlegen.

Hier finden Sie eine Anleitung, wie das aktuelle TLS Zertifikate hinterlegt wird wenn es noch nicht vorhanden sein sollte:

zip-File www_kassensichv_io_cert_chain.zip herunterladen und auspacken
im Terminal die folgenden Befehle eingeben (das sorgt dafür, dass die Cert Chain im System hinterlegt wird):

certutil -addstore -f "Root" USERTrustRSAAAACA.crt
certutil -addstore -f "Root" SectigoRSADomainValidationSecureServerCA.crt
certutil -addstore -f "Root" AAACertificateServices.crt

Bitte beachten Sie:

Dieser Vorgang betrifft nur SIGN DE V1. SIGN DE V2 ist von diesem Update nicht betroffen.

SIGN DE V1 ist mittlerweile veraltet und kann im produktiven Betrieb nicht mehr verwendet werden. Es sind nur noch GET requests möglich.

Kann ich die selbe UUID von der SIGN DE API V1 (Version 1) für die V2 (Version 2) verwenden?

Nein! Wir empfehlen ausdrücklich, dies nicht zu tun.

Ein Universally Unique Identifier (UUID) ist eine 128-Bit-Zahl, welche zur Identifikation von Informationen in Computersystemen verwendet wird. Der Ausdruck Globally Unique Identifier (GUID) wird ebenfalls benutzt.

Bei der Generierung nach den Standardmethoden können UUIDs für praktische Zwecke als global eindeutig angenommen werden.

Aus diesem Grund sollte eine bestimmte UUID nicht mehr als einmal verwendet werden. Diese wäre dann nicht mehr eindeutig, was zu Fehlverhalten im System führen könnte.

Welcher Timeout soll für SIGN DE API Requests gesetzt werden?

Bitte beachten Sie, dass im Falle einer Nichtverfügbarkeit oder vorübergehenden Instabilität der TSE der Kassiervorgang nicht unterbrochen wird!

Die Timeouts hängen stark von der Frequenz des Kassensystems ab. Als Hersteller sollten Sie selbst entscheiden, welche Timeout-Dauer Sie für angemessen halten. Kein Request sollte so lange offen sein, dass der reibungslose Betrieb der Kasse gefährdet ist.

Aus der Erfahrung unserer Kunden können wir sagen, dass für die Transaktions-Endpunkte ein Timeout zwischen 3 und 5 Sekunden angemessen ist.

Falls Sie ein Problem wahrnehmen sollten, überprüfen Sie bitte die fiskaly-Statusseite sowie den Artikel Wie melde ich ein Problem?.

INFO Pro Tipp: Timeouts konfigurierbar machen. Wir empfehlen, die Möglichkeit zu schaffen, dass die Timeouts von einem Administrator eingestellt werden können (z.B. ein Wert zwischen 1,5-3 Sekunden). Auf diese Weise können wertvolle Entwicklungsressourcen eingespart werden und ein reibungsloser Betrieb der Kasse ist möglich.

Für die TSE-Erstellung und Personalisierung empfehlen wir einen Timeout von mindestens 30 Sekunden.

Wofür kann man das Metadaten Feld verwenden?

Metadaten können für interne Zwecke verwendet werden. Diese werden von fiskaly nicht direkt verwendet.

Sie können bis zu 20 Schlüssel-Wert-Paare im metadata Objekt angeben. Ein Schlüssel kann bis zu 40 Zeichen lang sein. Ein Wert kann bis zu 500 Zeichen lang sein.

Weitere Informationen über das Metadaten Feld, finden Sie in der API Dokumentation sowie bei den einzelnen Endpunkten.

Ist es möglich, TSEs, Clients und/oder Transaktionen dauerhaft zu löschen?

Es ist nicht möglich, einzelne TSEs, Clients oder Transaktionen dauerhaft zu löschen.

Bei Bedarf können wir Ihnen jedoch behilflich sein, eine gesamte Organisation bzw. verwaltete Organisation aus der Test-Umgebung zu löschen.

Bitte lesen Sie dazu den Artikel Löschen einer Organisation.

In diesem Fall wird die Organisation mit allen angelegten Ressourcen dauerhaft gelöscht.

Achtung: LIVE Organisationen mit produktiven Ressourcen können nicht gelöscht werden.

Welche Daten müssen auf dem Kassenbon vermerkt werden?

Nachfolgend finden Sie alle Daten, die auf einem Kassenbon vermerkt werden müssen, abgebildet mit den Werten, die vom upsertTransaction Endpunkt der SIGN DE zurückgegeben werden.

Es ist ausreichend, entweder den QR-Code oder die genannten Felder auf den Belegen zu erfassen.

INFO

Wir wurden von den zuständigen Finanzbehörden mit dem Appell kontaktiert, unseren Kunden ausdrücklich die QR-Code Lösung zu empfehlen!

Die TSE Daten (=abgesicherte Daten laut KassenSichV) sollen im QR-Code hinterlegt werden. Somit entfällt der Druck des TSE Klartextes auf Belegen. Im Falle einer Kassen-Nachschau erleichtert der QR-Code den Prozess. Kürzere Belege sparen Papier ein und dadurch Geld. Zusätzlich werden Thermopapier-Schadstoffe vermieden und die Umwelt geschont. Alternativ können Sie auf den digitalen fiskaly Beleg umsteigen und damit ganz auf Thermopapier verzichten.

Bitte beachten Sie, dass bei Anwendung der Erleichterungsregelungen für komplexe Systeme entsprechend der DSFinV-K Kapitel 2.7, zusätzlich der Start-Zeitpunkt der ersten order (“Bestellung-V1”) Transaktion auf den Beleg gedruckt werden muss (nicht im QR-Code integriert).

Darüber hinaus muss gewährleistet sein, dass der inhaltliche Zusammenhang über das Feld ABRECHNUNGSKREIS in der Datei Bonkopf_AbrKreis (vgl. Kapitel 3.1.2.2) in den DSFinV-K-Daten hergestellt werden kann, um die Entstehung und Abwicklung der einzelnen Bestell- und Abrechnungs-Vorgänge nachvollziehen zu können.

Ab 1. Januar 2024 muss der Beleg in Deutschland zusätzlich zu den bereits inkludierten TSE-Daten außerdem die Seriennummer des elektronischen Aufzeichnungssystems sowie die Seriennummer des Sicherheitsmoduls (TSE) beinhalten (vgl. AEAO zu § 146a, Nr. 2.2.3.1 und 2.2.3.2)


Feld Beleg	Feld SIGN DE
TSE-Transaktion	number
TSE-Start	time_start
TSE-Stop	time_end
TSE-Seriennummer	tss_serial_number
TSE-Zeitformat	log.timestamp_format
TSE-Hashalgorithmus	signature.algorithm
TSE-PublicKey	signature.public_key
ClientID / KassenID	client_serial_number (entspricht der Seriennummer des elektronischen Aufzeichnungssystems)
TSE-Erstbestellung	Dieses Feld muss vom Kassenhersteller manuell hinzugefügt werden.
QR-Code	qr_code_data

New receipt comparison EN no BG.png

Der erste Kassenbeleg zeigt die verkürzte Variante, bei der die abgesicherten TSE-Daten im QR-Code hinterlegt wurden. Der zweite Beleg auf der rechten Seite zeigt einen Beleg mit aufgedrucktem Klartext der abgesicherten TSE-Daten laut KassenSichV. Hier ist der Unterschied in der Länge und dadurch die Einsparung von Ressourcen deutlich zu sehen.

Wo finde ich die offiziellen Dokumente zur fiskaly SIGN DE Zertifizierung?

Alle relevanten Dokumente zur Zertifizierung von fiskaly sind auf der fiskaly developers Seite zu finden.

Exporte (5)

Wie kann ein TSE-Export (TAR Export) ausgelöst und heruntergeladen werden?

**ACHTUNG: **Das Auslösen eines Exports kann den normalen Betrieb stören, einschließlich der Möglichkeit, Transaktionen zu signieren. Daher sollten Exporte am besten außerhalb der Geschäftszeiten ausgelöst werden.

TSE-Exporte im TAR-Format können über das fiskaly Dashboard ausgelöst und heruntergeladen werden.

Login

Melden Sie sich mit Ihren Kontodaten im fiskaly Dashboard an.

Wählen Sie die jeweilige Ansicht

Wählen Sie in der linken oberen Ecke die gewünschte Umgebung („LIVE“ oder „TEST“).

Wählen Sie Land und Lösung

Wählen Sie in der linken Seitenleiste „Deutschland“, dann „SIGN DE V2“, gefolgt von „Technische Sicherheitseinrichtung“.

Wählen Sie eine TSE

Es erscheint eine Liste aller TSE Instanzen. Wählen Sie die TSE aus, für die Sie einen Export auslösen möchten, indem Sie auf die entsprechende ID klicken.

Lösen Sie den Export aus

Klicken Sie auf „EXPORT AUSLÖSEN“ in der oberen linken Ecke.

Wenden Sie (falls erforderlich) Filter an oder erstellen Sie einen vollständigen Export. Wählen Sie den gewünschten Zeitraum und klicken Sie dann auf „EXPORT“.

Laden Sie die Export-Datei herunter

Klicken Sie in der linken Seitenleiste auf „Exporte“.

Sie sehen nun eine Liste aller Exporte. Der erste aufgelistete Export ist der aktuellste. Scrollen Sie nach rechts und klicken Sie auf „HERUNTERLADEN“.

Alternativ können TSE-Exporte auch über die SIGN DE API ausgelöst und heruntergeladen werden:

Auslösen eines Exports: Verwenden Sie den Endpunkt Trigger an export.

Herunterladen des Exports: Rufen Sie die TAR-Datei ab, die durch den Exportvorgang erzeugt wurde, indem Sie den Endpunkt Retrieve the TAR file generated by an export operation verwenden.

Hinweis: Der Query-Parameter client_id sollte nicht in Kombination mit anderen Parametern verwendet werden.

Warum werden beim TSE Export meine Filteroptionen ignoriert?

Hier finden Sie eine Beschreibung wie vom SIGN DE API V2 Endpunkt triggerExport mit dem TSE Exporte (.tar Exporte) erstellt werden.

Falls Ihre Filteroptionen ignoriert werden, sollten Sie insbesondere überprüfen, ob Sie z.B. start_date, end_date, start_transaction_number, end_transaction_number tatsächlich als Query Parameter (und nicht als Request Body) in Ihrem Request übergeben haben.

Bitte beachten Sie weiters, dass bei der Verwendung der Filterung auf einen Client (client_id) alle weiteren Query Parameter ignoriert werden.

Warum wird beim TSE Export mit Filterung auf einen Client das Zeitintervall ignoriert?

Hier finden Sie eine Beschreibung wie vom SIGN DE API V2 Endpunkt triggerExport mit dem TSE Exporte (.tar Exporte) erstellt werden.

Bitte beachten Sie, dass der Query-Parameter client_id nicht in Kombination mit anderen Query-Parametern start_date, end_date, start_transaction_number, end_transaction_number) verwendet werden kann.

Bei der Filterung nach einem bestimmten Client werden alle anderen Filteroptionen ignoriert.

Timeout nach dem Triggern eines TSE Exports (.tar Export)

Nach dem Triggern eines TAR Exports auf der SIGN DE API V2 ist die entsprechende TSE so lange blockiert bis der Export abgeschlossen ist (etwa 10-20 Sekunden).

Bitte berücksichtigen Sie dieses Verhalten in Ihrer Implementierung.

Kann ich Log-Dateien eines TSE Exports ‘lesbar’ darstellen?

Log Dateien sind nicht menschlich lesbar. Diese werden digital validiert.

TSE - Technische Sicherheitseinrichtung (9)

Kann ein TEST TSE Zertifikat ablaufen?

Das Zertifikat einer TEST TSE ist ab Erstellung der TSE ein Jahr gültig.

Wenn Sie die Fehlermeldung E_CERTIFICATE_EXPIRED erhalten sollte einfach eine neue TSE erstellt werden.

Bitte beachten Sie, dass dies nur auf TEST TSE Instanzen zutrifft. Zertifikate einer LIVE TSE Instanzen haben keine begrenzte Gültigkeit.

Was bedeutet der Status EVICTED einer TSE?

Alle TSEs, die sich seit mindestens 3 Monaten im Status CREATED befinden werden künftig in den Status EVICTED gesetzt.

TSEs im Status EVICTED können nicht zum Signieren der Transaktionen verwendet werden und es ist nicht möglich den Status dieser TSEs zu ändern. Für diese TSEs ist kein Zertifikat verfügbar.

Um zu verhindern, dass eine TSE in den Status EVICTED gesetzt wird ist es notwendig den Status einer neu angelegten TSE von CREATED auf UNINITIALIZED und dann auf INITIALIZED zu ändern. Nur initialisierte TSEs können Transaktionen signieren. Wir empfehlen nur so viele TSEs zu erstellen, wie für das Signieren nötig sind.

Kann eine TSE aus einer Organisation in eine andere verschoben werden?

Es ist nicht mögliche eine TSE aus einer (verwalteten) Organisation in eine andere (verwaltete) Organisation zu verschieben.

Da jede (verwaltete) Organisation einen eigenen Standort darstellt sollte die TSE immer dem bestimmten Standort zugewiesen werden.

Tipp: Wird eine TSE innerhalb einer Organisation nicht mehr benötigt sollte diese deaktiviert und die mit der TSE verbundenen Kassen (clients) deaktiviert werden. Wichtig: Kassen (clients) können nicht mehr deaktiviert werden, sobald die TSE deaktiviert wurde - siehe SIGN DE - Kann eine Kasse (client) deaktiviert werden nachdem die TSE deaktiviert wurde?

Warum startet der Signaturzähler (signature_counter) einer neuen TSE nicht bei null?

Bei der Initialisierung einer TSE laufen im Hintergrund bereits einige systemrelevante Prozesse ab, die ebenfalls als Signaturen erfasst werden.

Die System-Signaturen sind der Grund, warum der signature_counter nicht mit der Anzahl der Transaktionen übereinstimmt.

Warum bekomme ich die Fehlermeldung 401 ERROR_AUTHENTICATION_FAILED (AUTHENTICATION_RESULT_PIN_IS_BLOCKED)?

Ihr admin_pin wird nach fünf erfolglosen Authentifizierungsversuchen gesperrt. In diesem Fall muss der admin_pin zurückgesetzt werden. Führen Sie in dem Fall den SIGN DE API V2 Endpunkt changeAdminPin Request mit Ihrem admin_puk und new_admin_pin aus.

Warum hat eine TSE der TEST-Umgebung den Status DELETED?

Jede TSE in der TEST Umgebung, die sich im Status DISABLED befindet oder seit mehr als 14 Tagen inaktiv ist, wird jeden Sonntag gelöscht. Das bedeutet, dass ihre Ressourcen gelöscht werden und die TSEs der TEST Umgebung in der Datenbank in den Status DELETED übergehen.

Sollte das TSE Limit in der TEST Umgebung erreicht werden, können Ressourcen für neue TSEs freigemacht werden, indem der Status von vorhandenen TSEs auf DISABLED gesetzt wird.

Eine Anleitung hierfür finden Sie in folgendem Artikel:

SIGN DE - Wie kann ich eine TSE deaktivieren (disablen)?

Was bedeutet der Status DEFECTIVE einer TSE?

Aufgrund eines technischen Problems bei einer TSE kann es vorkommen, dass diese TSE von fiskaly in den Status DEFECTIVE gesetzt werden muss. In diesem seltenen Fall muss die TSE durch eine neue ersetzt werden. Vorhandene Clients müssen mit jeweils neuer client_id mit der neuen TSE verknüpft werden.

TSE-Exporte (TAR files) können weiterhin ausgelöst und heruntergeladen werden.

Ist es möglich den Admin-PUK einer TSE nachträglich auszulesen?

**Bitte beachten Sie: ** Es ist wichtig, Admin-PUK und Admin-PIN einer TSE sicher zu hinterlegen.

Falls sich die TSE noch im Status CREATED befindet, gibt ein idempotenter Request auf den SIGN DE API Endpunkt createTss mit der entsprechenden tss_id als Path-Parameter den Admin-PUK der TSE zurück.

Sollte die TSE bereits einen anderen Status haben gibt es leider keine direkte Möglichkeit den Admin-PUK auszulesen. Senden Sie uns bitte in dem Fall eine Support Anfrage (dev-support@fiskaly.com) mit der entsprechenden tss_id, damit wir das weitere Vorgehen koordinieren können.

Wie kann ich eine TSE deaktivieren (disablen)?

Eine TSE wird deaktiviert indem diese über den SIGN DE API V2 Endpunkt updateTss auf den Status "DISABLED" gesetzt wird. Dieser Schritt kann nicht rückgängig gemacht werden. Es ist jedoch weiterhin möglich, ältere Daten dieser TSE zu exportieren (triggerExport).

Eine TSE kann nur aus dem Status "UNINITIALIZED" und "INITIALIZED" deaktiviert werden.

Bevor der Status einer TSE geändert werden kann, muss eine Admin-Authentifizierung über den SIGN DE V2 Endpunkt authenticateAdmin erfolgen.

Die Deaktivierung ist auch über das fiskaly Dashboard möglich:

Melden Sie sich bei Ihrem Konto an und wählen Sie die entsprechende Organisation aus.
Mit dem Schalter oben links schalten Sie auf die entsprechende Ansicht (“LIVE” oder “TEST”), in der die TSE erstellt wurde.
Wählen Sie auf der linken Seitenleiste “Deutschland”, dann “SIGN DE V2”, und “Technische Sicherheitseinrichtung”.
Es öffnet sich eine Seite mit allen TSEs der Organisation.
Klicken Sie auf die ID der TSE, die deaktiviert werden soll. Es öffnet sich eine neue Seite.
Auf der TSE-Seite können Sie auf “TSE DEAKTIVIEREN” klicken, um den Dialog zum DISABLEN zu öffnen.
Für das Update wird die Admin-PIN benötigt.

Transaktionen (6)

Wie finde ich die letzte Transaktion einer TSE?

Die letzte Transaktion, die von einer bestimmten TSE verarbeitet wurde, kann folgendermaßen gefunden werden:

Verwenden Sie den retrieveTss Endpunkt, indem Sie die ID der entsprechenden TSE angeben.

Das Feld transaction_counter in der Antwort enthält die Nummer der zuletzt verarbeiteten Transaktion.

Verwenden Sie diese Nummer als Teil der Basis-URL und rufen Sie die Transaktion mithilfe des Endpunkts retrieveTransaction ab.

Wie ist mit nachträglichen Stornierungen umzugehen?

Im folgenden Beispiel wird gezeigt, wie eine bereits geschlossene Transaktion (Status FINISHED) storniert werden kann.

Im Falle einer nachträglichen Stornierung sollte über den SIGN DE V2 API upsertTransaction Endpunkt eine neue Transaktion mit dem receipt_type "RECEIPT" und negativen Vorzeichen erstellt werden.

Über die DSFinV-K sollte das Feld transactions[].head.storno auf “true” gesetzt werden, um zu kennzeichnen, dass es sich bei dieser neuen Transaktion um eine Stornierung der ursprünglichen Transaktion handelt.

Zusätzlich muss gemäß DSFinV-K im Kassenabschluss eine Referenz auf die ursprüngliche Transaktion gemacht werden. Untertransactions[].head.references über den Endpunkt insertCashPointClosing können hierfür mehrere Schemata ausgewählt werden - im Falle einer internen Referenz kann ReferenceInternalTransaction verwendet werden.

Bitte beachten Sie:

Bei einer nachträglichen Stornierung handelt es sich um keinen sofortigen Belegabbruch.

Wie sieht der klassische Checkout-Vorgang aus?

Der klassische Checkout-Vorgang sieht folgendermaßen aus:

Kundin kommt zur Kasse.
Eine Transaktion wird im Status ACTIVE ohne Schema Objekt gestartet (tx_revision=1).
Verkaufs- und Bezahlvorgang finden an der Kasse statt.
Nach dem erfolgreichen Bezahlvorgang wird die Transaktion mit ausgefülltem Schema mit dem Status FINISHED beendet (tx_revision=2).

In Gastronomie-Szenarien werden zusätzlich lang anhaltende Transaktionen des processType Bestellung-V1 benötigt. Details hierzu sind in den Erleichterungsregelungen (‘simplification arrangements’ in der englischen Fassung) der offiziellen DSFinV-K Dokumente zu finden: DSFinV-K 2.3, (new version) (EN) DSFinV-K 2.3, Stand März 2022 (DE)

Wie mit Verkaufsprozessen umgehen, die unmittelbar nach Beginn der Transaktion abgebrochen werden?

Muss ein Beleg unmittelbar storniert werden - also **bevor die Transaktion abgeschlossen ist **- z. B. aufgrund eines Fehlers oder wenn Kunden ihre Meinung ändern, kann folgendermaßen vorgegangen werden:

Die Transaktion sollte beendet werden, indem sie in den state "CANCELLED" gesetzt wird und zwar mit dem receipt_type "CANCELLATION" (AVBelegabbruch) und allen anderen erforderlichen Feldern.

Im Zusammenhang mit diesem Szenario darf keine Zahlung erfolgen.

Es wird darauf hingewiesen, dass sich das genannte Szenario von jenem einer Refundierung und einer nachträglichen Stornierung unterscheidet.

Bitte beachten Sie:

Die genannten Möglichkeiten sind nicht erschöpfend und sollten nur als Option betrachtet werden.

Wie ist mit Refundierungen umzugehen?

Im Falle einer Refundierung sollte über den SIGN DE V2 API upsertTransaction Endpunkt eine neue Transaktion mit dem receipt_type "RECEIPT" und negativen Vorzeichen erstellt werden.

Gemäß DSFinV-K muss im Kassenabschluss eine Referenz auf die ursprüngliche Transaktion gemacht werden. Untertransactions[].head.references über den Endpunkt insertCashPointClosing können hierfür mehrere Schemata ausgewählt werden - im Falle einer internen Referenz kann ReferenceInternalTransaction verwendet werden.

Bitte beachten Sie:

Bei Refundierungen handelt es sich um keinen sofortigen Belegabbruch.

Welche Felder sollte das Schema einer Transaktion enthalten?

Das Schema einer Transaktion finden Sie in der SIGN DE API Dokumentation:

Um eine Transaktion zu starten, setzen Sie den Status im Request Body auf "ACTIVE" und verwenden Sie die richtige client_id.

Es gibt zwei Möglichkeiten, eine Transaktion zu schließen:

Wenn die Transaktion wie erwartet abgeschlossen wurde, setzen Sie den Status auf "FINISHED".
Wenn etwas schief gegangen ist und Sie die Transaktion abbrechen möchten, setzen Sie den Status auf "CANCELLED".

Der Query-String für diesen Endpunkt muss den Parameter tx_revision enthalten. Setzen Sie tx_revision auf 1, wenn Sie die Transaktion starten. Nach jedem Aufruf muss die tx_revision inkrementiert werden.

Alle Daten im Schema-Feld des Request Body müssen UTF-8 kodiert sein.

Wenn Sie eine Transaktion starten, müssen der Typ und die Daten der Transaktion leer sein. Dies wird von der DSFinV-K (v2.1) vorgeschrieben.

Clients (6)

Kann eine Kasse (client) deaktiviert werden nachdem die TSE deaktiviert wurde?

Sobald eine TSE deaktiviert wurde ist es nicht mehr möglich, den Status einer Kasse (client), die mit dieser TSE verbunden ist, zu ändern.

Eine Kasse (client) kann also nur vor dem Deaktivieren der verbundenen TSE deaktiviert, also in den Status DEREGISTERED gesetzt werden.

Kann ein Client in Verbindung mit einer TSE in state CREATED erstellt werden?

Nein. Ein Client kann nur in Verbindung mit einer TSE in state UNINITIALIZED oder INITIALIZED erstellt werden.

Welche Daten verwende ich als serial_number beim Erstellen eines Clients?

Gemäß Abschnitt 7.5 der Technischen Richtlinie BSI TR-03153 muss die serial_number eines Clients vom Hersteller eindeutig vergeben werden, wodurch das Aufzeichnungssystem (ERS) gemeinsam mit der Information über den Hersteller eindeutig repräsentiert wird.

Wie kann ich eine Kasse (Client) deaktivieren, die nicht mehr verwendet werden soll?

Sie können eine Kasse (Client), die nicht mehr verwendet werden soll, in den Zustand "DEREGISTERED" setzen. Dies erfolgt über den SIGN DE API V2 Endpunkt updateClient.

Bitte beachten Sie, vor dem Ändern des Zustands eines Clients muss eine Admin Authentifizierung erfolgen. Details finden Sie in folgendem Artikel: SIGN DE - Wann genau benötige ich eine Admin Authentifizierung (authenticateAdmin) ?

Ein Client, der mit einer TSE im Zustand DISABLED verbunden ist, kann nicht mehr aktualisiert und nicht mehr verwendet werden. Dieser Client wird auch nicht verrechnet.

Kann ein Client im Dashboard angelegt werden oder nur über die SIGN DE API?

Clients können nur über die SIGN DE API angelegt werden.

Verwenden Sie hierfür den API-Endpunkt createClient.

Ist es möglich, eine Transaktion auf einem Client zu starten und dieselbe Transaktion auf einem anderen Client abzuschließen?

Es ist nicht möglich, unterschiedliche client_ids für das Starten (state: ACTIVE) und Schließen (state: FINISHED) derselben Transaktion zu verwenden.

Je nach Anwendungsfall können Sie jedoch die Verwendung der Erleichterungsregelungen, wie sie bei den Unterlagen der DSFinV-K ab der Seite 109 abgebildet sind, in Erwägung ziehen.

Deutsch: DSFinV-K 2.3

Authentifizierung (1)

Wann genau benötige ich eine Admin Authentifizierung (authenticateAdmin) ?

Neben der API-Authentifizierung mit einem gültigen Access Token benötigen einige Endpunkte der SIGN DE API auch eine Admin-Authentifizierung.

Die Admin-Authentifizierung erfolgt über den SIGN DE API Endpunkt authenticateAdmin.

Mit authenticateAdmin erhält der verwendete Access Token zusätzliche Admin-Rechte für die Dauer seiner Gültigkeit, bzw. bis zum Aufruf des logoutAdmin Endpunktes.

Diese Admin-Rechte werden für einige Anfragen an TSEs und Clients des SIGN DE benötigt.

In der API-Dokumentation sind diese Endpunkte mit der Information Requires Admin Authentication gekennzeichnet.

updateTss (Erfordert Admin-Authentifizierung für Update zu INITIALIZED und DISABLED)

Bitte beachten Sie, dass die Admin-Authentifizierung der SIGN DE API nichts mit dem Admin einer Organisation der fiskaly Management API zu tun hat. Einen Artikel über den Admin einer Organisation finden Sie unter Was ist der Admin einer Organisation?.

Fehler und Statuscodes (2)

Timeout nach dem Triggern eines TSE Exports (.tar Export)

Nach dem Triggern eines TAR Exports auf der SIGN DE API V2 ist die entsprechende TSE so lange blockiert bis der Export abgeschlossen ist (etwa 10-20 Sekunden).

Bitte berücksichtigen Sie dieses Verhalten in Ihrer Implementierung.

Was ist im Falle eines Verbindungsabbruchs zu fiskaly zu tun?

Wichtig: DIE KASSE DARF NICHT BLOCKIERT WERDEN! Es besteht keine Verpflichtung, dass die Kasse zu irgendeinem Zeitpunkt aufgrund von Verbindungsproblemen zur SIGN DE API nicht mehr verwendet werden kann. Der Betrieb der Kasse sollte dadurch nicht beeinträchtigt werden. Bitte stellen Sie sicher, dass Ihre Integration den Betrieb der Kasse nicht blockiert.

Sofern der fiskaly service nicht erreichbar ist können in dem Zeitraum keine Transaktionen signiert werden. In diesem Fall sollte statt der Signatur eine Fehlermeldung, die den Grund für die fehlende Signatur beschreibt (z.B. “Verbindung zur TSE nicht möglich” oder “TSE ausgefallen”), auf dem Kassenbon festgehalten werden.

Die nachträgliche Signierung der Transaktion ist nicht zulässig.

Was this page helpful?