Dokumentation

Übersicht

Der fiskaly-Client ist ein zustandsloser HTTP-Client, der Anfragen bearbeitet, über eine clientseitige Validierung für das Anfrage-Schema verfügt und mit der SMAERS-Komponente kommuniziert. Er wird als ein Satz gemeinsam genutzter Bibliotheken für verschiedene Betriebssysteme und Architekturen auf unserer Download-Seite ausgeliefert. Der Client verwendet eine leicht angepasste Version des JSON-RPC 2.0-Protokolls zur Beschreibung von Anfragen, Antworten und Fehlern. Die einzige Abweichung betrifft Benachrichtigungen, welche nicht unterstützt werden und eine Fehlermeldung produzieren. Bitte stellen Sie sicher, dass Sie mit der JSON-RPC 2.0-Spezifikation vertraut sind, bevor Sie fortfahren.

Changelog

v1.1.100. (06.04.2020)

Bugfix

  • fix: Validator an v1 Änderungen angepasst

Verschönerung

  • refactor: kleine Änderung am user-agent Header

v1.1.0. (02.04.2020)

Funktionalität

  • Methode: echo
    • Gibt den exakt gleichen String zurück
    • Wird verwendet um die Enkodierung und die Kommunikation zwischen Client und SDK zu prüfen
  • Fehler: http-timeout-error
    • Wird geworfen sobald der Timeout bei einem HTTP-Request überschritten wird
  • Fehler: request-error
    • Wird geworfen wenn das Format der Anfrage fehlerhaft ist

Fehlerbehebung

  • fix: config liefert nun das Ergebnis korrekt zurück
  • fix: Validierung des Request-Bodies nur noch bei Anfragen an API v1
  • fix: SMAERS Version wird nun richtig dargestellt

Verschönerung

  • refactor: request-Parameter wurden nun zusammengefasst und vom Kontext getrennt
  • refactor: client-erros wurden entfernt
  • refactor: http-error liefert nun die Antwort des Servers gebündelt in einem Objekt
  • refactor: debug-file verwendet nun den standardmäßigen tmp-Ordner des jeweiligen Betriebssystems falls nicht anders gesetzt

Funktionen

Der fiskaly-Client exportiert zwei Funktionen:

_fiskaly_client_invoke(CString) CString

_fiskaly_client_invoke wird verwendet, um eine JSON-RPC 2.0-Methode aufzurufen. Sie nimmt eine vollständige JSON-RPC 2.0-Anfrage als Argument und gibt die Antwort des Clients zurück.

_fiskaly_client_free(CString)

_fiskaly_client_free wird verwendet, um den von Invoke zugewiesenen Speicher freizugeben.

Methoden

Die mit einem Stern (*) gekennzeichneten Parameter sind optional.

Konfiguration

Anfrage

{
"jsonrpc": "2.0",
"method": "config",
"params": {
* "config": {
* "debug_level": int,
* "debug_file": string,
* "client_timeout": int(ms),
* "smaers_timeout": int(ms)
},
"context": string
},
"id": int
}

Antwort

{
"jsonrpc": "2.0",
"result": {
"config": {
"debug_level": int,
"debug_file": string,
"client_timeout": int,
"smaers_timeout": int
},
"context": string
},
"id": int
}

Mit der config-Methode können Sie den Client konfigurieren und die aktuelle Konfiguration lesen. Sie gibt immer alle Konfigurationsparameter zurück. Sie können Timeouts für Client und SMAERS unabhängig voneinander einstellen, den Debug-Modus aktivieren und seine Ausgabe konfigurieren. Eine ausführliche Beschreibung des Debug-Modus finden Sie weiter unten auf dieser Seite. Alle angegebenen Parameter aus dem config-Feld werden in die Konfiguration geschrieben. Wenn Sie die Konfiguration nur lesen möchten, können Sie das Feld config vollständig aus der Anfrage auslassen.

Neuen Kontext erzeugen

Anfrage

{
"jsonrpc": "2.0",
"method": "create-context",
"params": {
"base_url": string,
"api_key": string,
"api_secret": string
},
"id": int
}

