fiskaly TSS / TSE API (0.5.0-draft)

Introduction

The fiskaly TSS / TSE API is a RESTful 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).

The fiskaly TSS / TSE API is a platform independent software-only solution, that is completely free of any additional hardware dongles. A working Internet connection is the only technical requirement for integrating our solution.

As a RESTful API, the fiskaly TSS / TSE API:

  • has resource-oriented URLs;
  • accepts JSON-encoded request bodies;
  • returns JSON-encoded responses;
  • uses standard HTTP status codes and verbs;
  • and is easy to integrate with your system.

*Note, that our system is not certified (yet)! We strive for a successful certification as soon as possible. As the technical guidelines and regulations are not final, the API is still under development and slight changes are therefore to be expected.

Security Module Application for Electronic Record-keeping Systems

An important part of the Technical Security System is the Security Module Application for Electronic Record-keeping Systems (SMA or SMAERS) component.

Note, that the SMAERS component must be used in the operational environment of the taxpayer.

fiskaly provides SMAERS libraries for many platforms (fiskaly-kassensichv-sma repository on GitHub). The libraries for production environments will be available after (preliminary) release for operation by the BSI.

In addition, fiskaly offers open source software for many platforms and programming languages to access these libraries and our services. These include additional features such as automatic authentication handling and automatic retry of failed requests. Have a look at our GitHub repositories:

Is your platform or programming language missing? Tell us.

Background

Our API implements and unifies a complex and intertwined set of legal requirements, technical guidelines and regulations. For the reference, the current version 0.5.0-draft of this API is based on the following set of artifacts:

Versioning

Our API follows Semantic Versioning.

That means, given a version number MAJOR.MINOR.PATCH, we increment the:

  • MAJOR version when we make incompatible API changes,
  • MINOR version when we add functionality in a backwards-compatible manner, and
  • PATCH version when we make backwards-compatible bug fixes.

The current MAJOR version 0 is reflected in the APIs base URL: /api/v0.

Changelog

  • 0.5.0-draft:
  • 0.4.0-draft:
    • The type of a transaction is now defined as string.
    • When starting a transaction (i.e. revision 0 of a transaction) type and data do not need to be supplied anymore (cf. DSFinV-K).
    • Timestamps are now provided and expected in seconds granularity.
    • TSS objects have the properties:
      • certificate: EC certificate
      • certificate_serial
      • public_key
      • signature_counter
      • transaction_counter
    • Client objects do no longer have the properties certificate_serial, public_key, signature_counter.
  • 0.3.0-draft:
  • 0.2.0-draft:
    • Support of DFKA transaction taxonomy has been added as a structured alternative to binary data. The transaction data schema has slightly changed
      • from
          {
            "data": {
              "schema": "DFKA",
              "data": { ... }
            }
          }
      • to
          {
            "data": {
              "dfka": { ... }
            }
          }
    • Support of authentication with api_key and api_secret has been added.
      • The new authentication mechanism supersedes the former way of authentication using api_key only.
    • List endpoints now return full objects (i.e., items in a list operation have the same set of properties as items retrieved by the corresponding get operation).
    • The type of a process (formerly string) now is defined as an enumeration (in accordance with Anwendungserlass zu § 146a AO).
    • Some properties of the Transaction resource have changed:
      • from begin_timestamp to time_start
      • from end_timestamp to time_end
      • from max_revision to latest_revision
    • Timestamps now have millisecond granularity (instead of second granularity).
    • Sort options (i.e., order_by a specific property) and filters (e.g., to filter for transactions in ACTIVE state) have been added to list operations.

Limitations

  • The system is not certified. That is, it is not meant for production use.
  • Cryptographic methods are subject to change in future releases. Such changes are however not expected to affect the interface of the system.
  • Software Development Kits (SDKs) have not yet been released.
  • The current test setup does not guarantee high availability.
  • The data in this test setup may be deleted at any time without prior notice.

Idempotent Requests

A core concept of API is Idempotence. Idempotence allows for safely retrying requests while side effects are guaranteed to happen exactly once.

This is useful when an API request is disrupted in transit and you never receive a response from our servers. For example, if a request to start a transaction does not respond due to a network connection error, you can retry the request with the same request body to guarantee that no more than one transaction is started.

Errors and Status Codes

