Welcome to the new fiskaly Workspace — documentation reimagined.

Guide for New Customers

Step-by-step setup for new SIGN DE customers

This guide walks you through the complete process of setting up your system with fiskaly SIGN DE, using a combination of the fiskaly Dashboard and API requests. By the end, you will have a fully working TSS with a client ready to sign transactions.

Overview

Before diving into the setup, here is what you will configure:

🏢

Organization

Your top-level entity in fiskaly. Managed organizations represent individual physical locations.

🔑

API Key & Secret

Credentials generated in the Dashboard, used to authenticate all subsequent API requests.

🔐

Authentication

Exchange your API key and secret for an access token used in all further API calls.

🛡️

TSS (Technical Security System)

The core signing component. Must be created, configured with an Admin PIN, and initialized.

💻

Client

Represents a point-of-sale terminal or application that creates transactions against a TSS.

🧾

Transaction

A signed fiscal record. Once your TSS and Client are ready, you can create and sign transactions.

Take a look at our video walkthrough for a visual explanation of the setup process.

Prerequisites

📘Before you begin

You need a fiskaly account and access to the fiskaly Dashboard. If you do not have an account yet, sign up here.

You will also need a tool to make HTTP requests — for example cURL (command line), Postman, or your own application code.

Step-by-step Setup

Create an Organization
When you log into the Dashboard for the first time, you are prompted to create an organization. This is your main organization, and all managed organizations are created beneath it.
Generally, each managed organization corresponds to a physical location (e.g. a store or restaurant).
💡Not ready for production?
For testing purposes, you do not need to fill in all fields. You can leave the billing address empty and complete it later.
After creating your organization, the Dashboard will show your current setup — initially with 0 TSS and 0 clients.
Generate an API Key and Secret
Navigate to the API Keys section in the fiskaly Dashboard and create a new API key.
You will receive an API Key and API Secret. Save these securely — you will need them for all subsequent API requests.
⚠️Store your credentials safely
The API Secret is only shown once. Make sure to copy and store it in a secure location before closing the dialog.
Our video tutorial demonstrates the process of generating an API key and secret.
Authenticate with the API
Use your API key and secret to obtain an access token. This token is required for all subsequent requests.
curl -X POST https://kassensichv-middleware.fiskaly.com/api/v2/auth \ -H "Content-Type: application/json" \ -d '{ "api_key": "your_api_key", "api_secret": "your_api_secret" }'
The response contains an access_token that you must include as a Bearer token in the Authorization header of all following requests.

Create a TSS

Create a new Technical Security System (TSS) by sending a PUT request with a unique TSS ID (UUID).

TSS_ID=$(uuidgen)

curl -X PUT "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "My first TSS"
  }'

After creation, you need to initialize the TSS. This involves three sub-steps:

a) Change the Admin PIN

The TSS is created in an UNINITIALIZED state. You must set a new Admin PIN before initialization.

curl -X PATCH "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "admin_puk": "initial-puk-from-creation",
    "new_admin_pin": "your-secure-admin-pin"
  }'

b) Authenticate as Admin

curl -X POST "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin/auth" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "admin_pin": "your-secure-admin-pin"
  }'

c) Initialize the TSS

Update the TSS state to INITIALIZED:

curl -X PATCH "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "INITIALIZED"
  }'

Create a Client

With the TSS initialized, create a client that represents your point-of-sale terminal or application.

CLIENT_ID=$(uuidgen)

curl -X PUT "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/client/${CLIENT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "serial_number": "POS-001"
  }'

Create a Transaction

Now you can create your first signed transaction. Transactions follow a lifecycle: start the transaction, then finish it.

a) Start the transaction

TX_ID=$(uuidgen)

curl -X PUT "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/tx/${TX_ID}?tx_revision=1" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "ACTIVE",
    "client_id": "your-client-id"
  }'

b) Finish the transaction

curl -X PUT "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/tx/${TX_ID}?tx_revision=2" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "FINISHED",
    "client_id": "your-client-id",
    "schema": {
      "standard_v1": {
        "receipt": {
          "receipt_type": "RECEIPT",
          "amounts_per_vat_rate": [
            {
              "vat_rate": "NORMAL",
              "amount": "10.00"
            }
          ],
          "amounts_per_payment_type": [
            {
              "payment_type": "CASH",
              "amount": "10.00"
            }
          ]
        }
      }
    }
  }'

The response includes the signed transaction data with a cryptographic signature from the TSS.

Log Out the Admin

After completing the setup, log the Admin user out of the TSS.

curl -X POST "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin/logout" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

💡Automate the setup

This entire sequence of requests can be integrated into a “one-click” provisioning solution that requires no manual user interaction. The implementation details are up to you.

Postman Collection

You can also run through these requests using Postman. Download the collection and environment files to get started quickly:

Download Postman Collection

Download Postman Environment

See the Postman tutorial for detailed instructions.

Next Steps

API Reference & TSS Examples

Explore the complete collection of API requests for managing TSS, clients, and transactions.

SIGN DE API Documentation

Full API documentation for the KassenSichV v2 endpoint — all resources, parameters, and responses.

Dashboard Guide

Learn how to manage organizations, API keys, and TSS through the fiskaly Dashboard.

Testing & Sandbox

Set up your sandbox environment to test transactions before going to production.