Zum Hauptinhalt springen

Migration example

This page describes how to carry out an example migration from V1 to V2.

Note​

It is important to plan a migration. The taxpayer is not involved in the migration process, and shouldn't experience any disruption. Therefore it is recommended to do a migration after the cash-point closing. You may need to do a staged roll-out.

API key and secret​

The Management API provides access to API keys.

You should use your existing organization structure and API keys with their associated secret. (The secret is only given when the API key is created.)

For this example, our API key and secret are:

info
   API Key: test_5p6sea5j5kq8zu4az2mjj2umm_examplekey
API Secret: lkYqVBE7TbqKSWnTg2YZsmwyJyXEp6awoAS1V74MSys

Set 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.

We will use a HTTP client (Postman) to run the following requests to set up a basic V2 system:

  • Authentication
  • Create TSS
  • Update TSS (state "UNINITIALIZED")
  • Change Admin PIN
  • Authenticate Admin
  • Update TSS (state "INITIALIZED")
  • Create Client
  • Logout Admin

The requests can be tested in Postman (see the Postman tutorial), or you can use the terminal command 'curl'.

You can download the relevant Postman files here:

...

You can find a complete collection of requests in the API reference, in this section, and also read the full API documentation.

Disable V1 TSS​

With the V2 system running, we can now proceed to decommission our old V1 system.

We can get a list of our V1 TSS using a GET request:

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

For this example, only one TSS is listed, with the following ID:

812487af-04f7-489d-9fdd-cfdfbd4e0019

We disable this TSS with a PUT request:

curl "https://kassensichv.io/api/v1/tss/812487af-04f7-489d-9fdd-cfdfbd4e0019" \
-H "Authorization: Bearer ..." \
-d state="DISABLED" \
-X PUT

The V1 API documentation contains more details about how to update the TSS.

Note that the TSS cannot be deleted, but its data is preserved. It is still possible to trigger exports even after the TSS is disabled. However, note also that the data cannot be migrated (hence the creation of a new V2 TSS).