Our API uses standard HTTP status codes to indicate the success or failure of requests:

Status 2xx

Status codes in the 200-299 range indicate success.

Status 4xx

Status codes in the 400-499 range indicate errors that have been caused by the client (e.g., a malformed request body has been sent).
Retrying such requests with the same request body is pointless and will result in the same status code again. Some 4xx errors can be handled programmatically may therefore include an additional error code like the following example:

{
  "status_code": 400,
  "error": "Bad Request",
  "code": "E_SOME_ERROR",
  "message": "Something bad happened"
}

Status 5xx

Status codes in the 500-599 range indicate errors on our side. Errors on our side can be considered temporary. This means that you may safely retry (see Idempotent Requests) the same request after a certain delay. We recommend an exponential backoff in your retry logic. Otherwise you might risk running into a 429 (Too Many Requests) error.

Request IDs

For each request, our API associates a unique request identifier to it. You will find this request identifier in the response headers, under X-Request-ID. If you need to contact us about a specific request (e.g. for debugging porposes) you have issued, please be sure to include the request identifier as this will greatly facilitate resolution on both sides.

Metadata

Another concept of our API is custom, user-defined metadata. Most resources in our API (e.g. Transactions) include a metadata property, that can be used to attach and store additional, structured information suchs resources.

For example, you could store a unique identifier for a particular receipt or invoice from your system on Transaction object. That way, you can effectively link a Transaction in our API to thr corresponding receipt / invoice in your system.

Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Quick Start

For a quick first demo, you may use Postman. We prepared a Postman collection that allows you to step through the most important functions of this API.

  1. First of all, download the Postman application.

  2. Create an API key and secret via the fiskaly dashboard.

  3. Insert your API key and secret in order to obtain your personalized Postman environment:

  4. Download the Postman collection.

  5. Start Postman and import the downloaded Postman collection and environment files.

    File > Import (Ctrl+O)

  6. Select the imported environment.

  7. Run the demo.

    Run > Run fiskaly demo ...

Authentication

Our API uses JWT tokens to authenticate requests. API requests without authentication will fail. All API requests have to be made over HTTPS, while requests made over plain HTTP will fail.

JWT

A JSON Web Token (JWT) used for access control and authorization.

API keys have to be obtained via the fiskaly dashboard.

  • Usage format: Bearer <JWT>
  • Example HTTP header: Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Security scheme type: HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Retrieve an authorization token

Access to our API is only granted with a valid JWT / authorization token that must be obtained using this endpoint.

Note: If you don't have an api_key yet, you can request an API key.

Request Body schema: application/json
One of
  • object
  • object
api_key
required
string
api_secret
required
string

Responses

200

Successful authentication

post /auth
/api/v0/auth

Request samples

application/json
Copy
Expand all Collapse all
{
  • "refresh_token": "string",
  • "api_key": "...",
  • "api_secret": "..."
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "access_token": "string",
  • "access_token_expires_in": 300,
  • "access_token_expires_at": 1577833200,
  • "refresh_token": "string",
  • "refresh_token_expires_in": 300,
  • "refresh_token_expires_at": 1577833200
}

Technical Security Systems

Endpoints for initialization and management of a Technical Security System (Technische Sicherheitseinrichtung).

List TSS

List Technical Security Systems.

Authorizations:
query Parameters
order_by
string
Enum:"description" "state" "time_creation" "time_init" "time_disable"

Specifies the property to sort by

order
string
Default: "asc"
Enum:"asc" "desc"

Determines the sorting order

limit
integer <= 100
Default: 100

Limits the number of returned results

offset
integer
Default: 0

Skips the specified number of results from the result set

states
Array of strings
Items Enum:"UNINITIALIZED" "INITIALIZED" "DISABLED"
Example: "states%5B0%5D=DISABLED&states%5B1%5D=INITIALIZED"

Filter to include only specific states

Responses

200

Returns the TSS list

get /tss
/api/v0/tss

Request samples

Copy

curl "https://kassensichv.io/api/v0/tss" \
-H "Authorization: Bearer ..." \
-X GET
          

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ],
  • "count": 0,
  • "_type": "TSS_LIST"
}

Retrieve a TSS

Returns information about an existing TSS.

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

Responses

200

Returns the TSS resource

404

TSS does not exist.

