Skip to content

Cancel an export

fiskaly
API docs by Redocly

fiskaly SIGN DE API (2.2.2)

Download OpenAPI specification:

fiskaly GmbH: info@fiskaly.com URL: https://fiskaly.com

Imprint: fiskaly.com/impressum | Privacy Policy: fiskaly.com/datenschutz

Introduction

The fiskaly SIGN DE API is a RESTful API. It implements a cloud-based middleware for the fiskaly CTSS (Certified Technical Security System) / TSE (Technische Sicherheitseinrichtung). The fiskaly SIGN DE API is compliant with the German KassenSichV (Kassen­sich­er­ungsver­ord­nung).

The fiskaly SIGN DE API is a platform-independent and software-only solution. The only thing you need to integrate the fiskaly SIGN DE API is a stable Internet connection.

The fiskaly SIGN DE API:

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

The obligations regarding the declaration requirement (Mitteilungspflicht) under §146a (4) AO starting with 2025 can be fulfilled by using the fiskaly SUBMIT DE.

Components

The fiskaly CTSS has to be integrated in your ERS. It consists of two components:

  • fiskaly SMAERS (Security Module Application for Electronic Record-keeping Systems) and
  • fiskaly CSP-L (Cryptographic Service Provider Light).

The fiskaly SIGN DE API is a common interface for the Electronic Record-keeping System (ERS). It can simplify the integration of the fiskaly CTSS into your ERS. If you want to integrate the fiskaly CTSS directly, please contact our sales team.

ERS (Electronic Record-keeping System)

The Electronic Record-keeping System (ERS) creates digital records of business transactions. It consists of workstations, input devices (PCs, iPads etc.), server systems, middleware, archives, and transaction processing units. The exact composition of the ERS depends on the Point of Sale (PoS) vendor. For more information, see the legal definition of the ERS.

Security Module Application for Electronic Record-keeping Systems (SMAERS)

The Security Module Application for Electronic Record-keeping Systems (SMAERS) receives transaction data and converts it to transaction log messages. It transmits the log messages to the Cryptographic Service Provider Light (CSP-L). The CSP-L signs the transaction log messages to protect the transaction data from undetected manipulation. The signed transaction logs are stored in a secure storage. The storage is provided by fiskaly.

The SMAERS Server must not be operated by the PoS vendor, taxpayer or an entity dependent on the taxpayer. In fiskaly SIGN DE API, the SMAERS Server is operated by fiskaly within the Google Cloud Platform in the geographical data center region Frankfurt (europe-west3).

Cryptographic Service Provider Light (CSP-L)

The CSP-L is a general-purpose signature provider. It protects your data against undetected manipulation. The CSP-L is operated by fiskaly. It runs on a special tamper-proof hardware in a secure datacenter.

fiskaly sign Middleware

The fiskaly sign Middleware provides a unified interface for the SMAERS component and the storage backend.

Background

The fiskaly SIGN DE API implements a set of legal requirements and technical guidelines. The current version 2.2.2 of this API is based on the following regulations:

Versioning

The fiskaly SIGN DE API follows Semantic Versioning.

The version number has a pattern of 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 2 is reflected in the API's base URL: /api/v2.

Idempotent Requests

The fiskaly SIGN DE API is idempotent. Idempotence means you can send the same request several times safely. The result will be the same as if you have sent it only once.

For example, if you request to start a transaction but don't receive a response, you can send the request again with the same request body. Only one transaction will be started.

UUIDv4

This API uses UUIDv4. Requests like createTss, createClient, and upsertTransaction create new resources. To run such requests, generate a random UUIDv4. Then pass the UUIDv4 in the request body. This UUIDv4 will be assigned to the newly created resource.

A good way to generate a UUIDv4 is to use a library in your programming language of choice (like this) or an online generator (like this). A UUIDv4 created this way will be random and unique throughout the system.

Using your system's id or a UUID bound to your hardware is a bad way to create a UUIDv4. If you use a UUID of your cash register as the client_id in createClient, you will not be able to use it again for another TSS. The UUIDs of fiskaly resources have to be truly random and non-dependent on any of your systems properties.

Request IDs

The fiskaly SIGN DE API associates a unique identifier with each request. This identifier needs to be generated and set by the ERS. You will find this request identifier in the response headers, under request-id. If you need help with a request you have issued, please provide the request identifier. We will find your request and help you faster.

Metadata

Most resources in the API (e.g. ) have a metadata property. You can store any additional information in the metadata.

For example, in the metadata of a transaction you can store an id of a receipt or invoice from your system.

You can specify up to 40 key-value pairs in the metadata object. A key can be up to 40 characters long. A value can be up to 500 characters long.

Request body size limits

The size limit of request bodies is 1 MB. Requests above this threshold will fail with status code 413 (request too large).

Automated eviction of unused TSSs

The SIGN DE system has an automated periodic process to evict unused TSS instances. During this process, resources of older CREATED, but not deployed TSS instances are released.

The preconditions for evicting a TSS are the followings:

  • the TSS has the state CREATED,
  • the TSS has been created at least 3 months ago,
  • no transactions have been signed by the TSS. Such TSS instances will have the EVICTED state.

Changes

Changelog for version 2.0.0 of the API

