Die Swissbit-TSE wird zusammen mit einem SDK sowie einer API-Beschreibung ausgeliefert. Beide können Sie nach Erwerb des Implementierungskits über den nicht öffentlichen Bereich des Shops herunterladen. 

Um die TSE am Kassensystem zu betreiben muss im Falle der Formfaktoren microSD und SD ein entsprechender Leser genutzt werden. 


Das SDK, derzeit erhältlich für Windows, Linux und Android muss in die Kassenapplication integriert (verlinkt) werden. 


Ist die TSE gemountet (Unter Windows stellt sich die TSE als gewöhnliches Laufwerk dar) sollte man sich den Laufwerksbuchstaben merken, da dieser in der Applikationslösung normalerweise konfiguriert werden muss. Das Implementieren einer Erkennungsroutine bleibt jedem selbst überlassen. 


Konfiguration einer TSE Einheit

Passwörter

Der PIN und der PUK funktionieren wie bei einem Handy. Wird der PIN zu oft falsch eingegeben, dann muss er mit dem PUK (Admin User) entsperrt werden. Wird der PUK zu oft falsch eingegeben, kann die TSE Einheit nicht mehr genutzt werden. PIN und PUK können geändert werden.

Die TaxID ist die Steuernummer des Kunden und kann nur einmal registriert werden.

Die ID gibt den Namen des Client an.

Zusätzlich benötigt man den Credential-Seed, ohne welchen man die Karte nicht initialisieren kann. Dieser ist bei uns „SwissbitSwissbit“.


Einrichten einer TSE Einheit

Initialisieren: worm_Init : Parmeter : Laufwerksbuchstabe

Wurde die Karte noch nicht aktiviert, muss ein SETUP durchgeführt werden. Dabei werden alle Daten wie PIN,PUK,ID,…… gesetzt. Hierfür benötigt man den Credential-Seed.

Setup durchführen

  • worm_tse_runSelfTest (Es kommt ein Fehler zurück, muss aber trotzdem ausgeführt werden)
  • worm_tse_setup (Der Setup wird durchgeführt)

Die Setup Methode ist eine Hilfsmethode die folgenden Aufrufe beinhaltet:

  • worm_user_change_puk
  • worm_user_change_pin
  • worm_tse_registerTaxId
  • worm_tse_ers_enable
  • worm_tse_registerClient
  • worm_tse_runSelfTest
  • worm_tse_initialize


Kontrolle ob TSE Einheit richtig konfiguriert wurde:

Die Funktionen müssen folgende Werte zurückgeben.

  • worm_info_isErsInterfaceActive = 1
  • worm_info_initializationState = 1
  • worm_info_hasPassedSelfTest = 1


enum WormInitializationState {
    Uninitialized = 0,
    Initialized = 1,
    Decommissioned = 2
}


PEM Datei auslesen

Die PEM Datei kann mit dem Befehl ausgelesen werden

worm_getLogMessageCertificate

Dieser gibt das Zertifikat zurück, dass man benötigt, um die Signaturen und zu überprüfen. Vorerst ist es noch notwendig aus dem Zertifikat den publicKey zu lesen und in den QR-Code zu schreiben. Aus dem Zertifikat kann man auch den Signaturalgorithmus lesen. Da sich das Zertifikat für eine TSE nicht ändert, müssen diese Daten nur einmal gelesen werden.


Starten (TSE wurde erfolgreich konfiguriert)

Wurde die TSE erfolgreich konfiguriert, dann muss nach dem WormLogin zyklisch die Zeit gesetzt werden.

  • worm_init (mit Laufwerk Buchstabe)
  • worm_tse_runSelfTest (muss als 1. Kommando nach dem worm_init gesendet werden)
  • worm_user_login (mit Pin und Type ( 1= Admin, 2=TimeAdmin))
  • worm_tse_ers_enable (damit überhaupt Transaktionen gemacht werden. Default Wert ist nicht aktiv)
  • worm_info_new (Neues worm_info wird erstellt)
  • worm_info_read (Um das Zeitintervall zu bekommen)
  • worm_info_maxTimeSynchronizationDelay (Gibt das Intervall zurück in welchem worm_tse_updateTime aufgerufen werden muss)
  • Timer Thread starten(welcher alle x Sekunden worm_tse_updateTime aufruft)


Transaktionen

Die Transaktionen sind der Hauptbestandteil der TSE. Diese sollten immer nach dem gleichen Schema ablaufen. Die Transaktion wird ohne Daten gestartet und danach mit Daten geschlossen.

Um Transaktionen durchzuführen benötigt man folgende Funktionen aus der API:

  • worm_transaction_response_new (Um Platz für die Informationen aus einer Transaktion zu machen)
  • worm_transaction_start (Daten sind immer leer, es werden Infos in die TransactionResponse geschrieben)
  • worm_transaction_finish (Hier werden die benötigten Daten übertragen, es werden Infos in die TransactionResponse geschrieben)
  • worm_transaction_response_logTime (Die Zeit der Transaktion)
  • worm_transaction_response_serialNumber (Die Seriennummer der TSE auf welchem die Transaktion durchgeführt wurde)
  • worm_transaction_response_signatureCounter (Der neue Signaturzähler)
  • worm_transaction_response_signature (Die Signatur)
  • worm_transaction_response_transactionNumber (Die Transaktionsnummer)