get /tss/{tss_id}
/api/v0/tss/{tss_id}

Request samples

Copy

curl "https://kassensichv.io/api/v0/tss/00000000-0000-0000-0000-000000000000" \
-H "Authorization: Bearer ..." \
-X GET
          

Response samples

application/json
Copy
Expand all Collapse all
{
  • "description": "Cash Register 1",
  • "state": "UNINITIALIZED",
  • "metadata":
    {},
  • "time_creation": 1577833200,
  • "time_init": 1577833200,
  • "time_disable": 1577833200,
  • "certificate": "string",
  • "certificate_serial": "string",
  • "public_key": "string",
  • "signature_counter": 0,
  • "transaction_counter": 0,
  • "_id": "00000000-0000-0000-0000-000000000000",
  • "_type": "TSS",
  • "_links":
    [
    ]
}

Create or update a TSS

Create or update a TSS with a self-generated UUIDv4 A TSS can be created in an "INITIALIZED" or "UNINITIALIZED" state. State transtions are possible from "UNINITIALIZED" to "INITIALIZED", from "INITIALIZED" to "DISABLED" and from from "UNINITIALIZED" to "DISABLED". The "DISABLED" state is permanent. Only an initialized TSS can generate signed log messages.

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

Request Body schema: application/json
description
string
state
string
Enum:"UNINITIALIZED" "INITIALIZED" "DISABLED"
metadata
object

You can use this parameter to attach custom key-value data to an object. Metadata is useful for storing additional, structured information on an object. Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Responses

200

Returns the TSS resource

400

Bad Request. Invalid TSS state change request.

put /tss/{tss_id}
/api/v0/tss/{tss_id}

Request samples

application/json
Copy
Expand all Collapse all
{ }

Response samples

application/json
Copy
Expand all Collapse all
{
  • "description": "Cash Register 1",
  • "state": "UNINITIALIZED",
  • "metadata":
    {},
  • "time_creation": 1577833200,
  • "time_init": 1577833200,
  • "time_disable": 1577833200,
  • "certificate": "string",
  • "certificate_serial": "string",
  • "public_key": "string",
  • "signature_counter": 0,
  • "transaction_counter": 0,
  • "_id": "00000000-0000-0000-0000-000000000000",
  • "_type": "TSS",
  • "_links":
    [
    ]
}

Retrieve metadata of a TSS

Retrieve additional structured information about a TSS.

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

Responses

200

Returns metadata

404

TSS does not exist.

get /tss/{tss_id}/metadata
/api/v0/tss/{tss_id}/metadata

Response samples

application/json
Copy
Expand all Collapse all
{}

Update metadata of a TSS

Create or update additional structured information about a TSS.

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

Request Body schema: application/json
property name *
string

Responses

200

Returns metadata

404

TSS does not exist.

put /tss/{tss_id}/metadata
/api/v0/tss/{tss_id}/metadata

Request samples

application/json
Copy
Expand all Collapse all
{}

Response samples

application/json
Copy
Expand all Collapse all
{}

Transactions

Endpoints for transactions and their lifecycle.

List transactions of a TSS

Lists transactions of a TSS.

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

query Parameters
order_by
string
Enum:"number" "state" "time_start" "time_end"

Specifies the property to sort by

order
string
Default: "asc"
Enum:"asc" "desc"

Determines the sorting order

limit
integer <= 100
Default: 100

Limits the number of returned results

offset
integer
Default: 0

Skips the specified number of results from the result set

states
Array of strings
Items Enum:"ACTIVE" "FINISHED" "CANCELLED"
Example: "states%5B0%5D=FINISHED&states%5B1%5D=CANCELLED"

Filter to include only specific states

Responses

200

Returns a list of transactions

404

Resource does not exist.

get /tss/{tss_id}/tx
/api/v0/tss/{tss_id}/tx

Request samples

Copy

curl "https://kassensichv.io/api/v0/tss/00000000-0000-0000-0000-000000000000/tx" \
-H "Authorization: Bearer ..." \
-X GET
          

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ],
  • "count": 0,
  • "_type": "TRANSACTION_LIST"
}

List all transactions

List transactions of all available TSS.

Authorizations:
query Parameters
order_by
string
Enum:"number" "state" "time_start" "time_end"

Specifies the property to sort by

order
string
Default: "asc"
Enum:"asc" "desc"