Overview of changes

  • The set of operations, path parameters, JSON schemas of requests and responses have been changed since v1.
  • The TSS is fully certified (cf. Certificate Overview. All certified components have been integrated in the API.
  • New URLs have been introduced. Use https://kassensichv-middleware.fiskaly.com for ALL calls to the API. Other URLs, such as https://kassensichv-middleware.fiskaly.dev, will soon be made UNAVAILABLE to customers.
  • There are fiskaly sign Middleware operations and common operations in the API. fiskaly sign Middleware operations require direct interaction with the SMAERS component, and common operations do not. fiskaly sign Middleware operations are marked with the label Only available via Middleware. fiskaly sign Middleware URL https://kassensichv-middleware.fiskaly.com can be used for ALL calls to the API. You can use the URL https://kassensichv.fiskaly.com for operations that are not labelled with Only available via Middleware.
  • The resources created with v1 cannot be transitioned to v2. All TSS resources must be created again with v2. You can access the old transactions via the v1 API. You can use your existing organizations, API-Keys, and users with v2.

Changes in authentication

  • authenticateApi hasn't been changed since v1. The base_url parameter from the development versions of v2 has been removed again.
  • authenticateAdmin has been added. This operation provides an additional security layer for administrative operations. The administrator of a TSS is the taxpayer. You must use changeAdminPin to set an initial PIN. Admin authentication is required for
  • logoutAdmin has been added. Use this operation to exit the administrator mode. Run this endpoint when you are finished making administrative changes.
  • The calls to authenticateAdmin and logoutAdmin are documented with system logs.

Changes in TSS handling

  • The lifecycle states of a TSS resource are CREATED, UNINITIALIZED, INITIALIZED, and DISABLED.
  • createTss has been added. This operation triggers the creation of a TSS instance. The operation returns the PUK of the TSS. The PUK is required for administrative access. It is only visible after the first run of the createTss endpoint. createTss is idempotent. If you don't receive a response, you can run the endpoint again. The calls to createTss are only possible if the TSS is in the state CREATED.
  • updateTss is used to change TSS state. The following state transitions are allowed:
    • CREATED to UNINITIALIZED,
    • UNINITIALIZED to INITIALIZED,
    • UNINITIALIZED to DISABLED,
    • INITIALIZED to DISABLED.
  • A transition from CREATED to UNINITIALIZED starts up the SMAERS component of the TSS. The SMAERS documents the startup and transition with a system log. An UNINITIALIZED TSS cannot be used for signing transactions.
  • A transition from UNINITIALIZED to INITIALIZED makes the TSS ready to use. The SMAERS component documents the initialization of the TSS with a system log. An INITIALIZED TSS can be used for signing transactions.
  • A transition to DISABLED permanently puts the TSS out of service. This operation cannot be reversed. The SMAERS documents the decommissioning of the TSS with a system log. A DISABLED TSS can no longer be used for signing transactions. You can still request an export of data from a DISABLED TSS.
  • changeAdminPin has been added. This operation changes the PIN for Admin Authentication. changeAdminPin can be used when the TSS is UNINITIALIZED or INITIALIZED. You have to set the PIN with changeAdminPin before using authenticateAdmin for the first time.
  • The calls to updateTss and changeAdminPin are documented with a system log.

Changes in client handling

  • The lifecycle states of a client resource are REGISTERED and DEREGISTERED.
  • createClient has been added. This operation puts a client in the state REGISTERED. The SMAERS documents the registration of the client with a system log.
  • updateClient updates the state of a client. This operation can be used to deregister or re-register an existing client. Deregistering a client is not permanent. A DEREGISTERED client can become REGISTERED again. The SMAERS component documents every client state change with a system log.

Changes in TEST environment

  • TSS instances in the TEST environment that have been disabled, or have been inactive for over 14 days, will be wiped at least every Sunday.
  • You can have up to five TSS in the states CREATED, UNINITIALIZED, and INITIALIZED. If this limit is reached, you won't be able to create new TSS. To create a new TSS, set the state of an existing TSS to DISABLED. Make sure that your test suite implements this in the teardown routine.
  • We regularly wipe the data in the TEST environment. The resources you created for testing can get deleted during the test runs.
  • When we wipe the TSS in the TEST environment, their states are set to DELETED. Once a TSS is in the state DELETED, all state changing operations (including exports) result in the error E_TSS_DELETED.

Log Messages

  • Calls to upsertTransaction generate transaction Logs (as in fiskaly SIGN DE API V1).
  • System logs are generated by the SMAERS component and may show up in exports.
  • Audit logs are generated by the CSPL component and may show up in exports.
  • Signing of system and audit logs increments the signature counter of a TSS just like signing of transaction Logs.

MINOR and PATCH changes

v2.2.2

v2.2.1

  • Enhanced validation for client serial numbers to prevent leading or trailing whitespace. Serial numbers must start and end with non-whitespace characters.

v2.2.0

  • All TSS instances in states INITIALIZED and UNINITIALIZED have been updated to the version 1.0.15-1.5.0 (BSI certification ID: BSI-K-TR-0717-2025). The version of the BSI Certification ID can be also retrieved by retrieveTss.

v2.1.35

  • OpenAPI schema description improvements.

v2.1.34

  • Improved export processing.
Show previous changes

v2.1.33

v2.1.32

  • listClientTransactions endpoint now returns only transactions where the latest revision belongs to the specified client. Previously, if any revision of a transaction belonged to the client, it was returned.

v2.1.31

v2.1.30

  • Limit on the number of exports in PENDING or WORKING state per TSS has been set to 10 in the triggerExport endpoint.

v2.1.29

  • Added a limit in the triggerExport endpoint for the maximum number of exports in PENDING or WORKING state per TSS. If the limit is reached, you can't trigger a new export until some exports are processed.

v2.1.28

  • Updating third-party dependencies.

v2.1.27

  • Updated documentation of createClient endpoint to clarify uniqueness requirements of the client serial_number.

v2.1.26

v2.1.25

  • Added the E_LOG_NOT_FOUND error which indicates that a log for a given transaction was not found.

v2.1.24

  • Added the E_TSS_LOCKED error which indicates the temporary unavailability of a TSS resource.

v2.1.23

  • Added E_EXPORT_PROCESSING_TIMEOUT to ExportException in the retrieve export endpoint for cases where an export takes too long to process (default: 24h).

v2.1.22

v2.1.21

  • Updating third-party dependencies.

v2.1.20

  • Removed field bsi_certification_valid_to on the responses of the TSS endpoints updateTss, retrieveTss, and listTss for TSS instances in the UNINITIALIZED, INITIALIZED, and DISABLED states.

v2.1.19

  • Underlying export storage mechanism has been changed.

v2.1.18

  • When an export has the state PENDING or WORKING, you can no longer trigger an export against the same TSS with the same parameters unless the first export is completed.

v2.1.17

  • Validation added for query parameters limit (minimum value is 1) and offset (minimum value is 0)

v2.1.16

  • Changed DSFinV-TW version to 1.1 in documentation, no API changes necessary from 1.0 before.

v2.1.15

  • The OpenAPI change from 2.1.24 was reverted because of breaking some customer implementations.

v2.1.14

  • The OpenAPI request specification of triggerExport was corrected to require an empty body structure. This change only effects the OpenAPI specification, the implemented behavior was not changed.

v2.1.13

  • Introduce a limitation for createTss up to 500 instances per pay
  • createTss has a new error response 403 Limit of 500 created TSS's per day reached.

v2.1.12

  • The schema dsfinvtw_v1 in the operation upsertTransaction is allowed within both TEST and LIVE environments

v2.1.11

  • Added periodic automated eviction process to release resources of TSS instances that have not yet transitioned to a lifecycle state beyond CREATED over three months. These TSS instances are transitioned to the state EVICTED.

v2.1.10

  • Updated upsertTransaction to return 400 Bad request instead of 404 Not found when client not found
  • Minor refactoring

v2.1.9

  • Correction of response status 401 instead of 400 in the case of an invalid refresh token in the operation authenticateApi

v2.1.8

  • General performance improvement

v2.1.7

  • Documentation change regarding status code 499 errors

v2.1.6

  • Added fields bsi_certification_id and bsi_certification_valid_to to the responses of the TSS endpoints updateTss, retrieveTss, and listTss for TSS instances in the UNINITIALIZED, INITIALIZED, and DISABLED states. These fields provide information about the certification, issued by the German Federal Office for Information Security (BSI), of each TSS instance.

v2.1.5

v2.1.4

v2.1.3

  • Prohibit update of the transactions with dsfinvtw_v1 schema in the operation upsertTransaction

v2.1.2

  • Introduced the EVICTED TSS state - such TSS instances have previously been created, but haven't been used to sign any transactions, and after a grace period their resources have been released following a maintenance process

v2.1.1

  • Fixed empty dsfinvtw_v1.driver_status in the response of the operation upsertTransaction

v2.1.0

  • New schema dsfinvtw_v1 has been added to the operation upsertTransaction. This schema covers DSFinV-TW. This feature is currently only available within the TEST environment

v2.0.53

  • Fixed empty field schema.raw in the response of the operation upsertTransaction in the scenario where schema.raw is not empty in the input when the transaction starts

v2.0.52

  • Optimized export processing

v2.0.51

  • Optimized export processing

v2.0.50

  • Updated API query string parsing to ignore leading question marks in malformed queries

v2.0.49

v2.0.48

v2.0.47

  • Autogenerate OpenAPI 3.0.3-compliant API specifications

v2.0.46

  • Changes in export processing

v2.0.45

  • Security updates

v2.0.44

  • Updating third-party dependencies

v2.0.43

  • Request id generation improvements
  • Export improvements

v2.0.42

v2.0.41

  • Export optimizations

v2.0.40

  • Updating third-party dependencies

v2.0.39

  • Performance optimisations

v2.0.38

  • Database performance optimisations

v2.0.37

  • Database performance optimisations

v2.0.36

  • Refinements in wiping mechanism

v2.0.34

  • Added information about dealing with DEFECTIVE state of TSS: Defective TSS

v2.0.33

v2.0.32

  • Validation added for maximum length of client serial number (70 characters) to conform with DSFinV-K
  • The documentation of the operation createClient is adapted accordingly

v2.0.31

  • Export improvements

v2.0.30

  • Rollback of version upgrade of some third-party dependencies due to breaking change in the behavior of SIGN DE v2 for at least one customer integration

v2.0.29

  • Updating third-party dependencies
  • Stability improvements in request timeout handling
  • Improvements to standardV1 schema transformation

v2.0.28

  • Added recommendation regarding the length of the serial number of the client in createClient

v2.0.27

  • Refinements in wiping mechanism

v2.0.23

  • Changes in wiping mechanism

v2.0.22

  • Updating third-party dependencies

v2.0.20

  • Minor documentation improvements

v2.0.18

  • Fix problems with big exports
  • Improve performance of log synchronization

v2.0.17

  • Logging improvements

v2.0.16

  • Export improvements
  • Documentation improvements

v2.0.15

  • Log synchronization improvements

v2.0.14

  • Updating some third-party dependencies

v2.0.13

  • Performance improvements

v2.0.12

The changes in the DSFinV-K v2.3 are taken into account:

v2.0.11

  • Updating some third-party dependencies.

v2.0.10

  • Adapted documentation of triggerExport operation.
  • Adapted documentation of amount of upsertTransaction operation.
  • Prevent changing the state of the exports from CANCELLED to COMPLETED.
  • Prevent changing the state of the tss if TSS is DEFECTIVE.
  • Make the field exception of the exports more informative.

v2.0.9

  • Added new filtration parameters start_signature_counter and end_signature_counter in the triggerExport operations.

v2.0.8

v2.0.7

  • Added a new field to the TSS response: time_defective. It shows the time at which the TSS went into state DEFECTIVE.
  • Documented the 403 Forbidden error response. It can be thrown if the organization is not provided or not authorized for the operation.

v2.0.6

  • Added a new TSS state: DEFECTIVE. TSS that are in state DEFECTIVE cannot be used for transaction handling, but can be used for all retrieve and list operations.

v2.0.5

  • Added a new TSS state: DELETED. This state only exists within the TEST environment. TSS are put in the state DELETED when they are removed from the TEST environment. The TEST environment cleanup happens at least every Sunday.

v2.0.4

  • All received UUIDs are automatically converted to lower case.

v2.0.3

v2.0.2

  • createTss has a new error response 423 TSS creation locked. This error is returned transparently instead of 500 Internal server error.
  • 401 Unauthorized is returned transparently instead of 502 Bad Gateway (Log Shipping failed) in case of an expired access token.

v2.0.1

  • Metadata in updateTss were not stored persistently. New metadata now get combined with existing metadata of the TSS and then stored persistently.

Resources

TSS

The technical security system (TSS) resource represents the set of components that sign transactions. Each TSS is assigned an instance of SMAERS. A TSS can have a number of clients, transactions and exports associated with it.

The TSS changes its state as it moves through its lifecycle. The changelog describes how to perform TSS state change.

Client

The client resource is the representation of your electronic record-keeping system (ERS) in our system. A client must be associated with a TSS. A client can have only one TSS.

A client has its own state lifecycle. See changelog for info on how to manage the client state change.

Transaction

The transaction resource represents a transaction that needs to be signed. A transaction is associated with a TSS and a client that initiates the transaction.

The lifecycle states of a transaction resource are ACTIVE, FINISHED, and CANCELLED. At the start of a transaction, the state must be set to ACTIVE. The state stays ACTIVE until the transaction is finished or cancelled. The FINISHED state means that the transaction has been finished as expected. The CANCELLED state means that something went wrong and the transaction had to be cancelled.

Transaction UUID Uniqueness: Transaction UUIDs must be unique within each TSS. Although it is highly unlikely with properly generated UUIDs, the same UUIDs may reappear across different TSS instances.

Export

The export resource holds the state of the asynchronous generation of the export TAR file. The export TAR file contains the SMAERS initialization information, the signed log messages, and the certificates to verify them. A created export file is available until the time specified by the `time_expiration` attribute. After the `time_expiration` the export file is deleted permanently.

Errors and Status Codes

NOTE: DON'T BLOCK THE TILL

There is no obligation that the till should stop its operation, or be heavily affected, due to outages on the part of the Sign DE API! Please make sure that your integration is not blocking the checkout process.

If the API malfunctions or is unreachable, the tills should still be able to work, while noting the outage on the receipt. Please note the relevant information in the corresponding AO-Anwendungerlass from the German Federal Ministry of Finance.

Defective TSS

As a result of an irrecoverable error, the state of a TSS may be set to DEFECTIVE. This TSS can no longer be used for signing.

In this case the TSS should be replaced by the customer, by using the operation createTss to create a new TSS. Existing clients must be linked to the new TSS, each with a new client_id via endpoint createClient.

The following operations are impossible if TSS is DEFECTIVE:

The rest of the operations are still functioning. Triggering (triggerExport) and downloading (retrieveExportFile) exports (TAR file) is still possible.

The fiskaly SIGN DE 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-498 range indicate errors that have been caused by the requesting application (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. Status code 413 indicates that the request body was too large. Currently the size limit for requests bodies is 1 MB. Some 4xx errors can be handled programmatically. The error response is in JSON format and is structured like this:

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

The response will contain an error code or other information that reveals the reason of the error. Change the request accordingly before retrying. Below you can find the most frequent errors and how to fix them.

A special case is the status code 499: this indicates that the client connection was closed prematurely, this request can, and should, be retried 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. In case of a 429, the Retry-After header is included, indicating the number of seconds to wait before retrying.

General errors

400 Bad Request
  • E_TX_REVISION_NOT_FOUND

    No tx_revision could be found for the tx_revision from your request query. Run the Retrieve transaction endpoint without query parameters. Check the latest_revision field of the response to see the largest available tx_revision number.

  • E_TSS_NOT_INITIALIZED

    The TSS you are trying to access is not initialized. Run the Retrieve TSS endpoint and check the state of your TSS. If the state is "UNINITIALIZED", initialize the TSS by passing "INITIALIZED" in the state field of the Update TSS endpoint. If the state is "CREATED", run the Update TSS endpoint with "UNINITIALIZED" in the state field. Then initialize the TSS as described above. After that send your original request again.

  • E_TSS_DISABLED

    The TSS you are trying to access is disabled. The "DISABLED" state of the TSS cannot be reverted. Create a new TSS with the Create TSS endpoint. Then follow the usual workflow initializing the TSS and creating a new client.

  • E_ILLEGAL_TSS_STATE_CHANGE

    This TSS state update is not possible at the current stage of your workflow with this TSS. When the TSS is created, its state is set to "CREATED". Then it should be manually changed to "UNINITIALIZED". To do that, run the Update TSS endpoint with "UNINITIALIZED" in the state field. After that, the TSS can be initialized by passing "INITIALIZED" in the state field of the Update TSS endpoint. To disable the TSS, run the same route with "DISABLED" in the state field. Disabling the TSS requires its state to be either "UNINITIALIZED" or "INITIALIZED".

  • E_ILLEGAL_CLIENT_SERIAL

    Check the error message to see what is wrong with the serial_number you provided. The serial_number represents the unique identifier of the ERS (see 7.5. BSI TR-03153-TS. Make sure the serial_number is unique for the clients of this TSS. Apply the changes suggested by the error message and retry the request.

  • E_CLIENT_DEREGISTERED

    You must register the client before performing this operation on it. Register the client by passing "REGISTERED" in the state field of the Update client endpoint. Then send your original request again.

  • E_TX_LIMIT_REACHED

    A TSS is only allowed to have 2000 open ("ACTIVE") transactions. If you reached this limit, you won't be able to start new transactions until you cancel or finish the old ones. To finish a transaction, pass "FINISHED" in the state field of the upsertTransaction endpoint with all the required schema fields. To cancel a transaction, pass "CANCELLED" with all the required schema fields. Run the endpoint for all transactions that should be closed.

  • E_DUPLICATE_EXPORT

    This export has already been triggered. Run the Retrieve export endpoint and wait until the export is finished. Depending on the size, the export can take up to one hour to finish.

  • E_CANCEL_EXPORT

    The export has already been completed, cancelled or an error has occurred. The cancellation is possible only when the state of the export is "PENDING" or "WORKING". Run the Retrieve export endpoint. The state field of the response body will show the exact state of the export.

  • E_PARAMETER_MISMATCH

    You cannot trigger an export with this set of query parameters. Change your query parameters as the error message suggests. Then rerun your request.

  • E_CHANGE_ADMIN_PIN_FAILED

    The admin_puk you provided is not correct. Check the admin_puk you transmitting in the request and run the endpoint again.

  • E_FAILED_SCHEMA_VALIDATION

    The request failed to validate against the required OpenAPI schema. The details are described in the message property of the error.

401 Unauthorized
  • E_UNAUTHORIZED
    • Authenticate API

      Check that your api_key and api_secret are correct and that you are using the right environment (TEST or LIVE). Also make sure that you are not trying to authenticate with your dashboard user credentials. Rerun the request or create a new api_key/api_secret pair.

    • Authenticate Admin

      Make sure that you are using the correct admin_pin and rerun the request. If the problem persists, set a new admin_pin using your PUK. To change admin_pin, run the Change or Unblock Admin PIN request with your admin_puk and new_admin_pin.

403 Forbidden
  • E_TSS_LIMIT_REACHED

    You have reached the limit of active TSS in the test environment. Disable one of your TSS by passing "DISABLED" in the state field of the Update TSS endpoint. Then retry the Create TSS request.

  • E_TSS_LIMIT_PER_DAY_REACHED

    You have reached the limit for TSS creation per day.

  • E_CLIENT_LIMIT_REACHED

    You have reached the limit of active clients for this TSS. You can deregister the clients that are no longer in use or create a new TSS and register the client there. To deregister a client, pass "DEREGISTERED" in the state field of the Update client endpoint. To create a new TSS, run the Create TSS request with a new tss_id.

  • E_ACCESS_DENIED

    You may not access the requested resource or the organization from your request query doesn't match the organization from your JWT token. Check that the organization in the request query is correct. Run the Authenticate API endpoint. Make sure that organization_id is present in the access_token_claims field of the response body.

404 Resource does not exist
  • E_TSS_NOT_FOUND

    No TSS with the tss_id from your request has been found. Send a request to the Retrieve TSS endpoint with the tss_id check that the TSS exists.

  • E_CLIENT_NOT_FOUND

    No client could be found for the client_id and tss_id from your request. Check that the TSS exists with the Retrieve TSS endpoint. Check that the client exists on the TSS with the Retrieve client endpoint.

  • E_TX_NOT_FOUND

    No transaction could be found for the tss_id and tx_id_or_number from your request. Check that the TSS exists with the Retrieve TSS endpoint. Check that the transaction exists on the TSS with the Retrieve transaction endpoint.

  • E_EXPORT_NOT_FOUND

    No export could be found for the tss_id and export_id from your request. Check that the TSS exists with the Retrieve TSS endpoint. Check that the export exists on the TSS with the Retrieve export endpoint.

  • E_EXPORT_NOT_COMPLETED

    Export is not in the state COMPLETED. Run the Retrieve export endpoint. Check the state of the export and try again later. The Retry-After header is included and set to 60, indicating the number of seconds to wait before retrying.

  • E_LATEST_TX_REVISION_NOT_FOUND

    The latest tx_revision could not be found.

409 Conflict
  • E_TSS_CONFLICT

    A TSS with the specified tss_id already exists. Generate another tss_id and retry the request with it.

  • E_CLIENT_CONFLICT

    A client with the specified client_id already exists in the system. Generate another client_id and retry the request.

  • E_TX_ILLEGAL_TYPE_CHANGE

    The process_type from your request body is different from the _type in the transaction. Retrieve the transaction with the Retrieve transaction route and see the _type field of the response body. Make sure that it matches the process_type from your original request.

  • E_TX_NO_TYPE_DEFINED

    The process_type is missing from your request body. Retrieve the transaction with the Retrieve transaction route and see the _type field of the response body. Insert the value of _type into the process_type field of your request body and send it again.

  • E_TSS_ILLEGAL_STATE_TO_PERFORM_EXPORT

    Exports can only be performed when the TSS is in the state of "INITIALIZED" or "DISABLED". Run the Retrieve TSS endpoint and check the state field of your TSS. If the state is "CREATED", run the Update TSS endpoint with the state field set to "UNINITIALIZED". Then run this Update TSS endpoint with the state field set to "INITIALIZED".

    If the state of the TSS is "UNINITIALIZED", run the Update TSS request with "INITIALIZED" in the state field.

    If you no longer need your TSS but want to access the exports, you can disable the TSS. To disable the TSS, run the Update TSS request with "DISABLED" in the state field. You can only disable the TSS when it is in the state of "UNINITIALIZED" or "INITIALIZED". This change is permanent and cannot be undone.

  • E_PENDING_TX_CONFLICT

    A transaction with this tx_id already exists in the system. Generate another tx_id and retry the request. Make sure that the tx_id complies to the UUIDv4 standards.

  • E_EXPORT_DUPLICATE_RATE_LIMITED

    The export is refused for a given TSS when it has the same parameters of an export currently in PENDING or WORKING state for that particular TSS. You can resubmit the duplicate export request once the first one is completed.

  • E_TOO_MANY_EXPORTS

    Number of exports in PENDING or WORKING state is limited per TSS. Please wait until some of the exports are processed. Then you can trigger a new export.

  • E_EXPORT_IN_PROGRESS

    The operation cannot be performed due to a running export. Trigger exports after business hours (when there are no or few transactions going on).

423 Locked
  • E_ADMIN_PIN_BLOCKED

    Your admin_pin gets blocked after the initial creation of the TSS and after five unsuccessful authentication attempts. You must now reset your admin_pin. Run the Change or Unblock Admin PIN request with your admin_puk and new_admin_pin.

  • E_TSS_DEFECTIVE

    This TSS is in the state DEFECTIVE and cannot be used for the current operation. You can still use this TSS for retrieve and list operations.

  • E_TSS_DELETED

    This TSS is in the state DELETED and cannot be used for the current operation.

  • E_TSS_EVICTED

    This TSS is in the state EVICTED and cannot be used for the current operation.

  • E_AVAILABLE_ON_TEST_ONLY

    Experimental feature - Only available for TEST API Keys.

429 Too Many Requests

This error indicates that you have sent too many requests in a short period of time. Besides the 429 status code, the response will also contain a Retry-After header that indicates how long you should wait before retrying the request. The value of the Retry-After header is in seconds.

432 Use Middleware

Status 5xx

Status codes in the 500-599 range indicate errors on the server side. These errors 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. In case of 429 or 503 Service Unavailable response, the Retry-After header is included, indicating the number of seconds to wait before retrying.

502 Bad Gateway
  • SMAERS_GATEWAY_ERROR_PRECONDITION_UNEXPORTED_LOGS

    It is an expected error. The request is retried internally up to a limit. If the retry limit is reached, the error is returned by the API. Please retry the request if this error occurs.

  • ERROR_IDENTIFY_ERS

    It is an expected error. The request is retried internally up to a limit. If the retry limit is reached, the error is returned by the API. Please retry the request if this error occurs.

503 Service Unavailable
  • E_TSS_LOCKED This error indicates that the CSPL assigned to the resource being accessed is in maintenance mode. The request should be retried later when the maintenance is finished.

Known issues

  • If you're experiencing any problems with the fiskaly SIGN DE API, please check the fiskaly SIGN DE API status page or forward to Developer Support.
  • According to the schema, signature.counter in transaction responses must be of type string. However, our Middleware returns it as a number. In the future, signature.counter will be returned as string. For now, please, make sure that your implementation can accept both number and string.
  • The BSI Technical Guidelines dictate that TSS TAR export files must adhere to "The Open Group: POSIX.1-1988 - Portable Operating System Interface, 1988" format, which restricts file names to 99 characters. Using extensions for longer names is not allowed per these Guidelines. File names within the TAR file are derived from various attributes, some beyond the developer's control (like incorporating client IDs). Occasionally, these names exceed 99 characters. In such cases, the TAR file switches to PAX format, employing extensions for longer names, but only if the TAR file contains a name longer than 99 characters. BSI-approved discussions confirm that this behavior, while exceeding 99 characters, is intentional and shall not be altered.

How to raise an Issue

At fiskaly we strive to always improve ourselves, our systems and quality that we deliver. As in all software projects, there will be issues as well. We're living a transparent operation process, and will inform about known operation problems via status.fiskaly.com. Before raising a new issue, please check there first.

Please read the article How to raise an issue to provide us with all required details in case of an issue, so that it can be solved in your interest as soon as possible.

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. Download the Postman application.

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

  3. Insert your API key and secret to get your personalized Postman environment:

  1. Download the Postman collection.

  2. Start Postman and select Upload Files from the Import dialog:

    File > Import (Ctrl+O)

    postman upload files

  3. Select the collection and environment files that you downloaded:

    postman select files

  4. The Postman screen should now look like this:

    postman screen

  5. Select the Sign API v2 environment:

    postman select environment

  6. Run the demo:

    postman run demo

Authentication

Authenticate API

To access our API, you need to have a valid JWT token. This endpoint creates the token with your api_key and api_secret. If you don't have an api_key, you can create one via the fiskaly dashboard. The api_secret will be generated for you after you create the api_key. The token must be sent with every following request in the Authorization header field using the Bearer authentication scheme. See details here.

WARNING: even if you delete or otherwise deactivate your API credentials, any generated tokens will remain valid until they expire (currently up to 24 hours).

Authorizations:
JWT
Request Body schema: application/json
One of
api_key
required
string (ApiKeyKey)

Key of an API Key

api_secret
required
string (ApiKeySecret)

Secret of an API Key

Responses

Request samples

Content type
application/json
Example
{
  • "api_key": "string",
  • "api_secret": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "access_token_claims": {
    },
  • "access_token_expires_in": 0,
  • "access_token_expires_at": 1577833200,
  • "refresh_token": "string",
  • "refresh_token_expires_in": 0,
  • "refresh_token_expires_at": 1577833200
}

Authenticate Admin

Only available via Middleware

This endpoint allows the TSS administrator (the taxpayer) to access restricted functionality. The administrator needs to provide their PIN. The PIN is then verified inside the TSS. The login only happens within the current session. After a new TSS has been created, the administrator needs to set a new PIN. We recommend choosing a unique PIN for every TSS. This will increase the security of your resources.

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

Identifies a TSS

Request Body schema: application/json
required
admin_pin
required
string (AdminPin) >= 6 characters

Represents the PIN for the authentication. (TR-03151)

Responses

Request samples

Content type
application/json
{
  • "admin_pin": "AB1234"
}

Response samples

Content type
application/json
{ }

Logout Admin

Only available via Middleware

Use this endpoint to exit the administrator mode.

Log out as soon as you have finished making administrative changes.

This operation can be called safely even if no admin is authenticated.

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

Identifies a TSS

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Technical Security System

Create a TSS

This endpoint creates a TSS. The TSS is identified by a tss_id. The tss_id must comply with the UUIDv4 standard and should be generated on your side. When you create a TSS, its state is set to "CREATED". The response for this endpoint will contain the admin PUK. The administrator will need the PUK to set the admin PIN. Make sure to store the PUK securely. When the TSS has left the state "CREATED", you will no longer be able to see the PUK. Use the Update a TSS endpoint to transition to state "UNINITIALIZED".

WARNING: Future major versions of SIGN DE API will strictly enforce UUIDv4 format requirements. Verifying that your "tss_id" conforms to the UUIDv4 standard to ensure compatibility is recommended.

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

Identifies a TSS

Request Body schema: application/json
object (MetadataRequest) <= 40 properties

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

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "certificate": "string",
  • "serial_number": "string",
  • "public_key": "string",
  • "signature_algorithm": "ecdsa-plain-SHA256",
  • "signature_timestamp_format": "unixTime",
  • "transaction_data_encoding": "UTF-8",
  • "max_number_registered_clients": 9007199254740991,
  • "max_number_active_transactions": 9007199254740991,
  • "supported_update_variants": "SIGNED",
  • "metadata": {},
  • "_id": "00000000-0000-0000-0000-000000000000",
  • "_type": "TSS",
  • "_env": "TEST",
  • "_version": "2.2.2",
  • "time_creation": 1577833200,
  • "admin_puk": "ABCD123456",
  • "state": "CREATED"
}

Retrieve a TSS

This endpoint returns information about a specific TSS.

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

Identifies a TSS

Responses

Response samples

Content type
application/json
{
  • "certificate": "string",
  • "serial_number": "string",
  • "public_key": "string",
  • "signature_algorithm": "ecdsa-plain-SHA256",
  • "signature_timestamp_format": "unixTime",
  • "transaction_data_encoding": "UTF-8",
  • "max_number_registered_clients": 9007199254740991,
  • "max_number_active_transactions": 9007199254740991,
  • "supported_update_variants": "SIGNED",
  • "metadata": {},
  • "_id": "00000000-0000-0000-0000-000000000000",
  • "_type": "TSS",
  • "_env": "TEST",
  • "_version": "2.2.2",
  • "time_creation": 1577833200,
  • "description": "fiskaly sign cloud-TSE (tss_id)",
  • "state": "CREATED",
  • "bsi_certification_id": "string",
  • "signature_counter": "string",
  • "transaction_counter": "string",
  • "number_registered_clients": 9007199254740991,
  • "number_active_transactions": 9007199254740991,
  • "time_uninit": 1577833200,
  • "time_init": 1577833200,
  • "time_defective": 1577833200,
  • "time_disable": 1577833200
}

Update a TSS

Only available via Middleware

Requires Admin Authentication for state change to INITIALIZED and DISABLED

When you create a TSS, its state is set to "CREATED". After creating the TSS, you need to deploy it. Deploying the TSS means starting a new SMAERS process associated with it. To deploy a TSS, set its state to "UNINITIALIZED".

This process may take longer than other requests. For this reason the timeout for updating to state "UNINITIALIZED" MUST be increased to at least 30 seconds!

If the update is not successful, the request should be repeated. It is recommended to perform this request during times with lower system load, such as the early morning or late evening.

After deploying the TSS, you need to initialize it. Only initialized TSS can process transactions. To initialize the TSS, set its state to "INITIALIZED". Only when initializing a TSS, a description may be provided.

If you don't need the TSS anymore, you can disable it. To disable the TSS, set its state to "DISABLED". Only the TSS in the states "UNINITIALIZED" or "INITIALIZED" can be disabled. Disabling a TSS is permanent and can't be undone.

TSS metadata can be updated alongside state, or by providing the same state along with the new metadata.

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

Identifies a TSS

Request Body schema: application/json
required
description
string (TssDescription) ^[A-Za-z0-9 '()+,-./:=?]{0,100}$

Description of TSS

state
required
string
Enum: "UNINITIALIZED" "INITIALIZED" "DISABLED"
object (MetadataRequest) <= 40 properties

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

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "description": "fiskaly sign cloud-TSE (tss_id)",
  • "state": "UNINITIALIZED",
  • "certificate": "string",
  • "serial_number": "string",
  • "public_key": "string",
  • "bsi_certification_id": "string",
  • "signature_counter": "string",
  • "signature_algorithm": "ecdsa-plain-SHA256",
  • "signature_timestamp_format": "unixTime",
  • "transaction_counter": "string",
  • "transaction_data_encoding": "UTF-8",
  • "number_registered_clients": 9007199254740991,
  • "max_number_registered_clients": 9007199254740991,
  • "number_active_transactions": 9007199254740991,
  • "max_number_active_transactions": 9007199254740991,
  • "supported_update_variants": "SIGNED",
  • "metadata": {},
  • "_id": "00000000-0000-0000-0000-000000000000",
  • "_type": "TSS",
  • "_env": "TEST",
  • "_version": "2.2.2",
  • "time_creation": 1577833200,
  • "time_uninit": 1577833200,
  • "time_init": 1577833200,
  • "time_defective": 1577833200,
  • "time_disable": 1577833200
}

Change or Unblock Admin PIN

Only available via Middleware

This endpoint allows the administrator to change or unblock their PIN. The admin PIN is blocked and must be reset after the initial creation of a TSS and after five unsuccessful authentication attempts.

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

Identifies a TSS

Request Body schema: application/json
required
admin_puk
required
string (AdminPuk) >= 10 characters

Represents the PUK of the user/application. (TR-03151)

new_admin_pin
required
string (AdminPin) >= 6 characters

Represents the PIN for the authentication. (TR-03151)

Responses

Request samples

Content type
application/json
{
  • "admin_puk": "ABCD123456",
  • "new_admin_pin": "AB1234"
}

Response samples

Content type
application/json
{ }

List TSS

This endpoint lists all available TSS.

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

Specifies the property to sort by

states
Array of strings[ items unique ]
Items Enum: "CREATED" "UNINITIALIZED" "INITIALIZED" "DISABLED" "DELETED" "DEFECTIVE" "EVICTED"

Filter to include only specific states of TSS

Example: states%5B0%5D=DISABLED&states%5B1%5D=INITIALIZED

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

Determines the sorting order

limit
integer [ 1 .. 100 ]
Default: 100

Limits the number of returned results

offset
integer >= 0
Default: 0

Skips the specified number of results from the result set

show_deleted
boolean
Default: true
Enum: false true

Set to true to include the resources of deleted TSS, set to false to hide them.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 9007199254740991,
  • "_type": "TSS_LIST",
  • "_env": "TEST",
  • "_version": "2.2.2"
}

Retrieve metadata of a TSS

This endpoint retrieves additional structured information about a TSS.

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

Identifies a TSS

Responses

Response samples

Content type
application/json
{}

Update metadata of a TSS

This endpoint creates or updates additional structured information about a TSS.

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

Identifies a TSS

Request Body schema: application/json

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.

<= 40 properties
property name*
additional property
string <= 500 characters

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Clients

Create a client

Only available via Middleware

Requires Admin Authentication

This endpoint creates a new client and associates it with a TSS.

The state of a new client is automatically set to "REGISTERED". Only a client in a "REGISTERED" state can use the TSS.

The client_id must be a randomly generated UUIDv4. The client_id must stay unique throughout the system. You cannot use the same client_id to create a client for a different TSS.

The serial_number is required by the SIGN DE API to be unique within each TSS. However, please be aware that BSI TR-03153-1 Chapter 9.3.1 requires the the serial_number to be uniquely assigned to a single ERS within the context of each ERS manufacturer.

Please note that with DSFinV-K version 2.3 the requirements regarding serial_number have changed. To comply with this change, the serial number must not contain a slash ("/") or underscore ("_"). Further information on the DSFinV-K can be found on the German Federal Central Tax Office website.

Before making use of DSFinV-K version 2.3, which is mandatory at the latest from July 1, 2022, all clients that currently use slashes ("/") or underscores ("_") in the serial_number field must be updated to state DEREGISTERED and replaced by a new client that complies with the requirements of DSFinV-K version 2.3.

According to DSFinV-K serial_number must not be longer than 70 characters.

WARNING: Future major versions of SIGN DE API will strictly enforce UUIDv4 format requirements. Verifying that your "client_id" conforms to the UUIDv4 standard to ensure compatibility is recommended.

Authorizations:
JWT
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
required
serial_number
required
string (ClientSerialNumber) non-empty ^(?!\s)[A-Za-z0-9 '()+,-./:=?]{0,70}(?<!\s)$

Unique identifier of the ERS see 7.5. BSI TR-03153.
Please note that the regular expression for this property is subject to change in a future version of the API to reflect the change introduced with DSFinV-K version 2.3.
For technical reasons, from DSFinV-K Version 2.3 on, neither a slash ("/") nor an underscore ("_") may be used in the serial_number of the client.
According to DSFinV-K serial_number must not be longer than 70 characters.

object (MetadataRequest) <= 40 properties

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

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "serial_number": "string",
  • "state": "REGISTERED",
  • "tss_id": "00000000-0000-0000-0000-000000000000",
  • "metadata": {},
  • "_id": "00000000-0000-0000-0000-000000000000",
  • "_type": "CLIENT",
  • "_env": "TEST",
  • "_version": "2.2.2",
  • "time_creation": 1577833200
}

Retrieve a client

This endpoint retrieves information about a specific client.

Authorizations:
JWT
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

Response samples

Content type
application/json
{
  • "serial_number": "string",
  • "state": "REGISTERED",
  • "tss_id": "00000000-0000-0000-0000-000000000000",
  • "metadata": {},
  • "_id": "00000000-0000-0000-0000-000000000000",
  • "_type": "CLIENT",
  • "_env": "TEST",
  • "_version": "2.2.2",
  • "time_creation": 1577833200,
  • "time_update": 1577833200
}

Update a client

Only available via Middleware

Requires Admin Authentication

Use this endpoint to update a client. Only a client in a "REGISTERED" state can use the TSS.

Note: This endpoint updates the existing metadata without overwriting it. When new metadata is provided, it is merged with the existing metadata.

Authorizations:
JWT
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
required
state
required
string
Enum: "REGISTERED" "DEREGISTERED"

Defines the state of a Client in the TSS. Only registered clients are able to write transactions.

object (MetadataRequest) <= 40 properties

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

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "serial_number": "string",
  • "state": "REGISTERED",
  • "tss_id": "00000000-0000-0000-0000-000000000000",
  • "metadata": {},
  • "_id": "00000000-0000-0000-0000-000000000000",
  • "_type": "CLIENT",
  • "_env": "TEST",
  • "_version": "2.2.2",
  • "time_creation": 1577833200,
  • "time_update": 1577833200
}