Antwort

{
"jsonrpc": "2.0",
"result": {
"context": string
},
"id": int
}

Um sicherzustellen, dass der fiskaly-Client zustandslos (stateless) ist, verwenden wir eine Kontextzeichenfolge, die alle benötigten Informationen enthält. Dieser String muss mit jeder Methode (außer der Versionsmethode) gesendet werden und wird auch in jeder Antwort zurückgegeben. Stellen Sie sicher, dass Sie Ihren gespeicherten Kontext mit dem aus der Antwort zurückgegebenen aktualisieren.

Um eine unbeabsichtigte Änderung zu verhindern, wird der Kontext zusammen mit seinem sha256-Hash in eine base64-Zeichenkette kodiert. Es wird empfohlen, den Kontext als schreibgeschützt zu behandeln und nur die bereitgestellten Methoden zu verwenden, um seinen Inhalt zu ändern.

API Anfrage

Anfrage

{
"jsonrpc": "2.0",
"method": "request",
"params": {
"request": {
"method": string,
"path": string,
* "query": json_object,
* "headers": json_object,
* "body": base64_string,
* "destination_file": string
},
"context": string
},
"id": int
}

Antwort

{
"jsonrpc": "2.0",
"result": {
"response": {
"status": string,
"header": json_object,
"body": base64_string
},
"context": string
},
"id": int
}

Die Anfragemethode wird zum Senden von HTTP-Anfragen verwendet. Die URL setzt sich aus der im Kontext definierten Basis-URL und dem path der Anfrage zusammen. Der Client validiert Ihre Eingaben automatisch. Im Falle einer Anfrage an den Transaktionsendpunkt der KassenSichV-API validiert der Client auch den body der Anfrage und signiert ihn mit Hilfe der SMAERS-Komponente.

Wenn Sie beabsichtigen, eine Datei von einer unserer APIs herunterzuladen (z.B. im Falle eines Exports in der KassenSichV API), können Sie einen Zieldateipfad angeben. Der Client speichert dann die empfangenen Daten in dieser Datei. Die JSON-RPC-Antwort enthält in diesem Fall keinen body.

Version

Anfrage

{
"jsonrpc": "2.0",
"method": "version",
"params": {},
"id": int
}

Antwort

{
"jsonrpc": "2.0",
"result": {
"client": {
"version": string,
"source_hash": string,
"commit_hash": string
},
"smaers": {
"version": string,
"commit_hash": string
}
},
"id": int
}

Die Versionsmethode gibt die Versionsinformationen des aktuell verwendeten Clients und SMAERS zurück.

Echo

Anfrage

{
"method": "echo",
"params": json_object
}

Antwort

{
"result": json_object
}

Die Echo Methode liefert das params-Feld der Anfrage unverändert zurück. Dies dient als Überprüfung der UTF-8 Kodierung in den SDKs.

Fehler

Der fiskaly-Client gibt die in der JSON-RPC 2.0-Spezifikation definierten Fehlermeldungen zurück. Um detailliertere Informationen über die Fehlerursache zu erhalten, können die folgenden zusätzlichen, benutzerdefinierten Fehler vom fiskaly-Client zurückgegeben werden:

HTTP Fehler

{
"jsonrpc": "2.0",
"error": {
"code": -20000,
"message": "HTTP error",
"data": {
"response": {
"status": 400,
"headers": {
"X-Request-Id": ["0123456789"]
},
"body": base64_string
}
}
},
"id": int
}

HTTP Zeitüberschreitung

{
"jsonrpc": "2.0",
"error": {
"code": -21000,
"message": "HTTP timeout"
},
"id": int
}

Anfragefehler

{
"jsonrpc": "2.0",
"error": {
"code": -7353,
"message": "Request Error"
},
"id": int
}

Debug Modus

