Zum Hauptinhalt springen

Migrating from V1 to V2

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

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

  • Only one integration is needed - there is no hardware rollout, since everything is software based
  • Software updates are automatic and invisible
  • You always have semi-live access to your data. The data is also always imported in close to real time via the dashboard.
  • Performance is monitored by fiskaly

Here is an overview of the changes. There is also a detailed changelog.

The SDK is replaced by an API​

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

Your V1 environment will continue to work during the 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 organisations created in the productive environment remain in place and are fully functional. No new organisations need to be created.

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

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

Data migration is not necessary​

No manual data migration needs to be carried out. Due to technical and legal requirements, data from V1 can't be transitioned to V2, so all resources will have to be created again using V2.

For the V2 resources (TSSs and clients) new UUIDs must be used to keep the IDs of all resources across the fiskaly system unique in order to avoid potential issues.

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 accordingly at the new TSS (use new UUIDs for this process). From that point on, only SIGN DE V2 is to be used for signing transactions.

info

The SIGN DE V1 endpoints are accessible until the end of 30.12.2022. TSS exports of V1 should be triggered and downloaded by that date.

SMAERS rollouts are managed by fiskaly​

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

Authentication​

The fiskaly SIGN DE API implements a set of legal requirements and technical guidelines. Several changes have resulted from the specifications of the TR.

The most obvious changes to the API concern authentication. Some operations on TSE and client require a (TSS-)Admin (as defined in the BSI TR-03153-TS) authentication.

A PIN/PUK is used for initial setup of the (TSS-)Admin user. This is included in the process of creating the first TSS.

The following maintenance operations require administrator authentication:

Other notes​

  • All POS devices must be registered as clients of the TSS. Multiple clients can (and should) be assigned to a single TSS. No more than 199 clients can be assigned to one TSS.
  • A TSS is only allowed to have 2000 open (i.e. "ACTIVE") transactions. In case a TSS reaches this limit, you need to close the open transactions (set to "CANCELLED" / "FINISHED", depending on your process).

  • Please note that revision handling of a transaction in SIGN DE V2 has changed slightly compared to V1. The query string for endpoint upsertTransaction must include the tx_revision parameter. Set tx_revision to 1 when you start the transaction. After each call, the tx_revision must be incremented. Pass an incremented tx_revision in the query string for the next call.

  • The field certificate_serial of the "FINISHED" transaction response in SIGN DE V1 corresponds in SIGN DE V2 to field tss_serial_number.

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

Overview of steps​

To migrate your system to V2, ongoing operations on the V1 should be stopped. To ensure that no more transactions are signed via the V1, the TSS of the V1 should be disabled. This also avoids confusion with the billing.

Then carry out some initial requests to set up the Administrator and the first TSS on V2. This should be done using a HTTP client; you cannot use the dashboard.

The following diagram illustrates the process:

initial-setup

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, the customer.

The next page takes you step by step through an example.