List all clients

This endpoint lists the clients of all available TSS.

Authorizations:
JWT
query Parameters
order_by
string
Enum: "serial_number" "time_creation"

Specifies the property to sort by

serial_number
string

Filter to return only specific clients

state
string
Enum: "REGISTERED" "DEREGISTERED"
Example: state=REGISTERED

Defines the state of a Client in the TSS. Only registered clients are able to write transactions.

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

Determines the sorting order

limit
integer [ 1 .. 100 ]
Default: 100

Limits the number of returned results

offset
integer >= 0
Default: 0

Skips the specified number of results from the result set

show_deleted
boolean
Default: true
Enum: false true

Set to true to include the resources of deleted TSS, set to false to hide them.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 9007199254740991,
  • "_type": "CLIENT_LIST",
  • "_env": "TEST",
  • "_version": "2.2.2"
}

List clients of a TSS

This endpoint lists the clients of a specific TSS.

Authorizations:
JWT
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"

Specifies the property to sort by

serial_number
string

Filter to return only specific clients

state
string
Enum: "REGISTERED" "DEREGISTERED"
Example: state=REGISTERED

Defines the state of a Client in the TSS. Only registered clients are able to write transactions.

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

Determines the sorting order

limit
integer [ 1 .. 100 ]
Default: 100

