fiskaly KassenSichV client for Java

The fiskaly KassenSichV client is an HTTP client that is needed¹ for accessing the kassensichv.io API that implements a cloud-based, virtual CTSS (Certified Technical Security System) / TSE (Technische Sicherheitseinrichtung) as defined by the German KassenSichV (Kassen­sich­er­ungsver­ord­nung).

Conceptually this client is a thin (convenience) wrapper around the OkHttp library for Java. This means you will have to look up the API documentation of OkHttp to learn how this client is used. From a developer's point of view, the only difference is that you have to instantiate your OkHttpClient through the ClientFactory provided by the SDK.

Be sure to have a look at our integration guide / tutorial.

Features

• Automatic authentication handling (fetch/refresh JWT and re-authenticate upon 401 errors).
• Automatic retries on failures (server errors or network timeouts/issues).
• Automatic JSON parsing and serialization of request and response bodies.
• Future: [1] compliance regarding BSI CC-PP-0105-2019 which mandates a locally executed SMA component for creating signed log messages.
• Future: Automatic offline-handling (collection and documentation according to Anwendungserlass zu § 146a AO)

Build project

First of all, you have to initialize the required git submodule(s) using:

$ git submodule update --init

The project uses Gradle as a build and dependency management tool. In order to build the project, use the following command:

$ ./gradlew jar

This will result in multiple JAR-files for each sub-project that can be used in your project.

Each built library will be available at <sub-project-name>/build/libs/<sub-project-name>-<version>.jar.

Integration

Be sure to have a look at our integration guide / tutorial.

To integrate the client into your project, use the appropriate client build for your target platform.

• client/build/libs/com.fiskaly.kassensichv.client.general-<version>.jar for standard Java platforms
• client/build/libs/com.fiskaly.kassensichv.client.android-<version>.jar for Android

Usage example

The following example demonstrates how to instantiate an OkHttpClient using the SDK as well as how to issue requests against the KassenSichV-API.

public class Main {
  // com.fasterxml.jackson.databind.ObjectMapper
  private static final ObjectMapper mapper = new ObjectMapper(); 

  public static void Main(String[] args) {
    // Instantiate the appropriate SMA implementation for your target platform
    GeneralSMA sma = new GeneralSMA();

    // Instantiate the OkHttpClient using the provided Factory class
    OkHttpClient client = ClientFactory.getClient(apiKey, apiSecret, sma);

    // Create a basic TSS

    Map<String, String> tssMap = new HashMap<>();

    tssMap.put("state", "INITIALIZED");
    tssMap.put("description", "An example TSS");

    String jsonBody = mapper.writeValueAsString(tssMap);

    RequestBody body = RequestBody.create(jsonBody, MediaType.parse("application/json"));
    UUID uuid = UUID.randomUUID();

    Request request = new Request
        .Builder()
        .url("https://kassensichv.io/api/v0/tss/" + uuid)
        .put(body)
        .build();

    Response response = client
        .newCall(request)
        .execute();
  }
}

Enable Offline Functionality (Beta)

To enable offline functionality, use this factory call to instantiate an OkHttpClient:

OkHttpClient betaClient = ClientFactory.getPersistingClient(apiKey, secret, sma, persistenceStrategy);

The PersistanceStrategy interface defines a contract for a concrete persistence implementation (read more about the strategy pattern here).

A demo implementation for standard JVM platforms based on SQLite can be found in com.fiskaly.kassensichv.general.persistance.SqliteStrategy.java

Related

• fiskaly.com
• dashboard.fiskaly.com
• kassensichv.io
• kassensichv.net