Zur Unterstützung der Fehlerbehebung enthält der fiskaly-Client einen Debug-Modus. Wenn er aktiviert ist, werden Informationen mit variabler Granularität in eine Protokolldatei geschrieben. Die Ausführlichkeit wird durch das debug_level-Feld in der Konfiguration gesteuert. Gültige Debug-Level sind -1 (keine Ausgabe), 1 (nur Fehler), 2 (Fehler+Warnungen) und 3 (Fehler+Warnungen+Info). Die Ausgabedatei kann auch über die Methode config gesetzt werden. Die Voreinstellung ist /tmp/fiskaly.log.

Integration

1. Laden Sie die gemeinsame Bibliotheksdatei

Der Client wird als native Bibliothek für gängige Zielplattformen bereitgestellt. Die implementierungsspezifischen Details variieren je nach Programmiersprache, daher können in diesem Zusammenhang keine detaillierten Anweisungen gegeben werden. Die erforderlichen Funktionssignaturen können dem Abschnitt Funktionen dieses Dokuments entnommen werden. Da alle unsere SDKs OSS sind, können Sie sie jederzeit als Referenzimplementierung verwenden.

2. Einen neuen Kontext erzeugen

Der zurückgegebene Kontext enthält die bereitgestellten Parameter und die Standardkonfiguration. Speichern Sie den Kontext für eine zukünftige Wiederverwendung und senden Sie ihn bei jeder Anfrage. Jeder Methodenaufruf kann den Kontext ändern, daher ist es wichtig, den gespeicherten Kontext immer mit dem zurückgegebenen zu aktualisieren. Eine direkte Änderung des Kontexts kann zu undefiniertem Verhalten führen, daher wird davon dringend abgeraten.

{
"jsonrpc": "2.0",
"method": "create-context",
"params": {
"api_key": "example_uj3hBUmddscBeWYeU9HRpFjgqp4ZTf",
"api_secret": "gBmxxMXN5s4wVuKaaEZCKMGxrZEBJl0iRZfiAbBZefq",
"base_url": "https://kassensichv.io/api/v1/"
},
"id": 1
}

3. Benutzerdefinierte Einstellungen hinzufügen

Dieser Schritt ist optional und nur erforderlich, wenn Sie die Standardkonfigurationsparameter überschreiben wollen.

{
"jsonrpc": "2.0",
"method": "config",
"params": {
"config": {
"debug_level": 2,
"debug_file": "/var/log/fiskaly.log",
"client_timeout": 5000,
"smaers_timeout": 2000
},
"context": "T4QgYdRI6YH7vS_CBw0io7R2uK6DgCd3n2kW0TUdcBZ7IndyYXBwZXJfdmVyc2lvbiI6Ik5vIFdyYXBwZXIgVmVyc2lvbiIsImFwaV9rZXkiOiJleGFtcGxlX3VqM2hCVW1kZHNjQmVXWWVVOUhScEZqZ3FwNFpUZiIsImFwaV9zZWNyZXQiOiJnQm14eE1YTjVzNHdWdUthYUVaQ0tNR3hyWkVCSmwwaVJaZmlBYkJaZWZxIiwiYmFzZV91cmwiOiJodHRwczovL2thc3NlbnNpY2h2LmlvL2FwaS92MS8iLCJhY2Nlc3NfdG9rZW4iOiIiLCJyZWZyZXNoX3Rva2VuIjoiIiwiYWNjZXNzX3Rva2VuX2V4cGlyZXNfYXQiOjAsInJlZnJlc2hfdG9rZW5fZXhwaXJlc19hdCI6MCwiY29uZmlnIjp7ImRlYnVnX2xldmVsIjotMSwiY2xpZW50X3RpbWVvdXQiOjEwMDAsInNtYWVyc190aW1lb3V0IjoxMDAwfX0"
},
"id": 2
}

4. Anfragen senden

Die request Methode empfängt und gibt den Nachrichtenkörper als base64-kodierte Binärdaten zurück. Dadurch kann jedes Datenformat hoch- und heruntergeladen werden.