Limits the number of returned results

offset
integer >= 0
Default: 0

Skips the specified number of results from the result set

show_deleted
boolean
Default: true
Enum: false true

Set to true to include the resources of deleted TSS, set to false to hide them.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 9007199254740991,
  • "_type": "CLIENT_LIST",
  • "_env": "TEST",
  • "_version": "2.2.2"
}

List transactions of a client

This endpoint lists the transactions of a specific client.

Authorizations:
JWT
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

states
Array of strings (TxState)
Items Enum: "ACTIVE" "CANCELLED" "FINISHED"

Filter to include only specific states

Example: states%5B0%5D=FINISHED&states%5B1%5D=CANCELLED

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

Determines the sorting order

limit
integer [ 1 .. 100 ]
Default: 100

Limits the number of returned results

offset
integer >= 0
Default: 0

Skips the specified number of results from the result set

show_deleted
boolean
Default: true
Enum: false true

Set to true to include the resources of deleted TSS, set to false to hide them.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 9007199254740991,
  • "_type": "TRANSACTION_LIST",
  • "_env": "TEST",
  • "_version": "2.2.2"
}

Retrieve metadata of a client

This endpoint retrieves additional structured information about a client.

Authorizations:
JWT
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

Response samples

Content type
application/json
{}

Update metadata of a client