Determines the sorting order

limit
integer <= 100
Default: 100

Limits the number of returned results

offset
integer
Default: 0

Skips the specified number of results from the result set

states
Array of strings
Items Enum:"ACTIVE" "FINISHED" "CANCELLED"
Example: "states%5B0%5D=FINISHED&states%5B1%5D=CANCELLED"

Filter to include only specific states

Responses

200

Returns a list of transactions

404

Resource does not exist.

get /tx
/api/v0/tx

Request samples

Copy

curl "https://kassensichv.io/api/v0/tx" \
-H "Authorization: Bearer ..." \
-X GET
          

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ],
  • "count": 0,
  • "_type": "TRANSACTION_LIST"
}

Retrieve a transaction

Returns information about a transaction (identified by the tx_id_or_number path parameter) in its current revision or a specific revision if the tx_revision query parameter is set.

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

tx_id_or_number
required
string

Identifies a transaction by a tx_uuid (i.e. a self-generated UUIDv4) or a tx_number that gets assigned by us

query Parameters
tx_revision
required
integer [ 1 .. 9007199254740991 ]
Default: 1

Responses

200

Returns the Transaction resource

400

Revision number does not exist.

404

Resource does not exist.

get /tss/{tss_id}/tx/{tx_id_or_number}
/api/v0/tss/{tss_id}/tx/{tx_id_or_number}

Request samples

Copy

curl "https://kassensichv.io/api/v0/tss/00000000-0000-0000-0000-000000000000/tx/00000000-0000-0000-0000-000000000000" \
-H "Authorization: Bearer ..." \
-X GET
          

Response samples

application/json
Copy
Expand all Collapse all
{
  • "number": 0,
  • "time_start": 1577833200,
  • "time_end": 1577833200,
  • "certificate_serial": "string",
  • "type": "string",
  • "state": "ACTIVE",
  • "client_id": "00000000-0000-0000-0000-000000000000",
  • "data":
    {
    },
  • "revision": 1,
  • "latest_revision": 1,
  • "log":
    {
    },
  • "signature":
    {
    },
  • "tss_id": "00000000-0000-0000-0000-000000000000",
  • "metadata":
    {},
  • "_type": "TRANSACTION",
  • "_id": "00000000-0000-0000-0000-000000000000",
  • "_links":
    [
    ]
}

Start, update or finish a transaction

A transaction can be started and updated by specifying the state "ACTIVE" in the request body.

There are two options for ending a transaction:

  1. The state "CANCELLED" can be used to explicitly record the cancellation of a transaction.
  2. The state "FINISHED" can be seen as the usual way for ending a transaction.

Each call must include the parameter last_revision in the query string. After a call, the last_revision is incremented for the next call. The purpose of this variable is the preservation of order of subsequent calls. Furthermore, it is used as a means for the identification of conflicting transaction updates (e.g., two cashiers updating a transaction concurrently).

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

tx_id_or_number
required
string

Identifies a transaction by a tx_uuid (i.e. a self-generated UUIDv4) or a tx_number that gets assigned by us

query Parameters
last_revision
required
integer [ 0 .. 9007199254740991 ]
Default: 0
Request Body schema: application/json
state
required
string
Default: "ACTIVE"
Enum:"ACTIVE" "CANCELLED" "FINISHED"
client_id
required
string <uuid>

Identifies a client by a self-generated UUIDv4

type
string

Identifies the type of the transaction (see processType in TR-03151)

data
object or object or object
metadata
object

You can use this parameter to attach custom key-value data to an object. Metadata is useful for storing additional, structured information on an object. Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Responses

200

Returns the Transaction resource

400

Provided Data is wrong.

404

Resource does not exist.

put /tss/{tss_id}/tx/{tx_id_or_number}
/api/v0/tss/{tss_id}/tx/{tx_id_or_number}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "state": "ACTIVE",
  • "client_id": "00000000-0000-0000-0000-000000000000"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "number": 0,
  • "time_start": 1577833200,
  • "time_end": 1577833200,
  • "certificate_serial": "string",
  • "type": "string",
  • "state": "ACTIVE",
  • "client_id": "00000000-0000-0000-0000-000000000000",
  • "data":
    {
    },
  • "revision": 1,
  • "latest_revision": 1,
  • "log":
    {
    },
  • "signature":
    {
    },
  • "tss_id": "00000000-0000-0000-0000-000000000000",
  • "metadata":
    {},
  • "_type": "TRANSACTION",
  • "_id": "00000000-0000-0000-0000-000000000000",
  • "_links":
    [
    ]
}

