Skip to main content

Dokumentation

info

this section will be revised and adapted for the certified version 2 of the the fiskaly Cloud-TSS! Version 2 does not need a client or service, you can integrate with a pure HTTPS version.

├ť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#

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),
* "http_proxy": string
},
"context": string
},
"id": int
}

Antwort#

{
"jsonrpc": "2.0",
"result": {
"config": {
"debug_level": int,
"debug_file": string,
"client_timeout": int(ms),
"smaers_timeout": int(ms),
"http_proxy": string
},
"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. Wenn Sie den Systemproxy ignorieren m├Âchten, verwenden Sie "http_proxy": "-". Um den Logger auf stdout loggen zu lassen verwenden Sie den Wert -.

Neuen Kontext erzeugen#

Anfrage#

{
"jsonrpc": "2.0",
"method": "create-context",
"params": {
"base_url": string,
* "api_key": string,
* "api_secret": string,
* "email": string,
* "password": string,
* "organization_id": string,
* "environment": 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. Je nachdem welche Authentifizierungsmethode Sie verwenden m├Âchten, entweder mit dem API-Schl├╝ssel oder per E-Mail und Passwort (letzteres kann nur in der Management API verwendet werden), m├╝ssen Sie die ben├Âtigten Parameter ├╝bergeben. Diese sind entweder api_key und api_secret oder email und password. Sie k├Ânnen jedoch auch alle Parameter ├╝bergeben. Falls dies der Fall ist, priorisiert der Client die Authentifizierung per E-Mail, sofern die base_url die der Management API ist. Ansonsten verwendet der Client immer api_key und api_secret.

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": int,
"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
}
},
"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.

Selbsttest#

Anfrage#

{
"method": "self-test",
"params": {
"context": string
}
}

Antwort#

{
"result": {
"proxy": string,
"backend": string,
"smaers": string
}
}

Die Selbsttest-Methode ├╝berpr├╝ft den internen Status des Clients und der SMAERS und versucht, eine Verbindung zur fiskaly API aufzubauen. Sie liefert die Ergebnisse der einzelnen Tests zur├╝ck.

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. Wenn Sie m├Âchten die Protokolldatei in Stdout schreiben, verwenden Sie "debug_file": "-".

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,
"http_proxy": "http://127.0.0.1:8080"
},
"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
}

Subscribe to the Dev-Newsletter