Es wird für jede worm_transaction_start und für jede worm_transaction_end eine eigene LogNachricht in der TSE geschrieben. Das heißt, man muss die Informationen direkt nach einem erfolgreichen Aufruf der worm_transaction_start lesen und wieder bei einem erfolgreichen Aufruf der worm_transaction_end.

Es gibt drei verschiedene Transaktionstypen:

Bestellung, Kassenbeleg und sonstiger Vorgang (ist hier irrelevant).

Wie die jeweiligen Datensätze für worm_transaction_finish aussehen ist in „Anlage zur DSFinV-K“ ersichtlich.

Eine Bestellungs-Transaktion wird durchgeführt, nachdem einer oder mehrere Artikel boniert wurden. Die Kassenbelegs-Transaktion wird durchgeführt, sobald die Rechnung gedruckt wird.


Notwendige Informationen auf der Rechnung

Auf der Rechnung werden diverse Informationen benötigt, welche man nach der worm_transaction_start bzw. worm_transaction_finish gelesen hat.

  • TSE-Signature - Finish-Transaktion (worm_transaction_response_signature)
  • TSE-Transaktionsnummer - Finish-Transaktion (worm_transaction_response_transactionNumber)
  • TSE-Start Zeitpunkt - Start-Transaktion (worm_transaction_response_logTime )
  • TSE-Stop Zeitpunkt - Finish-Transaktion (worm_transaction_response_logTime)
  • TSE-Seriennummer - Finish-Transaktion (worm_info_tseSerialNumber-Diese Seriennummer muss als octet dargestellt werden)
  • TSE-sigcount - Finish-Transaktion (worm_transaction_response_signatureCounter)
  • TSE-starttimefirstorder (LogTime der ersten Bestell-Transaktion auf diesem Tisch (logTime der Start-Transaktion))
  • TSE-ZeitFormat - bleibt für TSE gleich (Kann aus den Logs gelesen werden oder einfach als Konfiguration eingetragen werden)
  • TSE-PublicKey – bleibt für TSE gleich (Kann aus dem Zertifikat gelesen werden)
  • TSE- Signatur Algorithmus - bleibt für TSE gleich (Kann aus dem Zertifikat gelesen werden)


QR Code

Der QR-Code enthält nochmals alle Daten der Rechnung im vorgegebenen Format (dieses ist auch in „„Anlage zur DSFinV-K“ ersichtlich“). Ein Beispiel:

V0;SwissbitDemo;KassenBeleg-V1;Beleg^6.90_0.00_0.00_0.00_0.00^6.90:Bar;25;125;2019-07-30T14:40:33.000Z;2019-07-30T14:40:34.000Z;SHA256withECDSA;unixTime;MEQCIHQRwSL6tvG3DoffVxVVR7ylGLrCRrlsgO08xls019QuAiBO2Qx3mHC1XdajX13Y7PNQ4TXmf3e4g4iagoxqpuaTLg==;BKRaS+BAaTnwCJPHLFUY1UYk88UXNFOPOjelUVSh1vBCRBNefihVIejklN4n9bIPBdFbnY265YgzxUq9ys9hXig=


Version

V0

Id

SwissbitDemo

processType

KassenBeleg-V1

processData

Beleg^6.90_0.00_0.00_0.00_0.00^6.90:Bar

Tranakktionsnummer

25

Signatur Zähler

125

Start Zeit

2019-07-30T14:40:33.000Z

LogZeit

2019-07-30T14:40:34.000Z

Signatur Algo.

SHA256withECDSA

Zeit Format

unixTime

Signatur

MEQCIHQRwSL6tvG3DoffVxVVR7ylGLrCRrlsgO08xls019QuAiBO2Qx3mHC1XdajX13Y7PNQ4TXmf3e4g4iagoxqpuaTLg==

Public Key

BKRaS+BAaTnwCJPHLFUY1UYk88UXNFOPOjelUVSh1vBCRBNefihVIejklN4n9bIPBdFbnY265YgzxUq9ys9hXig=


Probleme und Lösungen


PIN und PUK Probleme

Hier kann man ein Factory-Reset durchführen. Im Auslieferungszustand steht die Funktionen Factory-Reset nicht mehr zur Verfügung stehen.


Problem mit der MicroSD Karte

Wird bei dem Laufwerk mit dem Namen „SWISSBIT“ ein SD-Card-Icon in der Laufwerksübersicht angezeigt, so wird die TSE-Verbindung nicht funktionieren. Ist dies der Fall, so muss im Gerätemanager der USB-Controller „USB-Root-Hub (USB 3.0)“ deinstalliert werden. Sollte eine Abfrage zum komplett löschen des Treibers aufgehen, so bestätigt man diese. Anschließend muss der PC neugestartet werden

Lösung:

Diesen Treiber und die Treibersoftware löschen:

Und dann auch noch die Treibersoftware für diese Gerät löschen. Wird die SD Karte dann wieder in den USB Port gegeben soll es ohne Icon dargestellt werden.

Die SD Karte funktioniert ohne weiter Aktionen, sofern sie richtig konfiguriert wurde.