Retrieve metadata of a transaction

Retrieve additional structured information about a transaction.

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

tx_id_or_number
required
string

Identifies a transaction by a tx_uuid (i.e. a self-generated UUIDv4) or a tx_number that gets assigned by us

Responses

200

Returns metadata

404

Resource does not exist.

get /tss/{tss_id}/tx/{tx_id_or_number}/metadata
/api/v0/tss/{tss_id}/tx/{tx_id_or_number}/metadata

Response samples

application/json
Copy
Expand all Collapse all
{}

Update metadata of a transaction

Create or update additional structured information about a transaction.

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

tx_id_or_number
required
string

Identifies a transaction by a tx_uuid (i.e. a self-generated UUIDv4) or a tx_number that gets assigned by us

Request Body schema: application/json
property name *
string

Responses

200

Returns metadata

404

Resource does not exist.

put /tss/{tss_id}/tx/{tx_id_or_number}/metadata
/api/v0/tss/{tss_id}/tx/{tx_id_or_number}/metadata

Request samples

application/json
Copy
Expand all Collapse all
{}

Response samples

application/json
Copy
Expand all Collapse all
{}

Retrieve a signed transaction log

Returns the log message of a transaction (identified by the tx_id_or_number path parameter) in its current revision or a specific revision if the tx_revision query parameter is set.

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

tx_id_or_number
required
string

Identifies a transaction by a tx_uuid (i.e. a self-generated UUIDv4) or a tx_number that gets assigned by us

query Parameters
tx_revision
integer [ 1 .. 9007199254740991 ]
Default: 1

Responses

200

Returns a signed log message

400

Revision number does not exist.

404

Resource does not exist.

get /tss/{tss_id}/tx/{tx_id_or_number}/log
/api/v0/tss/{tss_id}/tx/{tx_id_or_number}/log

Request samples

Copy

curl "https://kassensichv.io/api/v0/tss/00000000-0000-0000-0000-000000000000/tx/00000000-0000-0000-0000-000000000000" \
-H "Authorization: Bearer ..." \
-X GET > log_message.der
          

List transactions of a Client

Lists transactions of a Client.

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

client_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a client by a self-generated UUIDv4

query Parameters
order_by
string
Enum:"number" "state" "time_start" "time_end"

Specifies the property to sort by

order
string
Default: "asc"
Enum:"asc" "desc"

Determines the sorting order

limit
integer <= 100
Default: 100

Limits the number of returned results

offset
integer
Default: 0

Skips the specified number of results from the result set

states
Array of strings
Items Enum:"ACTIVE" "FINISHED" "CANCELLED"
Example: "states%5B0%5D=FINISHED&states%5B1%5D=CANCELLED"

Filter to include only specific states

Responses

200

Returns a list of transactions

404

Resource does not exist.

get /tss/{tss_id}/client/{client_id}/tx
/api/v0/tss/{tss_id}/client/{client_id}/tx

Request samples

Copy

curl "https://kassensichv.io/api/v0/tss/00000000-0000-0000-0000-000000000000/tx" \
-H "Authorization: Bearer ..." \
-X GET
          

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ],
  • "count": 0,
  • "_type": "TRANSACTION_LIST"
}

Clients

Endpoints for client management. A client represents an electronic record-keeping system which is meant to communicate its transaction data to a TSS for log message creation.

List clients of a TSS

List clients (electronic record-keeping systems) of a TSS.

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

query Parameters
order_by
string
Enum:"serial_number" "time_creation" "certificate_serial" "signature_counter"

Specifies the property to sort by

order
string
Default: "asc"
Enum:"asc" "desc"

Determines the sorting order

limit
integer <= 100
Default: 100

Limits the number of returned results

offset
integer
Default: 0

Skips the specified number of results from the result set

Responses

200

Returns the Clients list

404

TSS does not exist.

get /tss/{tss_id}/client
/api/v0/tss/{tss_id}/client

Request samples

Copy