This endpoint creates or updates additional structured information about a client.

Authorizations:
JWT
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

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.

<= 40 properties
property name*
additional property
string <= 500 characters

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Transactions

List all transactions

This endpoint lists the transactions of all available TSS.

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

Specifies the property to sort by

states
Array of strings (TxState)
Items Enum: "ACTIVE" "CANCELLED" "FINISHED"

Filter to include only specific states

Example: states%5B0%5D=FINISHED&states%5B1%5D=CANCELLED

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

Determines the sorting order

limit
integer [ 1 .. 100 ]
Default: 100

Limits the number of returned results

offset
integer >= 0
Default: 0

Skips the specified number of results from the result set

show_deleted
boolean
Default: true
Enum: false true

Set to true to include the resources of deleted TSS, set to false to hide them.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 9007199254740991,
  • "_type": "TRANSACTION_LIST",
  • "_env": "TEST",
  • "_version": "2.2.2"
}

List transactions of a TSS

This endpoint lists the transactions of a specific TSS.

Authorizations:
JWT
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

states
Array of strings (TxState)
Items Enum: "ACTIVE" "CANCELLED" "FINISHED"

Filter to include only specific states

Example: states%5B0%5D=FINISHED&states%5B1%5D=CANCELLED

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

Determines the sorting order

