Migrating from V1 to V2

This guide provides you with the necessary information to ensure a smooth transition from SIGN DE V1 to SIGN DE V2.

Overview of Changes

fiskaly focuses on a purely cloud-based implementation of the TSE and the entire KassenSichV. This has several advantages:

• Only one integration is needed — no hardware rollout, since everything is software-based
• Software updates are automatic and invisible
• You always have semi-live access to your data via the dashboard
• Performance is monitored by fiskaly

Key Differences

Aspect	V1	V2
Integration method	SDK	REST API + HTTP client
Client communication	Direct to backend	Via Middleware service
TSS management	SDK-based	Dashboard + API
Admin authentication	Not required	PIN/PUK required
Client limit per TSS	—	Max 199 clients
Open transactions per TSS	—	Max 2,000 active
Transaction revisions	Implicit	Explicit tx_revision parameter
Certificate field	certificate_serial	tss_serial_number

The SDK is Replaced by an API

There is no longer any need to integrate an SDK. V2 uses a new API together with a web-based management dashboard, and can be addressed with any HTTP client of your choice.

V1 Continues to Work During Transition

While integrating V2, you can continue to use your existing V1 setup. A test environment is available for V2, allowing you to try out certified technical security systems, exports, clients, users, etc.

All API keys and organizations created in the productive environment remain in place and are fully functional. No new organizations need to be created.

💡Tip

For a multi-stage rollout, both V1 and V2 integrations can be operated in parallel in the cash register. The changeover to V2 can be activated centrally or by the end customer.

No Data Migration Necessary

⚠️Data cannot be transferred between versions

Due to technical and legal requirements, data from V1 cannot be transitioned to V2. All resources (TSSs and clients) will have to be created again using V2 with new UUIDs.

Your V1 data is retained. Existing transactions and exports will still be accessible from V1 but not from V2, and updating them will not be possible. You will need to re-register your clients at the new TSS using new UUIDs. From that point on, only SIGN DE V2 is to be used for signing transactions.

SMAERS Managed by fiskaly

fiskaly operates and manages the operation, rollout, and update of the SMAERS instances.

---

Key API V2 Details

Essential URLs

Service	URL
Management Dashboard	https://dashboard.fiskaly.com
SIGN DE API V2 (Middleware)	https://kassensichv-middleware.fiskaly.com
SIGN DE API V2 (Backend)	https://kassensichv.fiskaly.com
DSFinV-K API	https://dsfinvk.fiskaly.com

📘V1 customers

If you are a customer with a V1 account, your organizations and API keys are still valid for V2. You do not need to change anything!

Client Access

Communication is no longer directly to the backend, but to the fiskaly Middleware service: https://kassensichv-middleware.fiskaly.com/

The fiskaly Backend (https://kassensichv.fiskaly.com/) can still be used for the following operations:

• Authenticate API (without base_url)
• Create, Retrieve, and List TSS
• Retrieve and update TSS metadata
• Retrieve and List clients
• List and Retrieve transactions
• Retrieve signed transaction logs
• All export operations

⚠️Session compatibility

It is not possible to use a session created via the fiskaly Backend in the fiskaly Middleware. However, it is possible to use a session created via the fiskaly Middleware in the fiskaly Backend.

Authentication

There are two authentication methods:

Method	Description
ApiKeyAuthentication	Initial auth using API key and secret
RefreshTokenAuthentication	Refresh an existing session

Each accepts an optional base_url. If not set, a default value is used.

Some operations on TSE and clients require Admin authentication (as defined in BSI TR-03153-TS):

• Disabling a TSS
• Creating and de-registering clients in a TSS

PUK and PIN Codes

When a TSS is created, the response includes a PUK.

⚠️Store the PUK securely

The PUK is presented only once, when creating a TSS. The client must store it securely in case it is needed in the future.

Code	Purpose
PIN	Used for Admin Authentication. Blocked after 5 unsuccessful attempts.
PUK	Used for unblocking a blocked PIN.

Important Limits

⚠️Breaking changes to be aware of

• All POS devices must be registered as clients of the TSS. No more than 199 clients can be assigned to one TSS. - A TSS may only have 2,000 open (ACTIVE) transactions. If a TSS reaches this limit, you must close open transactions (set to CANCELLED or FINISHED). - Transaction revision handling has changed: the query string for upsertTransaction must include tx_revision. Set tx_revision to 1 when starting a transaction and increment after each call. - The field certificate_serial from V1 corresponds to tss_serial_number in V2.

Disabling a TSS

🚨Irreversible action

Setting the state of a TSS to DISABLED results in taking its SMAERS component out of operation permanently. This action is irreversible. No new transaction data can be processed, but retrieve, list, and export operations remain fully functional.

---

Step-by-Step Migration

📘Note

It is important to plan a migration. The taxpayer should not be involved in the migration process and should not experience any disruption. It is recommended to perform the migration after the cash-point closing. You may need to do a staged rollout.

API Key and Secret

Use your existing organization structure and API keys with their associated secret (the secret is only provided when the API key is created).

The Management API provides access to API keys.

Setting Up a V2 System

A V2 TSS should be created for each organization. Practically, this means that at least one TSS should be used for each location. Each TSS can handle multiple clients.

1. Authenticate

   Authenticate using your API key and secret to obtain access and refresh tokens.

2. Create TSS

   Create a new TSS. The response will include a PUK — store it securely.

3. Update TSS state to UNINITIALIZED

   Set the TSS state to UNINITIALIZED to prepare it for configuration.

4. Change Admin PIN

   Set a new Admin PIN using the PUK received during TSS creation.

5. Authenticate Admin

   Authenticate as the TSS Admin using the new PIN.

6. Update TSS state to INITIALIZED

   Set the TSS state to INITIALIZED to activate it.

7. Create Clients

   Register your POS devices as clients of the new TSS using new UUIDs.

8. Logout Admin

   Log out the Admin session. The TSS is now ready for use.

💡Tip

This sequence of requests can be integrated into a “one-click” solution which does not require any user interaction. The details of the implementation are up to you.

Disabling the V1 TSS

With the V2 system running, proceed to decommission the old V1 system.

List your V1 TSS using a GET request:

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

Disable each V1 TSS with a PUT request:

curl "https://kassensichv.io/api/v1/tss/{tss_id}" \
  -H "Authorization: Bearer ..." \
  -d state="DISABLED" \
  -X PUT

📘Note

The TSS cannot be deleted, but its data is preserved. It is still possible to trigger exports even after the TSS is disabled. However, the data cannot be migrated to V2.

💡Tip

To disable a V1 TSS after commissioning V2, perform a PUT request on the V1 TSS with state = "DISABLED" to ensure no more transactions are signed via V1 and to avoid billing confusion.

An overview of which data should be included on a receipt is shown in the Receipt Data article.

Related Pages

New Customers Guide

Complete V2 setup walkthrough for new integrations

Error Handling

Best practices for timeouts and error recovery

Receipt Data

Required receipt fields and QR code content