curl "https://kassensichv.io/api/v0/tss/00000000-0000-0000-0000-000000000000/client" \
-H "Authorization: Bearer ..." \
-X GET
          

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ],
  • "count": 0,
  • "_type": "CLIENT_LIST"
}

List all clients

List clients (electronic record-keeping systems) of all available TSS.

Authorizations:
query Parameters
order_by
string
Enum:"serial_number" "time_creation" "certificate_serial" "signature_counter"

Specifies the property to sort by

order
string
Default: "asc"
Enum:"asc" "desc"

Determines the sorting order

limit
integer <= 100
Default: 100

Limits the number of returned results

offset
integer
Default: 0

Skips the specified number of results from the result set

Responses

200

Returns the Clients list

404

TSS does not exist.

get /client
/api/v0/client

Request samples

Copy

curl "https://kassensichv.io/api/v0/client" \
-H "Authorization: Bearer ..." \
-X GET
          

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ],
  • "count": 0,
  • "_type": "CLIENT_LIST"
}

Retrieve a client

Retrieve information about a specific client (electronic record-keeping systems) of a TSS.

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

client_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a client by a self-generated UUIDv4

Responses

200

Returns the Client resource

404

Resource does not exist.

get /tss/{tss_id}/client/{client_id}
/api/v0/tss/{tss_id}/client/{client_id}

Request samples

Copy

curl "https://kassensichv.io/api/v0/tss/00000000-0000-0000-0000-000000000000/client/00000000-0000-0000-0000-000000000000" \
-H "Authorization: Bearer ..." \
-X GET
          

Response samples

application/json
Copy
Expand all Collapse all
{
  • "serial_number": "string",
  • "time_creation": 1577833200,
  • "time_update": 1577833200,
  • "tss_id": "00000000-0000-0000-0000-000000000000",
  • "metadata":
    {},
  • "_id": "00000000-0000-0000-0000-000000000000",
  • "_type": "CLIENT"
}

Create or update a client

Create or update a client. Only a electronic record-keeping system associated with a TSS as a client may use the TSS.

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

client_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a client by a self-generated UUIDv4

Request Body schema: application/json
serial_number
string
metadata
object

You can use this parameter to attach custom key-value data to an object. Metadata is useful for storing additional, structured information on an object. Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Responses

200

Returns the Client resource

400

Invalid client serial.

404

Resource does not exist.

put /tss/{tss_id}/client/{client_id}
/api/v0/tss/{tss_id}/client/{client_id}

Request samples

application/json
Copy
Expand all Collapse all
{ }

Response samples

application/json
Copy
Expand all Collapse all
{
  • "serial_number": "string",
  • "time_creation": 1577833200,
  • "time_update": 1577833200,
  • "tss_id": "00000000-0000-0000-0000-000000000000",
  • "metadata":
    {},
  • "_id": "00000000-0000-0000-0000-000000000000",
  • "_type": "CLIENT"
}

Retrieve metadata of a client

Retrieve additional structured information about a client.

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

client_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a client by a self-generated UUIDv4

Responses

200

Returns metadata

404

Resource does not exist.

get /tss/{tss_id}/client/{client_id}/metadata
/api/v0/tss/{tss_id}/client/{client_id}/metadata

Response samples

application/json
Copy
Expand all Collapse all
{}

Create or update metadata of a client

Create or update additional structured information about a client.

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

client_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a client by a self-generated UUIDv4

Request Body schema: application/json
property name *
string

Responses

200

Returns metadata

404

Resource does not exist.

put /tss/{tss_id}/client/{client_id}/metadata
/api/v0/tss/{tss_id}/client/{client_id}/metadata

Request samples

application/json
Copy
Expand all Collapse all
{}

Response samples

application/json
Copy
Expand all Collapse all
{}

List transactions of a Client

Lists transactions of a Client.

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

client_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a client by a self-generated UUIDv4

query Parameters
order_by
string
Enum:"number" "state" "time_start" "time_end"

Specifies the property to sort by

order
string
Default: "asc"
Enum:"asc" "desc"

Determines the sorting order

limit
integer <= 100
Default: 100

Limits the number of returned results

offset
integer
Default: 0

Skips the specified number of results from the result set

states
Array of strings
Items Enum:"ACTIVE" "FINISHED" "CANCELLED"
Example: "states%5B0%5D=FINISHED&states%5B1%5D=CANCELLED"

