Dokumentation
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 SIGN DE 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 SIGN DE 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
}