{
"jsonrpc": "2.0",
"method": "request",
"params": {
"request": {
"method": "PUT",
"path": "/tss/ecb75169-680f-48d1-93b2-52cc10abb9ff/tx/9cbe6566-e24c-42ac-97fe-6a0112fb3c63",
"query": { "last_revision": "0" },
"headers": { "Content-Type": "application/json" },
"body": "eyJzdGF0ZSI6ICJBQ1RJVkUiLCJjbGllbnRfaWQiOiAiYTYyNzgwYjAtMTFiYi00MThhLTk3MzYtZjQ3Y2E5NzVlNTE1In0="
},
"context": "aYqkp0feiGAiyKfcNu9sp0whSGCvaoykbmeC-R90Qcx7IndyYXBwZXJfdmVyc2lvbiI6Ik5vIFdyYXBwZXIgVmVyc2lvbiIsImFwaV9rZXkiOiJleGFtcGxlX3VqM2hCVW1kZHNjQmVXWWVVOUhScEZqZ3FwNFpUZiIsImFwaV9zZWNyZXQiOiJnQm14eE1YTjVzNHdWdUthYUVaQ0tNR3hyWkVCSmwwaVJaZmlBYkJaZWZxIiwiYmFzZV91cmwiOiJodHRwczovL2thc3NlbnNpY2h2LmlvL2FwaS92MS8iLCJhY2Nlc3NfdG9rZW4iOiIiLCJyZWZyZXNoX3Rva2VuIjoiIiwiYWNjZXNzX3Rva2VuX2V4cGlyZXNfYXQiOjAsInJlZnJlc2hfdG9rZW5fZXhwaXJlc19hdCI6MCwiY29uZmlnIjp7ImRlYnVnX2xldmVsIjoyLCJkZWJ1Z19maWxlIjoiL3Zhci9sb2cvZmlza2FseS5sb2ciLCJjbGllbnRfdGltZW91dCI6NTAwMCwic21hZXJzX3RpbWVvdXQiOjIwMDB9fQ"
},
"id": 3
}

Body-Enkodierung Beispiel

Klartext (JSON)

{
"body": {
"some-field": 23,
"another-field": "hello, world"
}
}

Base64 enkodiert

{
"body": "ewogICAgInNvbWUtZmllbGQiOiAyMywKICAgICJhbm90aGVyLWZpZWxkIjogImhlbGxvLCB3b3JsZCIKICB9"
}

5. Datei-Download

Um den Response-Body in einer Datei zu speichern, geben Sie einen Wert für das destination_file-Feld an. HTTP-Status und Header-Informationen werden weiterhin in der Antwort zurückgegeben, aber der Body wird in den angegebenen Dateipfad geschrieben.

{
"jsonrpc": "2.0",
"method": "request",
"params": {
"request": {
"destination_file": "/tmp/output.txt",
"method": "GET",
"path": "/something"
},
"context": "aYqkp0feiGAiyKfcNu9sp0whSGCvaoykbmeC-R90Qcx7IndyYXBwZXJfdmVyc2lvbiI6Ik5vIFdyYXBwZXIgVmVyc2lvbiIsImFwaV9rZXkiOiJleGFtcGxlX3VqM2hCVW1kZHNjQmVXWWVVOUhScEZqZ3FwNFpUZiIsImFwaV9zZWNyZXQiOiJnQm14eE1YTjVzNHdWdUthYUVaQ0tNR3hyWkVCSmwwaVJaZmlBYkJaZWZxIiwiYmFzZV91cmwiOiJodHRwczovL2thc3NlbnNpY2h2LmlvL2FwaS92MS8iLCJhY2Nlc3NfdG9rZW4iOiIiLCJyZWZyZXNoX3Rva2VuIjoiIiwiYWNjZXNzX3Rva2VuX2V4cGlyZXNfYXQiOjAsInJlZnJlc2hfdG9rZW5fZXhwaXJlc19hdCI6MCwiY29uZmlnIjp7ImRlYnVnX2xldmVsIjoyLCJkZWJ1Z19maWxlIjoiL3Zhci9sb2cvZmlza2FseS5sb2ciLCJjbGllbnRfdGltZW91dCI6NTAwMCwic21hZXJzX3RpbWVvdXQiOjIwMDB9fQ"
},
"id": 4
}
Last updated on