limit
integer [ 1 .. 100 ]
Default: 100

Limits the number of returned results

offset
integer >= 0
Default: 0

Skips the specified number of results from the result set

show_deleted
boolean
Default: true
Enum: false true

Set to true to include the resources of deleted TSS, set to false to hide them.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 9007199254740991,
  • "_type": "TRANSACTION_LIST",
  • "_env": "TEST",
  • "_version": "2.2.2"
}

Retrieve a transaction

This endpoint returns information about a specific transaction. The transaction is identified by the tx_id_or_number path parameter. This endpoint will return a specific revision of the transaction if the tx_revision query parameter is set. If no revision is present in the query, the latest revision is returned.

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

Identifies a TSS

required
TxId (string) or TxNum (integer)

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

query Parameters
tx_revision
integer [ 1 .. 9007199254740991 ]

Responses

Response samples

Content type
application/json
{
  • "number": 9007199254740991,
  • "time_start": 1577833200,
  • "client_serial_number": "string",
  • "tss_serial_number": "string",
  • "state": "ACTIVE",
  • "client_id": "00000000-0000-0000-0000-000000000000",
  • "schema": {
    },
  • "revision": 1,
  • "latest_revision": 1,
  • "tss_id": "00000000-0000-0000-0000-000000000000",
  • "metadata": {},
  • "_type": "TRANSACTION",
  • "_id": "00000000-0000-0000-0000-000000000000",
  • "_env": "TEST",
  • "_version": "2.2.2",
  • "time_end": 1577833200,
  • "qr_code_data": "V0;955002-00;Kassenbeleg-V1;Beleg^0.00_2.55_0.00_0.00_0.00^2.55:Bar;18;112;2019-07-10T18:41:04.000Z;2019-07-10T18:41:04.000Z;ecdsa-plain-SHA256;unixTime;MEQCIAy4P9k+7x9saDO0uRZ4El8QwN+qTgYiv1DIaJIMWRiuAiAt+saFDGjK2Yi5Cxgy7PprXQ5O0seRgx4ltdpW9REvwA==;BHhWOeisRpPBTGQ1W4VUH95TXx2GARf8e2NYZXJoInjtGqnxJ8sZ3CQpYgjI+LYEmW5A37sLWHsyU7nSJUBemyU=",
  • "log": {
    },
  • "signature": {
    }
}