Filter to include only specific states

Responses

200

Returns a list of transactions

404

Resource does not exist.

get /tss/{tss_id}/client/{client_id}/tx
/api/v0/tss/{tss_id}/client/{client_id}/tx

Request samples

Copy

curl "https://kassensichv.io/api/v0/tss/00000000-0000-0000-0000-000000000000/tx" \
-H "Authorization: Bearer ..." \
-X GET
          

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ],
  • "count": 0,
  • "_type": "TRANSACTION_LIST"
}

Data Exports

Endpoints for data export based on the Unified Digital Interface (Einheitliche Digitale Schnittstelle).

Trigger an export

Triggers an export and returns a reference to the associated ressource. This ressource is used for the asynchronous generation of a TAR file containing the initialization information, the log messages, and the certificate(s) required for the verification of the log messages.

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

export_id
required
string

Identifies an Export

query Parameters
client_id
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a client by a self-generated UUIDv4

transaction_number
string

Only return log messages associated with the given transaction number.

start_transaction_number
string

Only return log messages greater than or equal to the given start transaction number.

end_transaction_number
string

Only return log messages less than or equal to the given end transaction number.

start_date
integer [ 0 .. 9007199254740991 ]
Example: 1577833200

Only return log messages with dates larger than or equal to the given start date.

end_date
integer [ 0 .. 9007199254740991 ]
Example: 1577833200

Only return log messages with dates smaller than or equal to the given start date.

maximum_number_records
string

This parameter can be used to limit the number of returned log messages. If not 0 and the number of log messages exceeds the given maximum number of records, an error is returned. If 0, then all stored log messages are returned.

Request Body schema: application/json
metadata
object

You can use this parameter to attach custom key-value data to an object. Metadata is useful for storing additional, structured information on an object. Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Responses

200

Returns the export resource

400

Bad request. Mismatch in parameters. Provided parameters are conflicting.

404

TSS does not exist.

409

Conflict. A triggered export cannot be modified.

put /tss/{tss_id}/export/{export_id}
/api/v0/tss/{tss_id}/export/{export_id}

Request samples

application/json
Copy
Expand all Collapse all
{ }

Response samples

application/json
Copy
Expand all Collapse all
{
  • "href": "string",
  • "state": "CANCELLED",
  • "exception": "E_ID_NOT_FOUND",
  • "estimated_time_of_completion": 1577833200,
  • "time_request": 1577833200,
  • "time_start": 1577833200,
  • "time_end": 1577833200,
  • "time_expiration": 1577833200,
  • "time_error": 1577833200,
  • "tss_id": "00000000-0000-0000-0000-000000000000",
  • "metadata":
    {},
  • "_type": "EXPORT",
  • "_id": "string",
  • "_links":
    [
    ]
}

Retrieve an export

Returns an export resource. This resource holds the state of the asynchronous generation of a TAR file that (is ought to) contain(s) the initialization information, the log messages, and the certificate(s) required for the verification of the log messages. A successfully created export file is available until the time specified by the time_expiration attribute.

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

export_id
required
string

Identifies an Export

Responses

200

Returns the export resource

404

Resource does not exist.

get /tss/{tss_id}/export/{export_id}
/api/v0/tss/{tss_id}/export/{export_id}

Request samples

Copy

curl "https://kassensichv.io/api/v0/tss/00000000-0000-0000-0000-000000000000/export/00000000-0000-0000-0000-000000000000" \
-H "Authorization: Bearer ..." \
-X GET
          

Response samples

application/json
Copy
Expand all Collapse all
{
  • "href": "string",
  • "state": "CANCELLED",
  • "exception": "E_ID_NOT_FOUND",
  • "estimated_time_of_completion": 1577833200,
  • "time_request": 1577833200,
  • "time_start": 1577833200,
  • "time_end": 1577833200,
  • "time_expiration": 1577833200,
  • "time_error": 1577833200,
  • "tss_id": "00000000-0000-0000-0000-000000000000",
  • "metadata":
    {},
  • "_type": "EXPORT",
  • "_id": "string",
  • "_links":
    [
    ]
}

Cancel an export

Cancel an ongoing export operation (i.e., the generation of the TAR file). A cancellation is only possible in the states "PENDING" or "WORKING". Successfully created export files are available until the time specified by the time_expiration attribute and will be deleted automatically.

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