Start, update or finish a transaction

Only available via Middleware

Use this endpoint to change the state of a transaction.

To start a transaction, set the state field of the request body to "ACTIVE". When you update the transaction, the state must also be set to "ACTIVE".

There are two ways to end a transaction:

  1. If the transaction has finished as expected, set the state to "FINISHED".
  2. If something went wrong and you want to cancel the transaction, set the state to "CANCELLED".

The query string for this endpoint 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.

All the data in the schema field of the request body must be UTF-8 encoded.

When you start a transaction, the type and data of the transaction must be empty. This is required by the DSFinV-K (v2.1).

Note: A TSS is only allowed to have 2000 open (type= "ACTIVE") transactions. In case a TSS reaches this limit, you need to manually close (set to "CANCELLED" / "FINISHED", depending on your process) the open transactions.

Note: This endpoint updates the existing metadata without overwriting it. When new metadata is provided, it is merged with the existing metadata.

Note: A transaction with the dsfinvtw_v1 schema can be only be started and finished. Updates and cancelling are not possible.

Note: For transaction UUID uniqueness requirements refer to the transaction resource description section.

WARNING: Future major versions of SIGN DE API will strictly enforce UUIDv4 format requirements. If a UUID is being used in "tx_id_or_number", verifying that it conforms to the UUIDv4 standard to ensure compatibility is recommended.

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

Identifies a TSS

required
TxId (string) or TxNum (integer)

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

query Parameters
tx_revision
integer [ 1 .. 9007199254740991 ]
Request Body schema: application/json
required
state
required
string (TxState)
Default: "ACTIVE"
Enum: "ACTIVE" "CANCELLED" "FINISHED"
client_id
required
string <uuid> (ClientId)

Identifies a client by a self-generated UUIDv4

object or object or object (TxSchema) = 1 properties
object (MetadataRequest) <= 40 properties

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

Request samples

Content type
application/json
{
  • "state": "ACTIVE",
  • "client_id": "00000000-0000-0000-0000-000000000000",
  • "schema": {
    },
  • "metadata": {}
}

Response samples

Content type
application/json
{
  • "number": 9007199254740991,
  • "time_start": 1577833200,
  • "client_serial_number": "string",
  • "tss_serial_number": "string",
  • "state": "ACTIVE",
  • "client_id": "00000000-0000-0000-0000-000000000000",
  • "schema": {
    },
  • "revision": 1,
  • "latest_revision": 1,
  • "tss_id": "00000000-0000-0000-0000-000000000000",
  • "metadata": {},
  • "_type": "TRANSACTION",
  • "_id": "00000000-0000-0000-0000-000000000000",
  • "_env": "TEST",
  • "_version": "2.2.2",
  • "time_end": 1577833200,
  • "qr_code_data": "V0;955002-00;Kassenbeleg-V1;Beleg^0.00_2.55_0.00_0.00_0.00^2.55:Bar;18;112;2019-07-10T18:41:04.000Z;2019-07-10T18:41:04.000Z;ecdsa-plain-SHA256;unixTime;MEQCIAy4P9k+7x9saDO0uRZ4El8QwN+qTgYiv1DIaJIMWRiuAiAt+saFDGjK2Yi5Cxgy7PprXQ5O0seRgx4ltdpW9REvwA==;BHhWOeisRpPBTGQ1W4VUH95TXx2GARf8e2NYZXJoInjtGqnxJ8sZ3CQpYgjI+LYEmW5A37sLWHsyU7nSJUBemyU=",
  • "log": {
    },
  • "signature": {
    }
}