export_id
required
string

Identifies an Export

Responses

200

Returns the export resource

400

Bad request. A cancellation is only possible if the export is in state "PENDING" or "WORKING".

404

Resource does not exist.

delete /tss/{tss_id}/export/{export_id}
/api/v0/tss/{tss_id}/export/{export_id}

Request samples

Copy

curl "https://kassensichv.io/api/v0/tss/00000000-0000-0000-0000-000000000000/export/00000000-0000-0000-0000-000000000000" \
-H "Authorization: Bearer ..." \
-X DELETE
          

Response samples

application/json
Copy
Expand all Collapse all
{
  • "href": "string",
  • "state": "CANCELLED",
  • "exception": "E_ID_NOT_FOUND",
  • "estimated_time_of_completion": 1577833200,
  • "time_request": 1577833200,
  • "time_start": 1577833200,
  • "time_end": 1577833200,
  • "time_expiration": 1577833200,
  • "time_error": 1577833200,
  • "tss_id": "00000000-0000-0000-0000-000000000000",
  • "metadata":
    {},
  • "_type": "EXPORT",
  • "_id": "string",
  • "_links":
    [
    ]
}

Create or update metadata of an export

Create or update additional structured information about an export.

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

export_id
required
string

Identifies an Export

Request Body schema: application/json
property name *
string

Responses

200

Returns metadata

404

Resource does not exist.

put /tss/{tss_id}/export/{export_id}/metadata
/api/v0/tss/{tss_id}/export/{export_id}/metadata

Request samples

application/json
Copy
Expand all Collapse all
{}

Response samples

application/json
Copy
Expand all Collapse all
{}

Retrieve metadata of an export

Retrieve additional structured information about an export.

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

export_id
required
string

Identifies an Export

Responses

200

Returns metadata

404

Resource does not exist.

get /tss/{tss_id}/export/{export_id}/metadata
/api/v0/tss/{tss_id}/export/{export_id}/metadata

Response samples

application/json
Copy
Expand all Collapse all
{}

List exports of a TSS

Lists exports of a TSS.

Authorizations:
path Parameters
tss_id
required
string <uuid>
Example: "00000000-0000-0000-0000-000000000000"

Identifies a TSS

query Parameters
order_by
string
Enum:"state" "estimated_time_of_completion" "time_request" "time_start" "time_end" "time_expiration" "time_error"

Specifies the property to sort by

order
string
Default: "asc"
Enum:"asc" "desc"

Determines the sorting order

limit
integer <= 100
Default: 100

Limits the number of returned results

offset
integer
Default: 0

Skips the specified number of results from the result set

states
Array of strings
Items Enum:"CANCELLED" "PENDING" "WORKING" "COMPLETED" "ERROR"
Example: "states%5B0%5D=PENDING&states%5B1%5D=WORKING"

Filter to include only specific states

Responses

200

Returns the Export list

404

TSS does not exist.

get /tss/{tss_id}/export
/api/v0/tss/{tss_id}/export

Request samples

Copy

curl "https://kassensichv.io/api/v0/tss/00000000-0000-0000-0000-000000000000/export" \
-H "Authorization: Bearer ..." \
-X GET
          

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ],
  • "count": 0,
  • "_type": "EXPORT_LIST"
}

List all exports

List exports of all available TSS.

Authorizations:
query Parameters
order_by
string
Enum:"state" "estimated_time_of_completion" "time_request" "time_start" "time_end" "time_expiration" "time_error"

Specifies the property to sort by

order
string
Default: "asc"
Enum:"asc" "desc"

Determines the sorting order

limit
integer <= 100
Default: 100

Limits the number of returned results

offset
integer
Default: 0

Skips the specified number of results from the result set

states
Array of strings
Items Enum:"CANCELLED" "PENDING" "WORKING" "COMPLETED" "ERROR"
Example: "states%5B0%5D=PENDING&states%5B1%5D=WORKING"

Filter to include only specific states

Responses

200

Returns the Export list

404

TSS does not exist.

get /export
/api/v0/export

Request samples

Copy

curl "https://kassensichv.io/api/v0/export" \
-H "Authorization: Bearer ..." \
-X GET
          

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ],
  • "count": 0,
  • "_type": "EXPORT_LIST"
}