Retrieve a signed transaction log Deprecated

This endpoint returns the log message of a specific transaction. The transaction is identified by the tx_id_or_number path parameter. This endpoint will return a specific revision of the transaction if the tx_revision query parameter is set. If no revision is present in the query, the latest revision is returned.

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

Identifies a TSS

required
TxId (string) or TxNum (integer)

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

query Parameters
tx_revision
integer [ 1 .. 9007199254740991 ]

Responses

Retrieve metadata of a transaction

This endpoint retrieves additional structured information about a transaction.

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

Identifies a TSS

required
TxId (string) or TxNum (integer)

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

Responses

Response samples

Content type
application/json
{}

Update metadata of a transaction

This endpoint creates or updates additional structured information about a transaction.

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

Identifies a TSS

required
TxId (string) or TxNum (integer)

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

Request Body schema: application/json

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.

<= 40 properties
property name*
additional property
string <= 500 characters

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Data Exports

Cancel an export

This endpoint cancels an ongoing export operation.

You can cancel the export when it is in the states "PENDING" or "WORKING". If you run this endpoint before the export is complete, the export TAR file will not be generated.

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

Identifies a TSS

export_id
required
string <uuid>
Example: 00000000-0000-0000-0000-000000000000

Identifies an Export

Responses

Response samples

Content type
application/json
{
  • "state": "PENDING",
  • "time_request": 1761124061,
  • "_type": "EXPORT",
  • "_id": "81f2f226-4bbf-421b-8583-76d39ca3be31",
  • "_env": "TEST",
  • "_version": "2.2.2",
  • "metadata": { },
  • "tss_id": "34601cc0-70cc-42a0-b671-cb71ea8505ed"
}

Retrieve an export

This endpoint returns the export resource.

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

Identifies a TSS

export_id
required
string <uuid>
Example: 00000000-0000-0000-0000-000000000000

Identifies an Export

Responses

Response samples

Content type
application/json
{
  • "state": "PENDING",
  • "time_request": 1761124061,
  • "_type": "EXPORT",
  • "_id": "81f2f226-4bbf-421b-8583-76d39ca3be31",
  • "_env": "TEST",
  • "_version": "2.2.2",
  • "metadata": { },
  • "tss_id": "34601cc0-70cc-42a0-b671-cb71ea8505ed"
}

Trigger an export

This endpoint triggers an export and returns a reference to the export resource.

Note: The query parameter client_id is not meant to be used in combination with other query parameters.

WARNING: triggering an export may interfere with the normal operations of the TSS. A large export can prevent the TSS from signing transaction data. Trigger exports when you don't need to sign transactions. For example, when doing a cash point closing.

WARNING: Duplicate export requests sent to a TSS are rate-limited. You cannot trigger concurrent identical export request. If you want to execute the same export multiple times, please ensure the previous one has completed first.

WARNING: The total number of exports in WORKING and PENDING states must not exceed 10 per TSS. Please wait for the previous exports to complete before triggering a new one.

Please pay attention so that the parameters start_signature_counter and end_signature_counter do not exceed the range defined in maximum_number_records. The default setting for maximum_number_records is 1000000, which is also the maximal allowed number.

If you want to export more than maximum_number_records, since the customer can define a maximum_number_records < 1000000, please do it by several exports.

E.g. if tss.signature_counter is equal to 2500000 and maximum_number_records is not set (i.e., it is by default 1000000), then a complete export of all TSS records should be done in 3 batches:

  1. First export with end_signature_counter=1000000
  2. Second export with start_signature_counter=1000001 and end_signature_counter=2000000
  3. Third export with start_signature_counter=2000001

WARNING: Future major versions of SIGN DE API will strictly enforce UUIDv4 format requirements. Verifying that your "export_id" conforms to the UUIDv4 standard to ensure compatibility is recommended.

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

Identifies a TSS

export_id
required
string <uuid>
Example: 00000000-0000-0000-0000-000000000000

Identifies an Export

query Parameters
client_id
string

Only return log messages associated with the given client (other query parameters will be ignored).

transaction_number
string^\d+$

Only return log messages associated with the given transaction number.

start_transaction_number
string^\d+$

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

end_transaction_number
string^\d+$

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

start_date
integer [ 0 .. 9007199254740991 ]
Example: start_date=1577833200

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

end_date
integer [ 0 .. 9007199254740991 ]
Example: end_date=1577833200

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

maximum_number_records
string^\d+$
Default: "1000000"

This parameter can be used to limit the amount of signatures to be exported. If this amount is higher than the limit of 1000000 signatures (records), the export results in E_TOO_MANY_RECORDS error.

Minimal value is "1".

Maximal value is "1000000".

start_signature_counter
string^\d+$

Only return log messages with signature counters larger than or equal to the given value.

end_signature_counter
string^\d+$

Only return log messages with signature counters smaller than or equal to the given value.

Responses

Response samples

Content type
application/json
{
  • "state": "PENDING",
  • "time_request": 1761124061,
  • "_type": "EXPORT",
  • "_id": "81f2f226-4bbf-421b-8583-76d39ca3be31",
  • "_env": "TEST",
  • "_version": "2.2.2",
  • "metadata": { },
  • "tss_id": "34601cc0-70cc-42a0-b671-cb71ea8505ed"
}

List all exports

This endpoint lists the exports of all available TSS.

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

Specifies the property to sort by

states
Array of strings[ items unique ]
Items Enum: "CANCELLED" "PENDING" "WORKING" "COMPLETED" "ERROR"

Filter to include only specific states

Example: states%5B0%5D=PENDING&states%5B1%5D=WORKING

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

Determines the sorting order

limit
integer [ 1 .. 100 ]
Default: 100

Limits the number of returned results

offset
integer >= 0
Default: 0

Skips the specified number of results from the result set

show_deleted
boolean
Default: true
Enum: false true

Set to true to include the resources of deleted TSS, set to false to hide them.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 9007199254740991,
  • "_type": "EXPORT_LIST",
  • "_env": "TEST",
  • "_version": "2.2.2"
}

List exports of a TSS

This endpoint lists the exports of a specific TSS.

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

Identifies a TSS

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

Specifies the property to sort by

states
Array of strings[ items unique ]
Items Enum: "CANCELLED" "PENDING" "WORKING" "COMPLETED" "ERROR"

Filter to include only specific states

Example: states%5B0%5D=PENDING&states%5B1%5D=WORKING

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

Determines the sorting order

limit
integer [ 1 .. 100 ]
Default: 100

Limits the number of returned results

offset
integer >= 0
Default: 0

Skips the specified number of results from the result set

show_deleted
boolean
Default: true
Enum: false true

Set to true to include the resources of deleted TSS, set to false to hide them.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 9007199254740991,
  • "_type": "EXPORT_LIST",
  • "_env": "TEST",
  • "_version": "2.2.2"
}

Retrieve the TAR file generated by an export operation

This endpoint returns the TAR file generated by the export operation.

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

Identifies a TSS

export_id
required
string <uuid>
Example: 00000000-0000-0000-0000-000000000000

Identifies an Export

Responses

Retrieve metadata of an export

This endpoint retrieves additional structured information about an export.

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

Identifies a TSS

export_id
required
string <uuid>
Example: 00000000-0000-0000-0000-000000000000

Identifies an Export

Responses

Response samples

Content type
application/json
{}

Update metadata of an export

This endpoint creates or updates additional structured information about an export.

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

Identifies a TSS

export_id
required
string <uuid>
Example: 00000000-0000-0000-0000-000000000000

Identifies an Export

Request Body schema: application/json

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.

<= 40 properties
property name*
additional property
string <= 500 characters

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Was this page helpful?