{ "openapi": "3.0.3", "info": { "title": "fiskaly SIGN DE API", "description": "Imprint: [fiskaly.com/impressum](https://fiskaly.com/impressum) | Privacy Policy: [fiskaly.com/datenschutz](https://fiskaly.com/datenschutz)\n\n# Introduction\n\nThe fiskaly SIGN DE API is a [RESTful](https://wikipedia.org/wiki/Representational_state_transfer) 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).\n\nThe fiskaly SIGN DE API is a platform-independent and software-only solution.\nThe only thing you need to integrate the fiskaly SIGN DE API is a stable Internet connection.\n\nThe fiskaly SIGN DE API:\n\n- has resource-oriented URLs,\n- accepts [JSON](https://wikipedia.org/wiki/JSON)-encoded request bodies,\n- returns [JSON](https://wikipedia.org/wiki/JSON)-encoded responses,\n- uses standard HTTP status codes and verbs,\n- is easy to integrate with your system.\n\nThe obligations regarding the declaration requirement ([Mitteilungspflicht](https://www.bundesfinanzministerium.de/Content/DE/Downloads/BMF_Schreiben/Weitere_Steuerthemen/Abgabenordnung/AO-Anwendungserlass/2023-06-30-AEAO-Par-146-AO.pdf?__blob=publicationFile&v=2)) under [§146a (4) AO](https://www.gesetze-im-internet.de/ao_1977/__146a.html) starting with 2025 can be fulfilled by using the fiskaly [SUBMIT DE](https://workspace.fiskaly.com/api/sign-de/submission/v1).\n\n## Components\n\nThe fiskaly CTSS has to be integrated in your ERS. It consists of two components:\n\n- fiskaly SMAERS (Security Module Application for Electronic Record-keeping Systems) and\n- fiskaly CSP-L (Cryptographic Service Provider Light).\n\nThe 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](mailto:sales@fiskaly.com).\n### ERS (Electronic Record-keeping System)\n\nThe Electronic Record-keeping System (ERS) creates digital records of business transactions. \nIt consists of workstations, input devices (PCs, iPads etc.), server systems, middleware, archives, and transaction processing units.\nThe exact composition of the ERS depends on the Point of Sale (PoS) vendor. For more information, see the [legal definition of the ERS](https://www.bundesfinanzministerium.de/Content/DE/Downloads/BMF_Schreiben/Weitere_Steuerthemen/Abgabenordnung/AO-Anwendungserlass/2018-06-19-aenderung-anwendungserlass-abgabenordnung-Einzelaufzeichnungspflicht.pdf?__blob=publicationFile&v=4).\n### Security Module Application for Electronic Record-keeping Systems (SMAERS)\n\nThe 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.\nThe signed transaction logs are stored in a secure storage. The storage is provided by fiskaly.\n\nThe SMAERS Server must not be operated by the PoS vendor, taxpayer or an entity dependent on the taxpayer.\nIn 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`).\n\n### Cryptographic Service Provider Light (CSP-L)\n\nThe 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. \n\n### fiskaly sign Middleware\n\nThe fiskaly sign Middleware provides a unified interface for the SMAERS component and the storage backend.\n\n## Background\n\nThe fiskaly SIGN DE API implements a set of legal requirements and technical guidelines.\nThe current version `2.2.2` of this API is based on the following regulations:\n\n- [KassenSichV](https://www.bundesfinanzministerium.de/Content/DE/Gesetzestexte/Gesetze_Gesetzesvorhaben/Abteilungen/Abteilung_IV/18_Legislaturperiode/Gesetze_Verordnungen/2017-10-06-KassenSichV/0-Verordnung.html) (2017-10)\n- [BSI TR-03153](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR03153/TR-03153.pdf?__blob=publicationFile) (v1.0.1)\n- [BSI TR-03153-TS](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR03153/TR-03153-TS.pdf?__blob=publicationFile) (v1.0.1)\n- [BSI TR-03151](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR03151/TR-03151.pdf?__blob=publicationFile) (v1.0.1)\n- [BSI TR-03116-5](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR03116/BSI-TR-03116-5.pdf?__blob=publicationFile) (2019-02)\n- [BSI-CC-PP-0105-V2-2020](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Zertifizierung/Reporte/ReportePP/pp0105V2b_pdf.pdf?__blob=publicationFile&v=2) (v1.0)\n- [BSI-CC-PP-0111-2019](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Zertifizierung/Reporte/ReportePP/pp0111b_pdf.pdf?__blob=publicationFile&v=4) (v1.0)\n- [BSI-CC-PP-0112-2020](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Zertifizierung/Reporte/ReportePP/pp0112b_pdf.pdf?__blob=publicationFile&v=2) (v1.0)\n- [BSI-CC-PP-0113-2020](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Zertifizierung/Reporte/ReportePP/pp0113b_pdf.pdf?__blob=publicationFile&v=3) (v1.0)\n- [DFKA-Taxonomie Kassendaten](https://dfka.net/taxonomie/) (v1.1)\n- [Anwendungserlass zu § 146a AO](https://www.bundesfinanzministerium.de/Content/DE/Downloads/BMF_Schreiben/Weitere_Steuerthemen/Abgabenordnung/AO-Anwendungserlass/2019-06-17-einfuehrung-paragraf-146a-AO-anwendungserlass-zu-paragraf-146a-AO.pdf?__blob=publicationFile&v=1) (2019-06-17)\n- [DSFinV-K](https://www.bzst.de/DE/Unternehmen/Aussenpruefungen/DigitaleSchnittstelleFinV/digitaleschnittstellefinv_node.html) (v2.3)\n- [DSFinV-TW](https://www.bzst.de/DE/Unternehmen/Aussenpruefungen/DigitaleSchnittstelleTaxameter/digitaleSchnittstelleTaxameter_node.html) (v1.1)\n\n## Versioning\n\nThe fiskaly SIGN DE API follows [Semantic Versioning](https://semver.org).\n\nThe version number has a pattern of `MAJOR.MINOR.PATCH`. We increment the\n\n- `MAJOR` version when we make incompatible API changes,\n- `MINOR` version when we add functionality in a backwards-compatible manner, and\n- `PATCH` version when we make backwards-compatible bug fixes.\n\nThe current `MAJOR` version `2` is reflected in the API's base URL: `/api/v2`.\n\n\n## Idempotent Requests\n\nThe fiskaly SIGN DE API is idempotent. [Idempotence](https://wikipedia.org/wiki/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. \n\nFor example, if you request to [start a transaction](#operation/upsertTransaction) but don't receive a response, you can send the request again with the same request body. Only one transaction will be started.\n\n## UUIDv4\n\nThis API uses [UUIDv4](https://datatracker.ietf.org/doc/html/rfc4122). Requests like [createTss](#operation/createTss), [createClient](#operation/createClient), and [upsertTransaction](#operation/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.\n\nA good way to generate a UUIDv4 is to use a library in your programming language of choice (like [this](https://www.npmjs.com/package/uuid)) or an online generator (like [this](https://www.uuidgenerator.net/version4)). A UUIDv4 created this way will be random and unique throughout the system.\n\nUsing 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](#operation/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. \n\n## Request IDs\n\nThe 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`.\nIf you need help with a request you have issued, please provide the request identifier. We will find your request and help you faster. \n\n## Metadata\n\nMost resources in the API (e.g. ) have a `metadata` property. You can store any additional information in the `metadata`.\n\nFor example, in the `metadata` of a [transaction](#tag/Transactions) you can store an id of a receipt or invoice from your system.\n\nYou 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.\n\n \n\n## Request body size limits\n\nThe size limit of request bodies is 1 MB. Requests above this threshold will fail with status code `413` (request too large).\n\n## Automated eviction of unused TSSs\n\nThe 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.\n\nThe preconditions for evicting a TSS are the followings:\n* the TSS has the state `CREATED`,\n* the TSS has been created at least 3 months ago,\n* no transactions have been signed by the TSS.\nSuch TSS instances will have the `EVICTED` state.\n\n# Changes\n\n## Changelog for version 2.0.0 of the API\n\n### Overview of changes\n\n- The set of operations, path parameters, JSON schemas of requests and responses have been changed since v1.\n- The TSS is fully certified (cf. [Certificate Overview](https://workspace.fiskaly.com/en/docs/certification). All certified components have been integrated in the API.\n- New URLs have been introduced. Use [https://kassensichv-middleware.fiskaly.com](https://kassensichv-middleware.fiskaly.com) for **ALL** calls to the API. Other URLs, such as [https://kassensichv-middleware.fiskaly.dev](https://kassensichv-middleware.fiskaly.dev), will soon be made **UNAVAILABLE** to customers. \n- 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](https://kassensichv-middleware.fiskaly.com) can be used for **ALL** calls to the API. You can use the URL [https://kassensichv.fiskaly.com](https://kassensichv.fiskaly.com) for operations that are not labelled with Only available via Middleware.\n- 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.\n\n### Changes in authentication\n\n- [authenticateApi](#operation/authenticateApi) hasn't been changed since v1. The `base_url` parameter from the development versions of v2 has been removed again.\n- [authenticateAdmin](#operation/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](#operation/changeAdminPin) to set an initial PIN. Admin authentication is required for\n - [updateTss](#operation/updateTss) to set the `state` of a TSS to `INITIALIZED` or `DISABLED`,\n - [createClient](#operation/createClient) and [updateClient](#operation/updateClient).\n- [logoutAdmin](#operation/logoutAdmin) has been added. Use this operation to exit the administrator mode. Run this endpoint when you are finished making administrative changes. \n- The calls to [authenticateAdmin](#operation/authenticateAdmin) and [logoutAdmin](#operation/logoutAdmin) are documented with system logs.\n\n### Changes in TSS handling\n\n- The lifecycle states of a TSS resource are `CREATED`, `UNINITIALIZED`, `INITIALIZED`, and `DISABLED`.\n- [createTss](#operation/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](#operation/createTss) endpoint. [createTss](#operation/createTss) is idempotent. If you don't receive a response, you can run the endpoint again. The calls to [createTss](#operation/createTss) are only possible if the TSS is in the state `CREATED`.\n- [updateTss](#operation/updateTss) is used to change TSS state. The following state transitions are allowed:\n - `CREATED` to `UNINITIALIZED`,\n - `UNINITIALIZED` to `INITIALIZED`,\n - `UNINITIALIZED` to `DISABLED`,\n - `INITIALIZED` to `DISABLED`.\n- 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.\n- 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.\n- 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](#operation/triggerExport) from a `DISABLED` TSS.\n- [changeAdminPin](#operation/changeAdminPin) has been added. This operation changes the PIN for [Admin Authentication](#operation/authenticateAdmin). [changeAdminPin](#operation/changeAdminPin) can be used when the TSS is `UNINITIALIZED` or `INITIALIZED`. You have to set the PIN with [changeAdminPin](#operation/changeAdminPin) before using [authenticateAdmin](#operation/authenticateAdmin) for the first time.\n- The calls to [updateTss](#operation/updateTss) and [changeAdminPin](#operation/changeAdminPin) are documented with a system log.\n\n### Changes in client handling\n\n- The lifecycle states of a client resource are `REGISTERED` and `DEREGISTERED`.\n- [createClient](#operation/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.\n- [updateClient](#operation/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.\n\n### Changes in `TEST` environment\n- **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.**\n- 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.\n- We regularly wipe the data in the `TEST` environment. The resources you created for testing can get deleted during the test runs.\n- 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`.\n\n### Log Messages\n\n- Calls to [upsertTransaction](#operation/upsertTransaction) generate transaction Logs (**as in fiskaly SIGN DE API V1**).\n- System logs are generated by the SMAERS component and may show up in [exports](#operation/triggerExport).\n- Audit logs are generated by the CSPL component and may show up in [exports](#operation/triggerExport).\n- Signing of system and audit logs increments the signature counter of a TSS just like signing of transaction Logs.\n\n## MINOR and PATCH changes\n\n### v2.2.2\n- Limit the request rate to 20 requests per minute per unique TSS identifier for [listTransactions](#operation/listTransactions), returning [`429 Too Many Requests`](#section/Errors-and-Status-Codes/Status-4xx) when the limit is reached.\n\n### v2.2.1\n- Enhanced validation for client serial numbers to prevent leading or trailing whitespace. Serial numbers must start and end with non-whitespace characters.\n\n### v2.2.0\n- 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](#operation/retrieveTss).\n\n### v2.1.35\n- OpenAPI schema description improvements.\n\n### v2.1.34\n- Improved export processing.\n\n
\nShow previous changes\n\n### v2.1.33\n- Limit the request rate to 12 requests per minute per unique export identifier for [retrieveExport](#operation/retrieveExport) and [retrieveExportFile](#operation/retrieveExportFile), returning [`429 Too Many Requests`](#section/Errors-and-Status-Codes/Status-4xx) when the limit is reached.\n\n### v2.1.32\n- [listClientTransactions](#operation/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.\n\n### v2.1.31\n- Added `Retry-After` header to [`E_EXPORT_NOT_COMPLETED`](#section/Errors-and-Status-Codes/Status-4xx), [`429 Too Many Requests`](#section/Errors-and-Status-Codes/Status-4xx) and [`503 Service Unavailable`](#section/Errors-and-Status-Codes/Status-5xx) responses to indicate the number of seconds to wait before retrying.\n\n### v2.1.30\n- Limit on the number of exports in `PENDING` or `WORKING` state per TSS has been set to `10` in the [triggerExport](#operation/triggerExport) endpoint.\n\n### v2.1.29\n- Added a limit in the [triggerExport](#operation/triggerExport) endpoint for the maximum number of exports in `PENDING` or `WORKING` state per TSS. \nIf the limit is reached, you can't trigger a new export until some exports are processed.\n\n### v2.1.28\n- Updating third-party dependencies.\n\n### v2.1.27\n- Updated documentation of [createClient](#operation/createClient) endpoint to clarify uniqueness requirements of the client `serial_number`.\n\n### v2.1.26\n- Deprecated the [retrieveTransactionLog](#operation/retrieveTransactionLog) endpoint.\n\n### v2.1.25\n- Added the `E_LOG_NOT_FOUND` error which indicates that a log for a given transaction was not found.\n\n### v2.1.24\n- Added the `E_TSS_LOCKED` error which indicates the temporary unavailability of a TSS resource.\n\n### v2.1.23\n- Added E_EXPORT_PROCESSING_TIMEOUT to ExportException in the retrieve export endpoint for cases where an export takes too long to process (default: 24h).\n\n### v2.1.22\n- Enabled metadata updates through [updateTssMiddleware](#operation/updateTss) while preserving the current state.\n- Ensured metadata is combined and persisted on [updateClientMiddleware](#operation/updateClient).\n- Ensured metadata is combined and persisted on [upsertTransactionMiddleware](#operation/upsertTransaction).\n- Support for up to 40 metadata key-value pairs.\n\n### v2.1.21\n- Updating third-party dependencies.\n\n### v2.1.20\n- Removed field `bsi_certification_valid_to` on the responses of the TSS endpoints [updateTss](#operation/updateTss), [retrieveTss](#operation/retrieveTss), and [listTss](#operation/listTss) for TSS instances in the `UNINITIALIZED`, `INITIALIZED`, and `DISABLED` states.\n\n### v2.1.19\n- Underlying export storage mechanism has been changed.\n\n### v2.1.18\n- 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. \n\n### v2.1.17\n- Validation added for query parameters `limit` (minimum value is 1) and `offset` (minimum value is 0)\n\n### v2.1.16\n- Changed DSFinV-TW version to 1.1 in documentation, no API changes necessary from 1.0 before.\n\n### v2.1.15\n- The OpenAPI change from 2.1.24 was reverted because of breaking some customer implementations.\n\n### v2.1.14\n- The OpenAPI request specification of [triggerExport](#operation/triggerExport) was corrected to require an empty body structure. This change only effects the OpenAPI specification, the implemented behavior was not changed.\n\n### v2.1.13\n- Introduce a limitation for [createTss](#operation/createTss) up to 500 instances per pay\n- [createTss](#operation/createTss) has a new error response `403 Limit of 500 created TSS's per day reached`.\n\n### v2.1.12\n- The schema `dsfinvtw_v1` in the operation [upsertTransaction](#operation/upsertTransaction) is allowed within both `TEST` and `LIVE` environments\n\n### v2.1.11\n- 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`.\n\n### v2.1.10\n- Updated [upsertTransaction](#operation/upsertTransaction) to return 400 Bad request instead of 404 Not found when client not found\n- Minor refactoring\n\n### v2.1.9\n- Correction of response status `401` instead of `400` in the case of an invalid refresh token in the operation [authenticateApi](#operation/authenticateApi)\n\n### v2.1.8\n- General performance improvement\n\n### v2.1.7\n- Documentation change regarding status code `499` errors \n\n### v2.1.6\n- Added fields `bsi_certification_id` and `bsi_certification_valid_to` to the responses of the TSS endpoints [updateTss](#operation/updateTss), [retrieveTss](#operation/retrieveTss), and [listTss](#operation/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.\n\n### v2.1.5\n- Optimization of the operations [listTss](#operation/listTss), [listAllClients](#operation/listAllClients), [listAllExports](#operation/listAllExports)\n\n### v2.1.4\n- Optimization of the operations [listTransaction](#operation/listTransactions) and [listAllTransactions](#operation/listAllTransactions)\n\n### v2.1.3\n- Prohibit update of the transactions with `dsfinvtw_v1` schema in the operation [upsertTransaction](#operation/upsertTransaction)\n\n### v2.1.2\n- 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\n\n### v2.1.1\n- Fixed empty `dsfinvtw_v1.driver_status` in the response of the operation [upsertTransaction](#operation/upsertTransaction)\n\n### v2.1.0\n- New schema `dsfinvtw_v1` has been added to the operation [upsertTransaction](#operation/upsertTransaction). This schema covers [DSFinV-TW](https://www.bzst.de/DE/Unternehmen/Aussenpruefungen/DigitaleSchnittstelleTaxameter/digitaleSchnittstelleTaxameter_node.html). This feature is currently only available within the `TEST` environment\n\n### v2.0.53\n- Fixed empty field `schema.raw` in the response of the operation [upsertTransaction](#operation/upsertTransaction) in the scenario where `schema.raw` is not empty in the input when the transaction starts\n\n### v2.0.52\n- Optimized export processing\n\n### v2.0.51\n- Optimized export processing\n\n### v2.0.50\n- Updated API query string parsing to ignore leading question marks in malformed queries\n\n### v2.0.49\n- Postman collection is updated ([Quick Start](#section/Quick-Start))\n\n### v2.0.48\n- Additional validation in [triggerExport](#operation/triggerExport)\n- Set default and maximal value for `maximum_number_records` in [triggerExport](#operation/triggerExport)\n\n### v2.0.47\n- Autogenerate OpenAPI 3.0.3-compliant API specifications\n\n### v2.0.46\n- Changes in export processing\n\n### v2.0.45\n- Security updates\n\n### v2.0.44\n- Updating third-party dependencies\n\n### v2.0.43\n- Request id generation improvements\n- Export improvements\n\n### v2.0.42\n- Validation improvements in [upsertTransaction](#operation/upsertTransaction) and [createClient](#operation/createClient)\n\n### v2.0.41\n- Export optimizations\n\n### v2.0.40\n- Updating third-party dependencies\n\n### v2.0.39\n- Performance optimisations\n\n### v2.0.38\n- Database performance optimisations\n\n### v2.0.37\n- Database performance optimisations\n\n### v2.0.36\n- Refinements in wiping mechanism\n\n### v2.0.34\n- Added information about dealing with `DEFECTIVE` state of TSS: [Defective TSS](#section/Errors-and-Status-Codes/Defective-TSS)\n\n### v2.0.33\n- Ensure idempotence of the operation [createClient](#operation/createClient)\n\n### v2.0.32\n- Validation added for maximum length of client serial number (70 characters) to conform with DSFinV-K\n- The documentation of the operation [createClient](#operation/createClient) is adapted accordingly\n\n### v2.0.31\n- Export improvements\n\n### v2.0.30\n- 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\n\n### v2.0.29\n- Updating third-party dependencies\n- Stability improvements in request timeout handling\n- Improvements to standardV1 schema transformation\n\n### v2.0.28\n- Added recommendation regarding the length of the serial number of the client in [createClient](#operation/createClient)\n\n### v2.0.27\n- Refinements in wiping mechanism\n\n### v2.0.23\n- Changes in wiping mechanism\n\n### v2.0.22\n- Updating third-party dependencies\n\n### v2.0.20\n- Minor documentation improvements\n\n### v2.0.18\n- Fix problems with big exports\n- Improve performance of log synchronization\n\n### v2.0.17\n- Logging improvements\n\n### v2.0.16\n- Export improvements\n- Documentation improvements\n\n### v2.0.15\n- Log synchronization improvements\n\n### v2.0.14\n- Updating some third-party dependencies\n\n### v2.0.13\n - Performance improvements\n\n### v2.0.12\nThe changes in the [DSFinV-K v2.3](https://www.bzst.de/DE/Unternehmen/Aussenpruefungen/DigitaleSchnittstelleFinV/digitaleschnittstellefinv_node.html#js-toc-entry2) are taken into account:\n- Adapted documentation of the field `quantity` of [upsertTransaction](#operation/upsertTransaction) operation.\n- Adapted documentation of the field `order` of [upsertTransaction](#operation/upsertTransaction) operation.\n- Adapted documentation of the [createClient](#operation/createClient) operation.\n- Adapted documentation of the field `serial_number` of the [createClient](#operation/createClient) operation.\n\n### v2.0.11\n- Updating some third-party dependencies.\n\n### v2.0.10\n- Adapted documentation of [triggerExport](#operation/triggerExport) operation.\n- Adapted documentation of `amount` of [upsertTransaction](#operation/upsertTransaction) operation.\n- Prevent changing the `state` of the [exports](#operation/retrieveExport) from `CANCELLED` to `COMPLETED`.\n- Prevent changing the `state` of the [tss](#operation/retrieveTss) if TSS is `DEFECTIVE`.\n- Make the field `exception` of the [exports](#operation/retrieveExport) more informative.\n\n### v2.0.9\n- Added new filtration parameters `start_signature_counter` and `end_signature_counter` in the [triggerExport](#operation/triggerExport) operations.\n\n### v2.0.8\n- Added new filtration parameter `show_deleted` in the [listTss](#operation/listTss), [listAllClients](#operation/listAllClients), [listAllExports](#operation/listAllExports) operations.\n\n### v2.0.7\n- Added a new field to the TSS response: `time_defective`. It shows the time at which the TSS went into state `DEFECTIVE`.\n- Documented the `403 Forbidden` error response. It can be thrown if the `organization` is not provided or not authorized for the operation.\n\n### v2.0.6\n* 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.\n\n### v2.0.5\n* 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.\n\n### v2.0.4\n\n- All received UUIDs are automatically converted to lower case.\n\n### v2.0.3\n\n- [updateTss](#operation/updateTss), [createClient](#operation/createClient), [updateClient](#operation/updateClient), [upsertTransaction](#operation/upsertTransaction) now resolve consistently if not invoked on a TSS sequentially .\n\n### v2.0.2\n\n- [createTss](#operation/createTss) has a new error response `423 TSS creation locked`. This error is returned transparently instead of `500 Internal server error`.\n- `401 Unauthorized` is returned transparently instead of `502 Bad Gateway (Log Shipping failed)` in case of an expired access token.\n\n### v2.0.1\n\n- Metadata in [updateTss](#operation/updateTss) were not stored persistently. New metadata now get combined with existing metadata of the TSS and then stored persistently.\n\n
\n\n# Resources\n\n## TSS\n\nThe technical security system (TSS) resource represents the set of components that sign transactions. Each TSS is assigned an instance of [SMAERS](#section/Introduction/Components). A TSS can have a number of clients, transactions and exports associated with it.\n\nThe TSS changes its state as it moves through its lifecycle. The [changelog](#section/Changes) describes how to perform TSS state change.\n\n## Client\n\nThe 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.\n\nA client has its own state lifecycle. See [changelog](#section/Changes) for info on how to manage the client state change.\n\n## Transaction\n\nThe transaction resource represents a transaction that needs to be signed. A transaction is associated with a TSS and a client that initiates the transaction.\n\nThe lifecycle states of a transaction resource are `ACTIVE`, `FINISHED`, and `CANCELLED`.\nAt the start of a transaction, the state must be set to `ACTIVE`. The state stays `ACTIVE` until the transaction is finished or cancelled.\nThe `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.\n\n**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.\n\n## Export\n\nThe export resource holds the state of the asynchronous generation of the export TAR file.\nThe export TAR file contains the SMAERS initialization information, the signed log messages, and the certificates to verify them.\nA created export file is available until the time specified by the \\`time_expiration\\` attribute. After the \\`time_expiration\\` the export file is deleted permanently.\n\n# Errors and Status Codes\n\nNOTE: DON'T BLOCK THE TILL\n\nThere 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! \nPlease make sure that your integration is not blocking the checkout process.\n\nIf the API malfunctions or is unreachable, the tills should still be able to work, while noting the outage on the receipt.\nPlease note the relevant information in the corresponding [AO-Anwendungerlass](https://ao.bundesfinanzministerium.de/ao/2020/Abgabenordnung/Vierter-Teil/Zweiter-Abschnitt/Erster-Unterabschnitt/Paragraf-146a/ae-146a.html) from the German Federal Ministry of Finance. \n

\n\n## Defective TSS\nAs 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.\n\nIn this case the TSS should be replaced by the customer, by using the operation [createTss](#operation/createTss) to create a new TSS.\nExisting clients must be linked to the new TSS, each with a new `client_id` via endpoint [createClient](#operation/createClient).\n\nThe following operations are impossible if TSS is `DEFECTIVE`: \n - [authenticateAdmin](#operation/authenticateAdmin)\n - [logoutAdmin](#operation/logoutAdmin)\n - [updateTss](#operation/updateTss)\n - [changeAdminPin](#operation/changeAdminPin)\n - [createClient](#operation/createClient)\n - [updateClient](#operation/updateClient)\n - [upsertTransaction](#operation/upsertTransaction)\n\nThe rest of the operations are still functioning. Triggering ([triggerExport](#operation/triggerExport)) \nand downloading ([retrieveExportFile](#operation/retrieveExportFile)) exports (TAR file) is still possible.\n\nThe fiskaly SIGN DE API uses standard [HTTP status codes](https://http.cat/) to indicate the success or failure of requests:\n\n## Status 2xx\n\nStatus codes in the `200-299` range indicate success.\n\n## Status 4xx\n\nStatus 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). \n Retrying such requests with the same request body is pointless and _will_ result in the same status code again.\nStatus code `413` indicates that the request body was too large. Currently the size limit for requests bodies is 1 MB.\nSome `4xx` errors can be handled programmatically. The error response is in JSON format and is structured like this:\n\n```\n{\n\"status_code\": 400,\n\"error\": \"Bad Request\",\n\"code\": \"E_SOME_ERROR\",\n\"message\": \"Something bad happened\"\n}\n```\n\nThe 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.\n\nA 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.\nWe recommend an [exponential backoff](https://wikipedia.org/wiki/Exponential_backoff) in your retry logic.\nOtherwise you might risk running into a [`429 (Too Many Requests)`](https://http.cat/429) error. In case of a `429`, the `Retry-After` header is included, indicating the number of seconds to wait before retrying.\n\n### General errors\n\n
\n \n 400 Bad Request\n \n\n-
\n \n \n E_TX_REVISION_NOT_FOUND\n \n \n\n No `tx_revision` could be found for the `tx_revision` from your request query. Run the [Retrieve transaction](/api/v2/_docs/#operation/retrieveTransaction) endpoint without query parameters. Check the `latest_revision` field of the response to see the largest available `tx_revision` number.\n
\n\n-
\n \n \n E_TSS_NOT_INITIALIZED\n \n \n\n The TSS you are trying to access is not initialized. Run the [Retrieve TSS](/api/v2/_docs/#operation/retrieveTss) 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](/api/v2/_docs/#operation/updateTss) endpoint. If the `state` is `\"CREATED\"`, run the [Update TSS](/api/v2/_docs/#operation/updateTss) endpoint with `\"UNINITIALIZED\"` in the `state` field. Then initialize the TSS as described above. After that send your original request again.\n
\n\n-
\n \n \n E_TSS_DISABLED\n \n \n\n 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](/api/v2/_docs/#operation/createTss) endpoint. Then follow the usual workflow initializing the TSS and creating a new `client`.\n
\n\n-
\n \n \n E_ILLEGAL_TSS_STATE_CHANGE\n \n \n\n 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](/api/v2/_docs/#operation/updateTss) 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](/api/v2/_docs/#operation/updateTss) endpoint. To disable the TSS, run the same [route](/api/v2/_docs/#operation/updateTss) with `\"DISABLED\"` in the `state` field. Disabling the TSS requires its state to be either `\"UNINITIALIZED\"` or `\"INITIALIZED\"`.\n
\n\n-
\n \n \n E_ILLEGAL_CLIENT_SERIAL\n \n \n\n 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](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR03153/TR-03153-TS.pdf?__blob=publicationFile). 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.\n
\n\n-
\n \n \n E_CLIENT_DEREGISTERED\n \n \n\n 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](/api/v2/_docs/#operation/updateClient) endpoint. Then send your original request again.\n
\n\n-
\n \n \n E_TX_LIMIT_REACHED \n \n \n\n 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](#operation/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.\n\n-
\n \n \n E_DUPLICATE_EXPORT\n \n \n\n This `export` has already been triggered. Run the [Retrieve export](/api/v2/_docs/#operation/retrieveExport) endpoint and wait until the `export` is finished. Depending on the size, the `export` can take up to one hour to finish.\n
\n\n-
\n \n \n E_CANCEL_EXPORT\n \n \n\n 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](/api/v2/_docs/#operation/retrieveExport) endpoint. The `state` field of the response body will show the exact `state` of the `export`.\n
\n\n-
\n \n \n E_PARAMETER_MISMATCH\n \n \n\n You cannot trigger an `export` with this set of query parameters. Change your query parameters as the error message suggests. Then rerun your request.\n
\n\n-
\n \n \n E_CHANGE_ADMIN_PIN_FAILED\n \n \n\n The `admin_puk` you provided is not correct. Check the `admin_puk` you transmitting in the request and run the endpoint again.\n
\n\n-
\n \n \n E_FAILED_SCHEMA_VALIDATION\n \n \n\n The request failed to validate against the required OpenAPI schema. The details are described in the `message` property of the error.\n
\n\n
\n\n\n
\n \n 401 Unauthorized \n \n\n-
\n \n \n E_UNAUTHORIZED \n \n \n\n +
\n \n \n Authenticate API\n \n \n\n 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.\n
\n\n +
\n \n \n Authenticate Admin\n \n \n\n 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](/api/v2/_docs/#operation/changeAdminPin) request with your `admin_puk` and `new_admin_pin`.\n
\n
\n
\n\n
\n \n 403 Forbidden \n \n\n-
\n \n \n E_TSS_LIMIT_REACHED \n \n \n\n 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](/api/v2/_docs/#operation/updateTss) endpoint. Then retry the [Create TSS](/api/v2/_docs/#operation/createTss) request.\n
\n\n-
\n \n \n E_TSS_LIMIT_PER_DAY_REACHED \n \n \n\n You have reached the limit for TSS creation per day.\n
\n\n-
\n \n \n E_CLIENT_LIMIT_REACHED\n \n \n\n 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](/api/v2/_docs/#operation/updateClient) endpoint. To create a new TSS, run the [Create TSS](/api/v2/_docs/#operation/createTss) request with a new `tss_id`.\n
\n\n-
\n \n \n E_ACCESS_DENIED \n \n \n\n 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](/api/v2/_docs/#operation/authenticateApi) endpoint. Make sure that `organization_id` is present in the `access_token_claims` field of the response body.\n
\n
\n\n
\n \n 404 Resource does not exist\n \n\n-
\n \n \n E_TSS_NOT_FOUND\n \n \n\n No TSS with the `tss_id` from your request has been found. Send a request to the [Retrieve TSS](/api/v2/_docs/#operation/retrieveTss) endpoint with the `tss_id` check that the TSS exists.\n
\n\n-
\n \n \n E_CLIENT_NOT_FOUND\n \n \n\n No `client` could be found for the `client_id` and `tss_id` from your request. Check that the TSS exists with the [Retrieve TSS](/api/v2/_docs/#operation/retrieveTss) endpoint. Check that the `client` exists on the TSS with the [Retrieve client](/api/v2/_docs/#operation/retrieveClient) endpoint.\n
\n\n-
\n \n \n E_TX_NOT_FOUND\n \n \n\n 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](/api/v2/_docs/#operation/retrieveTss) endpoint. Check that the `transaction` exists on the TSS with the [Retrieve transaction](/api/v2/_docs/#operation/retrieveTransaction) endpoint.\n
\n\n-
\n \n \n E_EXPORT_NOT_FOUND\n \n \n\n No `export` could be found for the `tss_id` and `export_id` from your request. Check that the TSS exists with the [Retrieve TSS](/api/v2/_docs/#operation/retrieveTss) endpoint. Check that the `export` exists on the TSS with the [Retrieve export](/api/v2/_docs/#operation/retrieveExport) endpoint.\n
\n-
\n \n \n E_EXPORT_NOT_COMPLETED \n \n \n\n Export is not in the state `COMPLETED`. Run the [Retrieve export](/api/v2/_docs/#operation/retrieveExport) 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.\n
\n\n-
\n \n \n E_LATEST_TX_REVISION_NOT_FOUND\n \n \n\n The latest `tx_revision` could not be found.\n
\n\n
\n\n
\n \n 409 Conflict \n \n\n-
\n \n \n E_TSS_CONFLICT \n \n \n\n A TSS with the specified `tss_id` already exists. Generate another `tss_id` and retry the request with it.\n
\n\n-
\n \n \n E_CLIENT_CONFLICT \n \n \n\n A `client` with the specified `client_id` already exists in the system. Generate another `client_id` and retry the request.\n
\n\n-
\n \n \n E_TX_ILLEGAL_TYPE_CHANGE \n \n \n\n The `process_type` from your request body is different from the `_type` in the `transaction`. Retrieve the `transaction` with the [Retrieve transaction](/api/v2/_docs/#operation/retrieveTransaction) route and see the `_type` field of the response body. Make sure that it matches the `process_type` from your original request.\n
\n\n-
\n \n \n E_TX_NO_TYPE_DEFINED \n \n \n\n The `process_type` is missing from your request body. Retrieve the `transaction` with the [Retrieve transaction](/api/v2/_docs/#operation/retrieveTransaction) 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.\n
\n\n-
\n \n \n E_TSS_ILLEGAL_STATE_TO_PERFORM_EXPORT \n \n \n\n Exports can only be performed when the TSS is in the state of `\"INITIALIZED\"` or `\"DISABLED\"`. Run the [Retrieve TSS](/api/v2/_docs/#operation/retrieveTss) endpoint and check the `state` field of your TSS. If the `state` is `\"CREATED\"`, run the [Update TSS](/api/v2/_docs/#operation/updateTss) endpoint with the `state` field set to `\"UNINITIALIZED\"`. Then run this [Update TSS](/api/v2/_docs/#operation/updateTss) endpoint with the `state` field set to `\"INITIALIZED\"`.

\n If the `state` of the TSS is `\"UNINITIALIZED\"`, run the [Update TSS](/api/v2/_docs/#operation/updateTss) request with `\"INITIALIZED\"` in the `state` field.

\n 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](/api/v2/_docs/#operation/updateTss) 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.\n
\n\n-
\n \n \n E_PENDING_TX_CONFLICT \n \n \n\n 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](https://datatracker.ietf.org/doc/html/rfc4122) standards.\n
\n\n-
\n \n \n E_EXPORT_DUPLICATE_RATE_LIMITED\n \n \n\n 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.\n
\n\n-
\n \n \n E_TOO_MANY_EXPORTS\n \n \n\n 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.\n
\n\n-
\n \n \n E_EXPORT_IN_PROGRESS \n \n \n\n The operation cannot be performed due to a running export. Trigger exports after business hours (when there are no or few transactions going on).\n
\n
\n\n\n
\n \n 423 Locked \n \n\n-
\n \n \n E_ADMIN_PIN_BLOCKED \n \n \n \n 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](/api/v2/_docs/#operation/changeAdminPin) request with your `admin_puk` and `new_admin_pin`.\n
\n\n-
\n \n \n E_TSS_DEFECTIVE \n \n \n\n 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.\n
\n-
\n \n \n E_TSS_DELETED\n \n \n\n This TSS is in the state `DELETED` and cannot be used for the current operation.\n
\n-
\n \n \n E_TSS_EVICTED\n \n \n\n This TSS is in the state `EVICTED` and cannot be used for the current operation.\n
\n-
\n \n \n E_AVAILABLE_ON_TEST_ONLY\n \n \n\n Experimental feature - Only available for `TEST` API Keys.\n
\n
\n\n
\n \n 429 Too Many Requests\n \n\n This error indicates that you have sent too many requests in a short period of time.\n 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.\n
\n\n
\n \n 432 Use Middleware \n \n\n-
\n \n \n E_USE_MIDDLEWARE \n \n \n\n This operation requires you to use the fiskaly sign Middleware. The Middleware is available through this URL [https://kassensichv-middleware.fiskaly.com](https://kassensichv-middleware.fiskaly.com). For more information about the use of the Middleware see the [Changelog for version 2.0.0 of the API](#section/Changes).\n\n
\n
\n\n## Status 5xx\n\nStatus codes in the `500-599` range indicate errors on the server side.\nThese errors can be considered temporary.\nThis means that you may **safely retry** (see [Idempotent Requests](#section/Introduction/Idempotent-Requests)) the same request after a certain delay. We recommend an [exponential backoff](https://wikipedia.org/wiki/Exponential_backoff) in your retry logic.\nOtherwise you might risk running into a [`429 (Too Many Requests)`](https://http.cat/429) 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.\n\n
\n \n 502 Bad Gateway \n \n\n-
\n \n \n SMAERS_GATEWAY_ERROR_PRECONDITION_UNEXPORTED_LOGS \n \n \n\n 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.\n
\n\n-
\n \n \n ERROR_IDENTIFY_ERS \n \n \n\n 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.\n
\n\n
\n\n
\n \n 503 Service Unavailable\n \n\n-
\n \n \n E_TSS_LOCKED \n \n \n\n 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.\n
\n\n
\n\n# Known issues\n- If you're experiencing any problems with the fiskaly SIGN DE API, please check [the fiskaly SIGN DE API status page](https://status.fiskaly.com) or forward to [Developer Support](mailto:dev-support@fiskaly.com).\n- 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`.\n- 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.\n\n# How to raise an Issue\n\nAt 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.\nWe're living a transparent operation process, and will inform about known operation problems via [status.fiskaly.com](https://status.fiskaly.com/). Before raising a new issue, please check there first.\n\nPlease read the article [How to raise an issue](https://workspace.fiskaly.com/en/docs/guides/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.\n\n# Quick Start\n\n \n\nFor a quick first demo, you may use [Postman](https://www.getpostman.com/). We prepared a [Postman collection](https://www.getpostman.com/collection) that allows you to step through the most important functions of this API.\n\n1. Download the [Postman](https://www.getpostman.com/downloads/) application.\n\n2. Create an API key and secret via the [fiskaly dashboard](https://dashboard.fiskaly.com):\n [![api key and secret](https://kassensichv.fiskaly.com/api/v2/_postman/assets/apikey-small.png)](https://kassensichv.fiskaly.com/api/v2/_postman/assets/apikey.png)\n\n3. Insert your API key and secret to get your personalized Postman environment:\n\n
\n \n \n \n
\n\n4. Download the [Postman collection](https://kassensichv.fiskaly.com/api/v2/_postman/collection).\n\n5. Start Postman and select Upload Files from the Import dialog:\n\n `File > Import (Ctrl+O)`\n\n [![postman upload files](https://kassensichv.fiskaly.com/api/v2/_postman/assets/postman-0-small.png)](https://kassensichv.fiskaly.com/api/v2/_postman/assets/postman-0.png)\n\n6. Select the collection and environment files that you downloaded:\n\n [![postman select files](https://kassensichv.fiskaly.com/api/v2/_postman/assets/postman-1-small.png)](https://kassensichv.fiskaly.com/api/v2/_postman/assets/postman-1.png)\n\n7. The Postman screen should now look like this:\n\n [![postman screen](https://kassensichv.fiskaly.com/api/v2/_postman/assets/postman-2-small.png)](https://kassensichv.fiskaly.com/api/v2/_postman/assets/postman-2.png)\n\n8. Select the Sign API v2 environment:\n\n [![postman select environment](https://kassensichv.fiskaly.com/api/v2/_postman/assets/postman-3-small.png)](https://kassensichv.fiskaly.com/api/v2/_postman/assets/postman-3.png)\n\n9. Run the demo:\n\n [![postman run demo](https://kassensichv.fiskaly.com/api/v2/_postman/assets/postman-4-small.png)](https://kassensichv.fiskaly.com/api/v2/_postman/assets/postman-4.png)\n\n", "version": "2.2.2", "contact": { "name": "fiskaly GmbH", "url": "https://fiskaly.com", "email": "info@fiskaly.com" }, "x-logo": { "url": "https://www.fiskaly.com/fiskaly_logo.svg", "altText": "fiskaly" } }, "components": { "securitySchemes": { "JWT": { "description": "A JSON Web Token (JWT) used for access control and authorization.\nAPI keys have to be obtained via the [fiskaly dashboard](/).\n- Usage format: `Bearer `\n- Example HTTP header: `Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`", "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "BigintCounter": { "type": "string", "format": "bigint" }, "Byte": { "type": "string", "format": "byte" }, "Uuid": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "TssStatesQuery": { "type": "array", "description": "Filter to include only specific states of TSS \n\nExample: `states%5B0%5D=DISABLED&states%5B1%5D=INITIALIZED`", "items": { "type": "string", "enum": [ "CREATED", "UNINITIALIZED", "INITIALIZED", "DISABLED", "DELETED", "DEFECTIVE", "EVICTED" ], "uniqueItems": true } }, "Timestamp": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "A timestamp / point in time measured in seconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time)", "example": 1577833200 }, "Counter": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "Env": { "type": "string", "enum": ["TEST", "LIVE"], "example": "TEST" }, "TssSerialNumber": { "type": "string", "description": "The serial number of the TSS." }, "TssPublicKey": { "type": "string", "description": "The public key of the TSS, base64-encoded value." }, "TssCertificate": { "type": "string", "description": "The TSS certificate, base64-encoded." }, "SignatureValue": { "type": "string", "description": "Signature, base64-encoded value." }, "Metadata": { "type": "object", "example": { "my_property_1": "1234", "my_property_2": "https://my-internal-system/path/to/resource/1234" }, "maxProperties": 40, "additionalProperties": { "type": "string", "maxLength": 500 } }, "OrganizationId": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000", "description": "ID of the Organization" }, "MetadataRequest": { "type": "object", "example": { "my_property_1": "1234", "my_property_2": "https://my-internal-system/path/to/resource/1234" }, "maxProperties": 40, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "You can use this parameter to attach custom key-value data to an object.\nMetadata is useful for storing additional, structured information on an object.\n*Note:* You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long." }, "MetadataResponse": { "type": "object", "example": { "my_property_1": "1234", "my_property_2": "https://my-internal-system/path/to/resource/1234" }, "maxProperties": 40, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Returns metadata" }, "Count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of available data items" }, "RefreshToken": { "type": "string" }, "ApiKeyKey": { "type": "string", "description": "Key of an API Key" }, "ApiKeySecret": { "type": "string", "description": "Secret of an API Key" }, "TimestampFormat": { "type": "string", "description": "The format of the timestamp of the signed transactions.", "enum": ["unixTime"], "example": "unixTime" }, "Environment": { "type": "string", "enum": ["TEST", "LIVE"], "example": "TEST" }, "SupportedUpdateVariants": { "type": "string", "enum": ["SIGNED"], "example": "SIGNED" }, "Version": { "type": "string", "example": "2.2.2", "description": "fiskaly SIGN DE API version number" }, "Algorithm": { "type": "string", "description": "Type of Algorithm used to sign transactions.", "enum": ["ecdsa-plain-SHA256"], "example": "ecdsa-plain-SHA256" }, "TssId": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000", "description": "Identifies a TSS" }, "ClientId": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000", "description": "Identifies a client by a self-generated [UUIDv4](https://datatracker.ietf.org/doc/html/rfc4122)" }, "ExportId": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000", "description": "Identifies an Export" }, "Url": { "type": "string", "format": "uri" }, "BaseUrl": { "type": "string", "format": "uri", "description": "URL of the fiskaly Backend (a suitable default value is used if not set)" }, "GatewayName": { "type": "string", "description": "The name of the gateway", "pattern": "gw\\d+-(live|test)$", "example": "gw125-live" }, "TssDescription": { "type": "string", "description": "Description of TSS", "pattern": "^[A-Za-z0-9 '()+,-./:=?]{0,100}$", "example": "fiskaly sign cloud-TSE (tss_id)" }, "CauseOfDefect": { "type": "string", "description": "The cause of the defective state of the TSS" }, "RefreshTokenAuthentication": { "type": "object", "properties": { "refresh_token": { "$ref": "#/components/schemas/RefreshToken" } }, "required": ["refresh_token"] }, "ApiKeyAuthentication": { "type": "object", "properties": { "api_key": { "$ref": "#/components/schemas/ApiKeyKey" }, "api_secret": { "$ref": "#/components/schemas/ApiKeySecret" } }, "required": ["api_key", "api_secret"] }, "SmaersUrl": { "type": "string", "format": "uri", "description": "URL of the target SMAERS", "example": "https://smaers.fiskaly.com" }, "CsplUrl": { "type": "string", "format": "uri", "description": "URL of the target CSPL", "example": "https://cspl.fiskaly.com" }, "AdminPin": { "type": "string", "description": "Represents the PIN for the authentication. (TR-03151)", "minLength": 6, "example": "AB1234" }, "AdminPuk": { "type": "string", "description": "Represents the PUK of the user/application. (TR-03151)", "minLength": 10, "example": "ABCD123456" }, "ClientSerialNumber": { "type": "string", "pattern": "^(?!\\s)[A-Za-z0-9 '()+,-./:=?]{0,70}(? 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." }, "ClientState": { "type": "string", "enum": ["REGISTERED", "DEREGISTERED"], "description": "Defines the state of a Client in the TSS. Only registered clients are able to write transactions.", "example": "REGISTERED" }, "TssState": { "description": "Defines the state of a TSS.", "type": "string", "enum": [ "CREATED", "UNINITIALIZED", "INITIALIZED", "DISABLED", "DELETED", "DEFECTIVE", "EVICTED" ], "example": "INITIALIZED" }, "TxRevisionRetrieval": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "default": 1 }, "TxState": { "type": "string", "enum": ["ACTIVE", "CANCELLED", "FINISHED"], "default": "ACTIVE" }, "TxOperation": { "type": "string", "enum": ["Start", "Update", "Finish"] }, "TxNum": { "type": "integer", "maximum": 9007199254740991 }, "TxLog": { "type": "object", "properties": { "operation": { "type": "string", "enum": ["Start", "Update", "Finish"] }, "timestamp": { "$ref": "#/components/schemas/Timestamp" }, "timestamp_format": { "$ref": "#/components/schemas/TimestampFormat" } }, "required": ["operation", "timestamp", "timestamp_format"] }, "TxSignature": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/Byte" }, "algorithm": { "$ref": "#/components/schemas/Algorithm" }, "counter": { "$ref": "#/components/schemas/Counter" }, "public_key": { "type": "string" } }, "required": ["value", "algorithm", "counter", "public_key"] }, "TxId": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000", "description": "Identifies a transaction by a self-generated [UUIDv4](https://datatracker.ietf.org/doc/html/rfc4122)" }, "TxIdOrNumber": { "description": "Identifies a transaction by a `tx_id` (i.e. a self-generated [UUIDv4](https://datatracker.ietf.org/doc/html/rfc4122)) or a `tx_number` that gets assigned by us", "anyOf": [ { "$ref": "#/components/schemas/TxId" }, { "$ref": "#/components/schemas/TxNum" } ] }, "DSFinVKNumeric": { "type": "string", "pattern": "^-?\\d+(\\.\\d{2,5})$" }, "DSFinVTWNumeric": { "type": "string", "pattern": "^-?\\d{1,16}\\.\\d{2}$", "description": "encoded as quoted decimal with 2 decimal places", "example": "20.25" }, "DSFinVTWKilometerReading": { "type": "string", "description": "Kilometer reading encoded as quoted decimal with 3 decimal places", "pattern": "^\\d{1,16}\\.\\d{3}$" }, "DSFinVTWDistanceTraveled": { "type": "string", "description": "Distance traveled encoded as quoted decimal with 3 decimal places", "pattern": "^\\d{1,16}\\.\\d{3}$" }, "DSFinVTWMeterType": { "type": "string", "description": "Determines the meter type being used to track trips.\n\nCorresponds to `\"TW_PRAEFIX\"`.\n\n```\nTAXIMETER = T\nODOMETER = W\n```", "enum": ["TAXIMETER", "ODOMETER"] }, "DSFinVTWVehicleId": { "type": "string", "description": "Vehicle Identification
Corresponds to `\"ORDN_NR\"`", "pattern": "^[^_\\/^]+$", "maxLength": 20 }, "DSFinVTWTariffId": { "type": "string", "description": "Tariff Identification
Corresponds to `\"TW_TARIF\"`", "pattern": "^[^_\\/^]+$", "maxLength": 50, "default": "0" }, "DSFinVTWPassengerTransfers": { "type": "string", "description": "Number of passenger transfers carried out", "pattern": "^\\d{1,20}$" }, "DSFinVTWConstant": { "type": "string", "description": "Constant of the distance signal transmitter\n\nCorresponds to `\"TW_KONSTANTE\"`", "pattern": "^\\d{1,10}$" }, "DSFinVTWTotalSurchargeOrBaseAmount": { "type": "string", "pattern": "^-?\\d{1,16}\\.\\d{2}$", "description": "Total amount of billed surcharges (for taximeters) or base price (for odometers)", "example": "20.25" }, "DSFinVTWTotalBilledFareAmount": { "type": "string", "pattern": "^-?\\d{1,16}\\.\\d{2}$", "description": "Total amount billed as fare", "example": "20.25" }, "DSFinVTWDriverId": { "type": "string", "description": "Identification of the driver\n\nCorresponds to `\"TW_FAHRER\"`", "pattern": "^[^_\\/^]+$", "maxLength": 40 }, "DSFinVTWPriceData": { "type": "object", "description": "Price data of a trip", "properties": { "trip_start": { "$ref": "#/components/schemas/Timestamp" }, "trip_end": { "$ref": "#/components/schemas/Timestamp" }, "distance_traveled": { "$ref": "#/components/schemas/DSFinVTWDistanceTraveled" }, "fare": { "type": "string", "pattern": "^-?\\d{1,16}\\.\\d{2}$", "description": "Corresponds to `\"TW_FAHRPREIS\"`", "example": "20.25" }, "surcharge": { "type": "string", "pattern": "^-?\\d{1,16}\\.\\d{2}$", "description": "Corresponds to `\"TW_ZUSCHLAG\"`", "example": "20.25" }, "total_billed": { "type": "string", "pattern": "^-?\\d{1,16}\\.\\d{2}$", "description": "Corresponds to `\"TW_GESAMTSUMME\"`", "example": "20.25" } }, "required": [ "trip_start", "trip_end", "distance_traveled", "fare", "surcharge", "total_billed" ] }, "ProcessDataStandardV1Receipt": { "type": "object", "properties": { "receipt_type": { "type": "string", "enum": [ "RECEIPT", "TRAINING", "TRANSFER", "ORDER", "CANCELLATION", "ABORT", "BENEFIT_IN_KIND", "INVOICE", "OTHER", "ANNULATION" ], "example": "RECEIPT", "description": "values map to field 'BON_TYP' in DSFinV-K \n\n 'RECEIPT' = Beleg\n 'TRAINING' = AVTraining\n 'TRANSFER' = AVTransfer\n 'ORDER' = AVBestellung\n 'CANCELLATION' = AVBelegabbruch\n 'ABORT' = AVBelegabbruch\n 'BENEFIT_IN_KIND' = AVSachbezug\n 'INVOICE' = AVRechnung\n 'OTHER' = AVSonstige\n 'ANNULATION' = AVBelegstorno" }, "amounts_per_vat_rate": { "type": "array", "items": { "type": "object", "properties": { "vat_rate": { "oneOf": [ { "type": "string", "enum": [ "NORMAL", "REDUCED_1", "SPECIAL_RATE_1", "SPECIAL_RATE_2", "NULL" ], "description": "encoded as vat-rate names" }, { "type": "string", "enum": ["19", "7", "10.7", "5.5", "0"], "description": "encoded as quoted decimal (field 'UST_SATZ' in DSFinV-K)\n\n**WARNING**: these constants are **DEPRECATED** and will be removed in the next major version!" } ], "description": "encoded as vat-rate names or as quoted decimal (field 'UST_SATZ' in DSFinV-K)" }, "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d{2,5})$", "description": "encoded as quoted decimal with at least 2 decimals [max. 5 decimals] \n (field 'BRUTTO' in DSFinV-K)", "example": "20.25" } }, "required": ["vat_rate", "amount"] } }, "amounts_per_payment_type": { "type": "array", "items": { "type": "object", "properties": { "payment_type": { "type": "string", "enum": ["CASH", "NON_CASH"], "example": "CASH", "description": "values map to field 'ZAHLART_TYP' in DSFinV-K" }, "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d{2,5})$", "description": "encoded as quoted decimal with at least 2 decimals [max. 5 decimals] \n (field 'ZAHLART_BETRAG' in DSFinV-K)", "example": "0.12" }, "currency_code": { "type": "string", "pattern": "^[a-zA-Z]{3}$", "example": "USD", "description": "currency code according to [Appendix DSFinVK-2.0](https://www.bzst.de/DE/Unternehmen/Aussenpruefungen/DigitaleSchnittstelleFinV/digitaleschnittstellefinv.html), e.g: `\"USD\"`, `\"CHF\"`, `\"EUR\"` [ISO 4217 Norm]", "default": "EUR" } }, "required": ["payment_type", "amount"] } } }, "description": "Transaction schema for processType `\"Kassenbeleg-V1\"`", "required": ["receipt_type", "amounts_per_vat_rate"] }, "ProcessDataStandardV1Order": { "type": "object", "properties": { "line_items": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,5})?$", "description": "encoded as quoted decimal [max. 5 decimals] (field 'MENGE' up to DSFinV-K version 2.2, or the quotient of the field 'MENGE' divided by field 'FAKTOR' from DSFinV-K version 2.3)", "example": "10.98" }, "text": { "type": "string", "maxLength": 255, "example": "Eisbecher “Himbeere“", "description": "Designation of the product or service (field 'ARTIKELTEXT' in DSFinV-K)" }, "price_per_unit": { "type": "string", "pattern": "^-?\\d+(\\.\\d{2,5})$", "description": "encoded as quoted decimal with at least 2 decimals [max. 5 decimals] (field 'STK_BR' in DSFinV-K)", "example": "20.25" } }, "required": ["quantity", "text", "price_per_unit"] } } }, "description": "Transaction schema for processType `\"Bestellung-V1\"`.
Please note the differences in Annex I of DSFinV-K, between version 2.3 and version 2.2 concerning the field `order.line_items[].quantity`.", "required": ["line_items"] }, "ProcessDataStandardV1Other": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Transaction schema for processType `\"SonstigerVorgang\"`" }, "ProcessDataRaw": { "type": "object", "properties": { "process_type": { "type": "string", "description": "Identifies the type of the transaction (see *processType* in [TR-03151](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR03151/TR-03151.pdf?__blob=publicationFile))", "example": "Kassenbeleg-V1" }, "process_data": { "type": "string", "description": "Identifies the data of the transaction as a base64 encoded string (see *processData* in [TR-03151](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR03151/TR-03151.pdf?__blob=publicationFile))", "example": "dGVzdA==" } }, "required": ["process_type", "process_data"] }, "ProcessDataV1": { "type": "object", "minProperties": 1, "maxProperties": 1, "oneOf": [ { "properties": { "receipt": { "$ref": "#/components/schemas/ProcessDataStandardV1Receipt" } }, "required": ["receipt"] }, { "properties": { "order": { "$ref": "#/components/schemas/ProcessDataStandardV1Order" } }, "required": ["order"] }, { "properties": { "other": { "$ref": "#/components/schemas/ProcessDataStandardV1Other" } }, "required": ["other"] } ], "description": "Transaction data schema for **PoS Systems/Cash Registers** based on [DSFinV-K](https://www.bzst.de/DE/Unternehmen/Aussenpruefungen/DigitaleSchnittstelleFinV/digitaleschnittstellefinv.html)" }, "ProcessDataDSFinVTWV1PowerStatusEmptyStart": { "type": "object", "properties": {}, "additionalProperties": false }, "ProcessDataDSFinVTWV1PowerStatusFinish": { "type": "object", "description": "Transaction schema for processType `\"Einschalten-V1\"`", "properties": { "system": { "type": "object", "description": "Describes the meter itself", "properties": { "meter_type": { "$ref": "#/components/schemas/DSFinVTWMeterType" }, "manufacturer": { "type": "string", "description": "Corresponds to `\"TW_HERSTELLER\"` in DSFinV-TW.", "maxLength": 50 }, "model": { "type": "string", "description": "Corresponds to `\"TW_MODELL\"` in DSFinV-TW.", "maxLength": 50 } }, "required": ["meter_type", "manufacturer", "model"] }, "counter_unit": { "type": "object", "description": "Describes the counter unit and its current state (compare point 15.1 of the appendix IX of the EU directive 2014/32/EU)", "properties": { "total_kilometers": { "$ref": "#/components/schemas/DSFinVTWKilometerReading" }, "total_kilometers_with_passengers": { "$ref": "#/components/schemas/DSFinVTWKilometerReading" }, "total_passenger_transfers": { "$ref": "#/components/schemas/DSFinVTWPassengerTransfers" }, "total_surcharge_or_base_amount": { "$ref": "#/components/schemas/DSFinVTWTotalSurchargeOrBaseAmount" }, "total_billed_amount": { "$ref": "#/components/schemas/DSFinVTWTotalBilledFareAmount" } }, "required": [ "total_kilometers", "total_kilometers_with_passengers", "total_passenger_transfers", "total_surcharge_or_base_amount", "total_billed_amount" ] }, "generic_data": { "type": "object", "description": "Further describes the meter (compare point 4 of the appendix IX of the EU Directive 2014/32/EU)", "properties": { "constant": { "$ref": "#/components/schemas/DSFinVTWConstant" }, "last_backup": { "$ref": "#/components/schemas/Timestamp" }, "vehicle_id": { "$ref": "#/components/schemas/DSFinVTWVehicleId" }, "local_time": { "$ref": "#/components/schemas/Timestamp" }, "tariff_id": { "$ref": "#/components/schemas/DSFinVTWTariffId" } }, "required": [ "constant", "last_backup", "vehicle_id", "local_time", "tariff_id" ] } }, "required": ["system", "counter_unit", "generic_data"] }, "ProcessDataDSFinVTWV1PowerOffEmptyStart": { "type": "object", "properties": {} }, "ProcessDataDSFinVTWV1PowerOffFinish": { "type": "object", "description": "Transaction schema for processType `\"Ausschalten-V1\"`" }, "ProcessDataDSFinVTWV1DriverLogonFinish": { "type": "object", "properties": { "type": { "type": "string", "description": "Sets `\"Fahreranmeldung\"` as the operation in the processData", "enum": ["LOGON"] }, "driver_id": { "$ref": "#/components/schemas/DSFinVTWDriverId" } }, "required": ["type", "driver_id"] }, "ProcessDataDSFinVTWV1DriverLogoffFinish": { "type": "object", "properties": { "type": { "type": "string", "description": "Sets `\"Fahrerabmeldung\"` as the operation in the processData", "enum": ["LOGOFF"] }, "driver_id": { "$ref": "#/components/schemas/DSFinVTWDriverId" } }, "required": ["type", "driver_id"] }, "ProcessDataDSFinVTWV1DriverEmptyStart": { "type": "object", "properties": {}, "additionalProperties": false }, "ProcessDataDSFinVTWV1Driver": { "type": "object", "description": "Transaction schema for processType `\"Fahrer-V1\"`", "oneOf": [ { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1DriverEmptyStart" }, { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1DriverLogonFinish" }, { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1DriverLogoffFinish" } ] }, "ProcessDataDSFinVTWV1TripReceiptEmptyStart": { "type": "object", "properties": {}, "additionalProperties": false }, "ProcessDataDSFinVTWV1TripReceiptFinish": { "type": "object", "description": "Transaction schema for processType `\"Fahrtbeleg-V1\"`", "properties": { "meter_type": { "$ref": "#/components/schemas/DSFinVTWMeterType" }, "vehicle_id": { "$ref": "#/components/schemas/DSFinVTWVehicleId" }, "tariff_id": { "$ref": "#/components/schemas/DSFinVTWTariffId" }, "trip_type": { "type": "string", "description": "Type of the trip itself\n\n```\nTARIFF = Tariffahrt\nOTHER = sonstige Fahrt\n```", "enum": ["TARIFF", "OTHER"] }, "trip_data": { "$ref": "#/components/schemas/DSFinVTWPriceData" }, "amounts_per_vat_rate": { "type": "array", "description": "Summary of each tax sale per vat rate name for given trip", "items": { "type": "object", "properties": { "vat_rate": { "type": "string", "enum": ["NORMAL", "REDUCED_1", "NULL"], "description": "encoded as vat rate names (relates to the fields 'ALLGM_BRUTTO', 'ERM_BRUTTO' and 'NULL' in DSFinV-TW)" }, "amount": { "$ref": "#/components/schemas/DSFinVTWNumeric" } }, "required": ["vat_rate", "amount"] } }, "amounts_per_payment_type": { "type": "object", "description": "Summary of each payment type and currency (only needed if the taxi- or odometer can act as a simple cash register)", "properties": { "cash": { "type": "array", "description": "Summary of amounts given in cash per currency", "items": { "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/DSFinVTWNumeric" }, "currency_code": { "type": "string", "pattern": "^[a-zA-Z]{3}$", "example": "EUR", "description": "currency code according to ISO 4217", "default": "EUR" } }, "required": ["amount"] } }, "non_cash": { "type": "array", "description": "Summary of amounts given in non cash (e.g. credit card, etc.) per currency", "items": { "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/DSFinVTWNumeric" }, "currency_code": { "type": "string", "pattern": "^[a-zA-Z]{3}$", "example": "EUR", "description": "currency code according to ISO 4217", "default": "EUR" } }, "required": ["amount"] } } } } }, "required": [ "meter_type", "vehicle_id", "tariff_id", "trip_type", "trip_data", "amounts_per_vat_rate" ] }, "ProcessDataDSFinVTWV1EmptyTrip": { "type": "object", "description": "Transaction schema for processType `\"Frei-V1\"`

\nUnlike other transactions, data must be transmitted both at the start and at the end of this transaction.", "properties": { "kilometer_reading": { "$ref": "#/components/schemas/DSFinVTWKilometerReading" } }, "required": ["kilometer_reading"] }, "ProcessDataDSFinVTWV1Break": { "type": "object", "description": "Transaction schema for processType `\"Pause-V1\"`

\nUnlike other transactions, data must be transmitted both at the start and at the end of this transaction.", "properties": { "kilometer_reading": { "$ref": "#/components/schemas/DSFinVTWKilometerReading" } }, "required": ["kilometer_reading"] }, "ProcessDataDSFinVTWV1Other": { "type": "string", "maxLength": 512, "description": "Transaction schema for processType `\"SonstigerVorgangTW\"`" }, "ProcessDataDSFinVTWV1Response": { "type": "object", "description": "Transaction data schema for **Taximeter and Odometer** based on [DSFinV-TW](https://www.bzst.de/DE/Unternehmen/Aussenpruefungen/DigitaleSchnittstelleTaxameter/digitaleSchnittstelleTaxameter_node.html)", "properties": { "power_up": { "description": "Transaction schema for processType `\"Einschalten-V1\"`", "oneOf": [ { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1PowerStatusEmptyStart" }, { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1PowerStatusFinish" } ] }, "power_off": { "description": "Transaction schema for processType `\"Ausschalten-V1\"`", "oneOf": [ { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1PowerStatusEmptyStart" }, { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1PowerStatusFinish" } ] }, "driver_status": { "description": "Transaction schema for processType `\"Fahrer-V1\"`", "oneOf": [ { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1DriverEmptyStart" }, { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1DriverLogonFinish" }, { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1DriverLogoffFinish" } ] }, "trip_receipt": { "description": "Transaction schema for processType `\"Fahrtbeleg-V1\"`", "oneOf": [ { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1TripReceiptEmptyStart" }, { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1TripReceiptFinish" } ] }, "empty_trip": { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1EmptyTrip" }, "break": { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1Break" }, "other": { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1Other" } } }, "ProcessDataDSFinVTWV1": { "type": "object", "description": "Transaction data schema for **Taximeter and Odometer** based on [DSFinV-TW](https://www.bzst.de/DE/Unternehmen/Aussenpruefungen/DigitaleSchnittstelleTaxameter/digitaleSchnittstelleTaxameter_node.html)", "minProperties": 1, "maxProperties": 1, "oneOf": [ { "properties": { "power_up": { "description": "Transaction schema for processType `\"Einschalten-V1\"`", "oneOf": [ { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1PowerStatusEmptyStart" }, { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1PowerStatusFinish" } ] } }, "required": ["power_up"] }, { "properties": { "power_off": { "description": "Transaction schema for processType `\"Ausschalten-V1\"`", "oneOf": [ { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1PowerStatusEmptyStart" }, { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1PowerStatusFinish" } ] } }, "required": ["power_off"] }, { "properties": { "driver_status": { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1Driver" } }, "required": ["driver_status"] }, { "properties": { "trip_receipt": { "description": "Transaction schema for processType `\"Fahrtbeleg-V1\"`", "oneOf": [ { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1TripReceiptEmptyStart" }, { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1TripReceiptFinish" } ] } }, "required": ["trip_receipt"] }, { "properties": { "empty_trip": { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1EmptyTrip" } }, "required": ["empty_trip"] }, { "properties": { "break": { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1Break" } }, "required": ["break"] }, { "properties": { "other": { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1Other" } }, "required": ["other"] } ] }, "ListTssQueryString": { "type": "object", "properties": { "order_by": { "type": "string", "description": "Specifies the property to sort by", "enum": [ "description", "state", "time_creation", "time_init", "time_disable" ] }, "states": { "type": "array", "description": "Filter to include only specific states of TSS \n\nExample: `states%5B0%5D=DISABLED&states%5B1%5D=INITIALIZED`", "items": { "type": "string", "enum": [ "CREATED", "UNINITIALIZED", "INITIALIZED", "DISABLED", "DELETED", "DEFECTIVE", "EVICTED" ], "uniqueItems": true } }, "order": { "type": "string", "description": "Determines the sorting order", "enum": ["asc", "desc"], "default": "asc" }, "limit": { "description": "Limits the number of returned results", "type": "integer", "maximum": 100, "minimum": 1, "default": 100 }, "offset": { "description": "Skips the specified number of results from the result set", "type": "integer", "default": 0, "minimum": 0 }, "show_deleted": { "description": "Set to `true` to include the resources of deleted TSS, set to `false` to hide them.", "type": "boolean", "enum": [false, true], "default": true } } }, "ListClientsQuerystring": { "type": "object", "properties": { "order_by": { "type": "string", "description": "Specifies the property to sort by", "enum": ["serial_number", "time_creation"] }, "serial_number": { "type": "string", "description": "Filter to return only specific clients" }, "state": { "type": "string", "enum": ["REGISTERED", "DEREGISTERED"], "description": "Defines the state of a Client in the TSS. Only registered clients are able to write transactions.", "example": "REGISTERED" }, "order": { "type": "string", "description": "Determines the sorting order", "enum": ["asc", "desc"], "default": "asc" }, "limit": { "description": "Limits the number of returned results", "type": "integer", "maximum": 100, "minimum": 1, "default": 100 }, "offset": { "description": "Skips the specified number of results from the result set", "type": "integer", "default": 0, "minimum": 0 }, "show_deleted": { "description": "Set to `true` to include the resources of deleted TSS, set to `false` to hide them.", "type": "boolean", "enum": [false, true], "default": true } } }, "ListTransactionsQuerystring": { "type": "object", "properties": { "order_by": { "type": "string", "description": "Specifies the property to sort by", "enum": ["number", "state", "time_start", "time_end"] }, "states": { "description": "Filter to include only specific states \n\nExample: `states%5B0%5D=FINISHED&states%5B1%5D=CANCELLED`", "type": "array", "items": { "$ref": "#/components/schemas/TxState" } }, "order": { "type": "string", "description": "Determines the sorting order", "enum": ["asc", "desc"], "default": "asc" }, "limit": { "description": "Limits the number of returned results", "type": "integer", "maximum": 100, "minimum": 1, "default": 100 }, "offset": { "description": "Skips the specified number of results from the result set", "type": "integer", "default": 0, "minimum": 0 }, "show_deleted": { "description": "Set to `true` to include the resources of deleted TSS, set to `false` to hide them.", "type": "boolean", "enum": [false, true], "default": true } } }, "ListExportsQuerystring": { "type": "object", "properties": { "order_by": { "type": "string", "description": "Specifies the property to sort by", "enum": [ "state", "time_request", "time_start", "time_end", "time_expiration", "time_error" ] }, "states": { "description": "Filter to include only specific states \n\nExample: `states%5B0%5D=PENDING&states%5B1%5D=WORKING`", "type": "array", "items": { "type": "string", "enum": ["CANCELLED", "PENDING", "WORKING", "COMPLETED", "ERROR"], "uniqueItems": true } }, "order": { "type": "string", "description": "Determines the sorting order", "enum": ["asc", "desc"], "default": "asc" }, "limit": { "description": "Limits the number of returned results", "type": "integer", "maximum": 100, "minimum": 1, "default": 100 }, "offset": { "description": "Skips the specified number of results from the result set", "type": "integer", "default": 0, "minimum": 0 }, "show_deleted": { "description": "Set to `true` to include the resources of deleted TSS, set to `false` to hide them.", "type": "boolean", "enum": [false, true], "default": true } } }, "TriggerExportsQuerystring": { "type": "object", "properties": { "client_id": { "type": "string", "description": "Only return log messages associated with the given client (other query parameters will be ignored)." }, "transaction_number": { "type": "string", "pattern": "^\\d+$", "description": "Only return log messages associated with the given transaction number." }, "start_transaction_number": { "type": "string", "pattern": "^\\d+$", "description": "Only return log messages greater than or equal to the given start transaction number." }, "end_transaction_number": { "type": "string", "pattern": "^\\d+$", "description": "Only return log messages less than or equal to the given end transaction number." }, "start_date": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Only return log messages with dates larger than or equal to the given start date.", "example": 1577833200 }, "end_date": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Only return log messages with dates smaller than or equal to the given start date.", "example": 1577833200 }, "maximum_number_records": { "type": "string", "pattern": "^\\d+$", "description": "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. \n\nMinimal value is `\"1\"`. \n\nMaximal value is `\"1000000\"`.", "default": "1000000" }, "start_signature_counter": { "type": "string", "pattern": "^\\d+$", "description": "Only return log messages with signature counters larger than or equal to the given value." }, "end_signature_counter": { "type": "string", "pattern": "^\\d+$", "description": "Only return log messages with signature counters smaller than or equal to the given value." } } }, "Middleware": { "type": "object", "description": "Contains data used by the middleware", "properties": { "smaers_version": { "type": "string", "description": "The version of SMAERS used by the SMAERS Gateway to use the appropriate SMAERS container image" }, "latest_stored_signature_counter_in_backend": { "type": "string", "format": "bigint", "description": "The largest signature counter value known by the fiskaly sign Backend for this TSS" }, "client_serial_number": { "$ref": "#/components/schemas/ClientSerialNumber" }, "smaers_url": { "$ref": "#/components/schemas/SmaersUrl" } }, "required": ["latest_stored_signature_counter_in_backend", "smaers_url"] }, "MiddlewareTxRequest": { "type": "object", "properties": { "state": { "$ref": "#/components/schemas/TxState" }, "client_id": { "$ref": "#/components/schemas/ClientId" }, "schema": { "type": "object", "properties": { "standard_v1": { "$ref": "#/components/schemas/ProcessDataV1" }, "dsfinvtw_v1": { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1" }, "raw": { "$ref": "#/components/schemas/ProcessDataRaw" } } }, "metadata": { "$ref": "#/components/schemas/MetadataRequest" } }, "required": ["state", "client_id"] }, "AuthenticationRequest": { "oneOf": [ { "$ref": "#/components/schemas/ApiKeyAuthentication" }, { "$ref": "#/components/schemas/RefreshTokenAuthentication" } ] }, "AdminAuthenticationRequest": { "type": "object", "properties": { "admin_pin": { "$ref": "#/components/schemas/AdminPin" } }, "required": ["admin_pin"] }, "AdminLogoutRequest": { "type": "object" }, "AuthenticationResponse": { "type": "object", "description": "Successful authentication", "properties": { "access_token": { "type": "string" }, "access_token_claims": { "type": "object", "description": "Contains information about the claims that are embedded within the access token. Can be used to retrieve one's own `organization_id`.", "properties": { "env": { "$ref": "#/components/schemas/Env" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" } }, "required": ["env"] }, "access_token_expires_in": { "type": "integer" }, "access_token_expires_at": { "$ref": "#/components/schemas/Timestamp" }, "refresh_token": { "$ref": "#/components/schemas/RefreshToken" }, "refresh_token_expires_in": { "type": "integer" }, "refresh_token_expires_at": { "$ref": "#/components/schemas/Timestamp" } }, "required": ["access_token"] }, "AuthenticationViaMiddlewareResponse": { "type": "object", "description": "Successful authentication" }, "AdminLogoutResponse": { "type": "object", "description": "Successful Admin session logout" }, "StatusResponse": { "type": "object", "description": "Status report", "properties": { "_success": { "type": "boolean" } }, "required": ["_success"] }, "DataEncoding": { "type": "string", "description": "The Data Encoding Type used for signed transactions.", "enum": ["UTF-8"], "example": "UTF-8" }, "SignatureCounter": { "type": "string", "format": "bigint", "description": "The Signature Counter of the TSS" }, "TransactionCounter": { "type": "string", "format": "bigint", "description": "The Transaction Counter of the TSS." }, "NumberRegisteredClients": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The current number of registered Clients of the TSS." }, "NumberActiveTransactions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The current number of active Transactions of the TSS." }, "MaxNumberRegisteredClients": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The maximum number of registered Clients of the TSS." }, "MaxNumberActiveTransactions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The maximum number of active Transactions of the TSS." }, "CreateTssRequest": { "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/MetadataRequest" } } }, "TssRequestParams": { "type": "object", "properties": { "tss_id": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000", "description": "Identifies a TSS" } }, "required": ["tss_id"] }, "UpdateClientRequest": { "type": "object", "properties": { "state": { "type": "string", "enum": ["REGISTERED", "DEREGISTERED"], "description": "Defines the state of a Client in the TSS. Only registered clients are able to write transactions.", "example": "REGISTERED" }, "metadata": { "$ref": "#/components/schemas/MetadataRequest" } }, "required": ["state"] }, "ClientRequestParams": { "type": "object", "properties": { "tss_id": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000", "description": "Identifies a TSS" }, "client_id": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000", "description": "Identifies a client by a self-generated [UUIDv4](https://datatracker.ietf.org/doc/html/rfc4122)" } }, "required": ["tss_id", "client_id"] }, "CreateClientRequest": { "type": "object", "properties": { "serial_number": { "$ref": "#/components/schemas/ClientSerialNumber" }, "metadata": { "$ref": "#/components/schemas/MetadataRequest" } }, "required": ["serial_number"] }, "TxSchema": { "type": "object", "minProperties": 1, "maxProperties": 1, "oneOf": [ { "properties": { "standard_v1": { "$ref": "#/components/schemas/ProcessDataV1" } }, "required": ["standard_v1"] }, { "properties": { "dsfinvtw_v1": { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1" } }, "required": ["dsfinvtw_v1"] }, { "properties": { "raw": { "$ref": "#/components/schemas/ProcessDataRaw" } }, "required": ["raw"] } ] }, "TxRequest": { "type": "object", "properties": { "state": { "$ref": "#/components/schemas/TxState" }, "client_id": { "$ref": "#/components/schemas/ClientId" }, "schema": { "$ref": "#/components/schemas/TxSchema" }, "metadata": { "$ref": "#/components/schemas/MetadataRequest" } }, "required": ["state", "client_id"] }, "ExportState": { "type": "string", "enum": ["CANCELLED", "PENDING", "WORKING", "COMPLETED", "ERROR"], "description": "The current state of the export operation." }, "ExportException": { "type": "string", "enum": [ "E_UNEXPECTED", "E_ID_NOT_FOUND", "E_BAD_REQUEST", "E_INTERNAL", "E_TRANSACTION_ID_NOT_FOUND", "E_NO_DATA_AVAILABLE", "E_TOO_MANY_RECORDS", "E_ALREADY_PROCESSING", "E_LOGS_NOT_DELETED", "E_EXPORT_PROCESSING_TIMEOUT" ], "description": "If the state property is equal to `error`, then the error is described by this property." }, "ExportResponse": { "type": "object", "properties": { "state": { "$ref": "#/components/schemas/ExportState" }, "exception": { "$ref": "#/components/schemas/ExportException" }, "time_request": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Time of the initial request.", "example": 1577833200 }, "time_start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Time of the start of the export operation.", "example": 1577833200 }, "time_end": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Time of the end of the export operation.", "example": 1577833200 }, "time_expiration": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Time of the expiration of the generated TAR file.", "example": 1577833200 }, "time_error": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Time of the error of the export operation.", "example": 1577833200 }, "estimated_time_of_completion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Estimated point in time when the state will change to `COMPLETED`", "example": 1577833200 }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "tss_id": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000", "description": "Identifies a TSS" }, "_type": { "type": "string", "example": "EXPORT", "enum": ["EXPORT"] }, "_id": { "$ref": "#/components/schemas/ExportId" }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" } }, "required": [ "state", "time_request", "_type", "_id", "_env", "_version" ], "description": "Returns the export resource", "example": { "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" } }, "BaseUpdateTssResponse": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/TssDescription" }, "state": { "type": "string", "enum": ["UNINITIALIZED", "INITIALIZED", "DISABLED"] }, "certificate": { "$ref": "#/components/schemas/TssCertificate" }, "serial_number": { "$ref": "#/components/schemas/TssSerialNumber" }, "public_key": { "$ref": "#/components/schemas/TssPublicKey" }, "bsi_certification_id": { "type": "string", "description": "ID of the TSS certification issued by the German Federal Office for Information Security (BSI)" }, "signature_counter": { "$ref": "#/components/schemas/SignatureCounter" }, "signature_algorithm": { "$ref": "#/components/schemas/Algorithm" }, "signature_timestamp_format": { "$ref": "#/components/schemas/TimestampFormat" }, "transaction_counter": { "$ref": "#/components/schemas/TransactionCounter" }, "transaction_data_encoding": { "$ref": "#/components/schemas/DataEncoding" }, "number_registered_clients": { "$ref": "#/components/schemas/NumberRegisteredClients" }, "max_number_registered_clients": { "$ref": "#/components/schemas/MaxNumberRegisteredClients" }, "number_active_transactions": { "$ref": "#/components/schemas/NumberActiveTransactions" }, "max_number_active_transactions": { "$ref": "#/components/schemas/MaxNumberActiveTransactions" }, "supported_update_variants": { "$ref": "#/components/schemas/SupportedUpdateVariants" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_id": { "$ref": "#/components/schemas/Uuid" }, "_type": { "type": "string", "example": "TSS", "enum": ["TSS"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_creation": { "$ref": "#/components/schemas/Timestamp" }, "time_uninit": { "$ref": "#/components/schemas/Timestamp" }, "time_init": { "$ref": "#/components/schemas/Timestamp" }, "time_defective": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "state", "time_creation", "certificate", "serial_number", "public_key", "signature_algorithm", "signature_timestamp_format", "transaction_data_encoding", "max_number_registered_clients", "max_number_active_transactions", "supported_update_variants", "_id", "_type", "_env", "_version" ] }, "BaseCreateClientResponse": { "type": "object", "properties": { "serial_number": { "$ref": "#/components/schemas/ClientSerialNumber" }, "state": { "type": "string", "enum": ["REGISTERED", "DEREGISTERED"], "description": "Defines the state of a Client in the TSS. Only registered clients are able to write transactions.", "example": "REGISTERED" }, "tss_id": { "$ref": "#/components/schemas/TssId" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_id": { "$ref": "#/components/schemas/ClientId" }, "_type": { "type": "string", "example": "CLIENT", "enum": ["CLIENT"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" } }, "required": [ "serial_number", "state", "tss_id", "_id", "_type", "_env", "_version" ] }, "BaseUpdateClientResponse": { "type": "object", "properties": { "serial_number": { "$ref": "#/components/schemas/ClientSerialNumber" }, "state": { "type": "string", "enum": ["REGISTERED", "DEREGISTERED"], "description": "Defines the state of a Client in the TSS. Only registered clients are able to write transactions.", "example": "REGISTERED" }, "tss_id": { "$ref": "#/components/schemas/TssId" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_id": { "$ref": "#/components/schemas/ClientId" }, "_type": { "type": "string", "example": "CLIENT", "enum": ["CLIENT"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_creation": { "$ref": "#/components/schemas/Timestamp" }, "time_update": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "serial_number", "state", "tss_id", "_id", "_type", "_env", "_version", "time_creation" ] }, "ProcessDataStandardV1": { "type": "object", "properties": { "receipt": { "$ref": "#/components/schemas/ProcessDataStandardV1Receipt" }, "order": { "$ref": "#/components/schemas/ProcessDataStandardV1Order" }, "other": { "$ref": "#/components/schemas/ProcessDataStandardV1Other" } } }, "BaseTxResponse": { "type": "object", "description": "Returns the Transaction resource", "properties": { "number": { "$ref": "#/components/schemas/TxNum" }, "time_start": { "$ref": "#/components/schemas/Timestamp" }, "client_serial_number": { "$ref": "#/components/schemas/ClientSerialNumber" }, "tss_serial_number": { "$ref": "#/components/schemas/TssSerialNumber" }, "state": { "$ref": "#/components/schemas/TxState" }, "client_id": { "$ref": "#/components/schemas/ClientId" }, "schema": { "type": "object", "properties": { "standard_v1": { "$ref": "#/components/schemas/ProcessDataStandardV1" }, "dsfinvtw_v1": { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1Response" }, "raw": { "$ref": "#/components/schemas/ProcessDataRaw" } } }, "revision": { "$ref": "#/components/schemas/TxRevisionRetrieval" }, "latest_revision": { "$ref": "#/components/schemas/TxRevisionRetrieval" }, "tss_id": { "$ref": "#/components/schemas/TssId" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_type": { "type": "string", "example": "TRANSACTION", "enum": ["TRANSACTION"] }, "_id": { "$ref": "#/components/schemas/TxId" }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" } }, "required": [ "tss_id", "tss_serial_number", "client_id", "client_serial_number", "state", "revision", "latest_revision", "_type", "_id", "_env", "_version" ] }, "MiddlewarePendingRequestErrorResponse": { "type": "object", "description": "Cannot accept a new pending request due to an existing pending request", "properties": { "code": { "type": "string", "example": "E_MIDDLEWARE_PENDING_REQUEST", "enum": ["E_MIDDLEWARE_PENDING_REQUEST"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 444 }, "error": { "type": "string" }, "_middleware": { "$ref": "#/components/schemas/Middleware" } } }, "MiddlewarePendingUpdateTssResponse": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/TssDescription" }, "state": { "type": "string", "enum": ["UNINITIALIZED", "INITIALIZED", "DISABLED"] }, "certificate": { "$ref": "#/components/schemas/TssCertificate" }, "serial_number": { "$ref": "#/components/schemas/TssSerialNumber" }, "public_key": { "$ref": "#/components/schemas/TssPublicKey" }, "bsi_certification_id": { "type": "string", "description": "ID of the TSS certification issued by the German Federal Office for Information Security (BSI)" }, "signature_counter": { "$ref": "#/components/schemas/SignatureCounter" }, "signature_algorithm": { "$ref": "#/components/schemas/Algorithm" }, "signature_timestamp_format": { "$ref": "#/components/schemas/TimestampFormat" }, "transaction_counter": { "$ref": "#/components/schemas/TransactionCounter" }, "transaction_data_encoding": { "$ref": "#/components/schemas/DataEncoding" }, "number_registered_clients": { "$ref": "#/components/schemas/NumberRegisteredClients" }, "max_number_registered_clients": { "$ref": "#/components/schemas/MaxNumberRegisteredClients" }, "number_active_transactions": { "$ref": "#/components/schemas/NumberActiveTransactions" }, "max_number_active_transactions": { "$ref": "#/components/schemas/MaxNumberActiveTransactions" }, "supported_update_variants": { "$ref": "#/components/schemas/SupportedUpdateVariants" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_id": { "$ref": "#/components/schemas/Uuid" }, "_type": { "type": "string", "example": "TSS", "enum": ["TSS"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_creation": { "$ref": "#/components/schemas/Timestamp" }, "time_uninit": { "$ref": "#/components/schemas/Timestamp" }, "time_init": { "$ref": "#/components/schemas/Timestamp" }, "time_defective": { "$ref": "#/components/schemas/Timestamp" }, "_middleware": { "$ref": "#/components/schemas/Middleware" } }, "description": "Returns the pending updated TSS resource that has been accepted for processing. The backend still needs data from the log message(s) generated by the SMAERS to complete the processing.", "required": [ "state", "time_creation", "certificate", "serial_number", "public_key", "signature_algorithm", "signature_timestamp_format", "transaction_data_encoding", "max_number_registered_clients", "max_number_active_transactions", "supported_update_variants", "_id", "_type", "_env", "_version", "_middleware" ] }, "MiddlewarePendingCreateClientResponse": { "type": "object", "properties": { "serial_number": { "$ref": "#/components/schemas/ClientSerialNumber" }, "state": { "type": "string", "enum": ["REGISTERED", "DEREGISTERED"], "description": "Defines the state of a Client in the TSS. Only registered clients are able to write transactions.", "example": "REGISTERED" }, "tss_id": { "$ref": "#/components/schemas/TssId" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_id": { "$ref": "#/components/schemas/ClientId" }, "_type": { "type": "string", "example": "CLIENT", "enum": ["CLIENT"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "_middleware": { "$ref": "#/components/schemas/Middleware" } }, "description": "Returns the pending created Client resource that has been accepted for processing. The backend still needs data from the log message(s) generated by the SMAERS to complete the processing.", "required": [ "serial_number", "state", "tss_id", "_id", "_type", "_env", "_version", "_middleware" ] }, "MiddlewarePendingUpdateClientResponse": { "type": "object", "properties": { "serial_number": { "$ref": "#/components/schemas/ClientSerialNumber" }, "state": { "type": "string", "enum": ["REGISTERED", "DEREGISTERED"], "description": "Defines the state of a Client in the TSS. Only registered clients are able to write transactions.", "example": "REGISTERED" }, "tss_id": { "$ref": "#/components/schemas/TssId" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_id": { "$ref": "#/components/schemas/ClientId" }, "_type": { "type": "string", "example": "CLIENT", "enum": ["CLIENT"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_creation": { "$ref": "#/components/schemas/Timestamp" }, "time_update": { "$ref": "#/components/schemas/Timestamp" }, "_middleware": { "$ref": "#/components/schemas/Middleware" } }, "description": "Returns the pending updated Client resource that has been accepted for processing. The backend still needs data from the log message(s) generated by the SMAERS to complete the processing.", "required": [ "serial_number", "state", "tss_id", "_id", "_type", "_env", "_version", "time_creation", "_middleware" ] }, "TxLogOperationType": { "type": "string", "enum": ["Start", "Update", "Finish"] }, "MiddlewarePendingTxResponse": { "type": "object", "properties": { "number": { "$ref": "#/components/schemas/TxNum" }, "time_start": { "$ref": "#/components/schemas/Timestamp" }, "client_serial_number": { "$ref": "#/components/schemas/ClientSerialNumber" }, "tss_serial_number": { "$ref": "#/components/schemas/TssSerialNumber" }, "state": { "$ref": "#/components/schemas/TxState" }, "client_id": { "$ref": "#/components/schemas/ClientId" }, "schema": { "type": "object", "properties": { "standard_v1": { "$ref": "#/components/schemas/ProcessDataStandardV1" }, "dsfinvtw_v1": { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1Response" }, "raw": { "$ref": "#/components/schemas/ProcessDataRaw" } } }, "revision": { "$ref": "#/components/schemas/TxRevisionRetrieval" }, "latest_revision": { "$ref": "#/components/schemas/TxRevisionRetrieval" }, "tss_id": { "$ref": "#/components/schemas/TssId" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_type": { "type": "string", "example": "TRANSACTION", "enum": ["TRANSACTION"] }, "_id": { "$ref": "#/components/schemas/TxId" }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "log": { "type": "object", "properties": { "operation": { "$ref": "#/components/schemas/TxLogOperationType" }, "timestamp_format": { "$ref": "#/components/schemas/TimestampFormat" } }, "required": ["operation", "timestamp_format"] }, "signature": { "type": "object", "properties": { "algorithm": { "$ref": "#/components/schemas/Algorithm" }, "public_key": { "$ref": "#/components/schemas/TssPublicKey" } }, "required": ["algorithm", "public_key"] }, "_middleware": { "$ref": "#/components/schemas/Middleware" } }, "description": "Returns the pending Transaction resource that has been accepted for processing. The backend still needs data from the log message(s) generated by the SMAERS to complete the processing.", "required": [ "tss_id", "tss_serial_number", "client_id", "client_serial_number", "state", "revision", "latest_revision", "_type", "_id", "_env", "_version", "_middleware" ] }, "MiddlewareAdminLogoutResponse": { "type": "object", "description": "Successful Admin session logout", "properties": { "_middleware": { "$ref": "#/components/schemas/Middleware" } }, "required": ["_middleware"] }, "MiddlewareAdminAuthenticationResponse": { "type": "object", "description": "Successful Admin authentication", "properties": { "_middleware": { "$ref": "#/components/schemas/Middleware" } }, "required": ["_middleware"] }, "MiddlewareChangeAdminPinRequest": { "type": "object", "description": "Admin PIN has been changed", "properties": { "_middleware": { "$ref": "#/components/schemas/Middleware" } }, "required": ["_middleware"] }, "CreateClientResponse": { "type": "object", "description": "Returns the created Client resource", "properties": { "serial_number": { "$ref": "#/components/schemas/ClientSerialNumber" }, "state": { "type": "string", "enum": ["REGISTERED", "DEREGISTERED"], "description": "Defines the state of a Client in the TSS. Only registered clients are able to write transactions.", "example": "REGISTERED" }, "tss_id": { "$ref": "#/components/schemas/TssId" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_id": { "$ref": "#/components/schemas/ClientId" }, "_type": { "type": "string", "example": "CLIENT", "enum": ["CLIENT"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_creation": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "serial_number", "state", "tss_id", "_id", "_type", "_env", "_version", "time_creation" ] }, "UpdateClientResponse": { "type": "object", "description": "Returns the updated Client resource", "properties": { "serial_number": { "$ref": "#/components/schemas/ClientSerialNumber" }, "state": { "type": "string", "enum": ["REGISTERED", "DEREGISTERED"], "description": "Defines the state of a Client in the TSS. Only registered clients are able to write transactions.", "example": "REGISTERED" }, "tss_id": { "$ref": "#/components/schemas/TssId" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_id": { "$ref": "#/components/schemas/ClientId" }, "_type": { "type": "string", "example": "CLIENT", "enum": ["CLIENT"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_creation": { "$ref": "#/components/schemas/Timestamp" }, "time_update": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "serial_number", "state", "tss_id", "_id", "_type", "_env", "_version", "time_creation", "time_update" ] }, "ClientResponse": { "type": "object", "description": "Returns the Client resource", "properties": { "serial_number": { "$ref": "#/components/schemas/ClientSerialNumber" }, "state": { "type": "string", "enum": ["REGISTERED", "DEREGISTERED"], "description": "Defines the state of a Client in the TSS. Only registered clients are able to write transactions.", "example": "REGISTERED" }, "tss_id": { "$ref": "#/components/schemas/TssId" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_id": { "$ref": "#/components/schemas/ClientId" }, "_type": { "type": "string", "example": "CLIENT", "enum": ["CLIENT"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_creation": { "$ref": "#/components/schemas/Timestamp" }, "time_update": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "serial_number", "state", "tss_id", "_id", "_type", "_env", "_version", "time_creation", "time_update" ] }, "ClientListResponse": { "type": "object", "description": "Returns the Clients list", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClientResponse" } }, "count": { "$ref": "#/components/schemas/Count" }, "_type": { "type": "string", "example": "CLIENT_LIST", "enum": ["CLIENT_LIST"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" } }, "required": ["data", "count", "_type", "_env", "_version"] }, "BaseTssResponse": { "type": "object", "description": "Returns the created TSS resource", "properties": { "certificate": { "$ref": "#/components/schemas/TssCertificate" }, "serial_number": { "$ref": "#/components/schemas/TssSerialNumber" }, "public_key": { "$ref": "#/components/schemas/TssPublicKey" }, "signature_algorithm": { "$ref": "#/components/schemas/Algorithm" }, "signature_timestamp_format": { "$ref": "#/components/schemas/TimestampFormat" }, "transaction_data_encoding": { "$ref": "#/components/schemas/DataEncoding" }, "max_number_registered_clients": { "$ref": "#/components/schemas/MaxNumberRegisteredClients" }, "max_number_active_transactions": { "$ref": "#/components/schemas/MaxNumberActiveTransactions" }, "supported_update_variants": { "$ref": "#/components/schemas/SupportedUpdateVariants" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_id": { "$ref": "#/components/schemas/Uuid" }, "_type": { "type": "string", "example": "TSS", "enum": ["TSS"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_creation": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "certificate", "serial_number", "public_key", "signature_algorithm", "signature_timestamp_format", "transaction_data_encoding", "max_number_registered_clients", "max_number_active_transactions", "supported_update_variants", "_id", "_type", "_env", "_version", "time_creation" ] }, "CreateTssResponse": { "type": "object", "description": "Returns the created TSS resource", "properties": { "certificate": { "$ref": "#/components/schemas/TssCertificate" }, "serial_number": { "$ref": "#/components/schemas/TssSerialNumber" }, "public_key": { "$ref": "#/components/schemas/TssPublicKey" }, "signature_algorithm": { "$ref": "#/components/schemas/Algorithm" }, "signature_timestamp_format": { "$ref": "#/components/schemas/TimestampFormat" }, "transaction_data_encoding": { "$ref": "#/components/schemas/DataEncoding" }, "max_number_registered_clients": { "$ref": "#/components/schemas/MaxNumberRegisteredClients" }, "max_number_active_transactions": { "$ref": "#/components/schemas/MaxNumberActiveTransactions" }, "supported_update_variants": { "$ref": "#/components/schemas/SupportedUpdateVariants" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_id": { "$ref": "#/components/schemas/Uuid" }, "_type": { "type": "string", "example": "TSS", "enum": ["TSS"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_creation": { "$ref": "#/components/schemas/Timestamp" }, "admin_puk": { "$ref": "#/components/schemas/AdminPuk" }, "state": { "type": "string", "enum": ["CREATED"] } }, "required": [ "admin_puk", "state", "certificate", "serial_number", "public_key", "signature_algorithm", "signature_timestamp_format", "transaction_data_encoding", "max_number_registered_clients", "max_number_active_transactions", "supported_update_variants", "_id", "_type", "_env", "_version", "time_creation" ] }, "UpdateTssRequest": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/TssDescription" }, "state": { "type": "string", "enum": ["UNINITIALIZED", "INITIALIZED", "DISABLED"] }, "metadata": { "$ref": "#/components/schemas/MetadataRequest" } }, "required": ["state"], "additionalProperties": false }, "UpdateTssResponse": { "type": "object", "description": "Returns the updated TSS resource", "properties": { "description": { "$ref": "#/components/schemas/TssDescription" }, "state": { "type": "string", "enum": ["UNINITIALIZED", "INITIALIZED", "DISABLED"] }, "certificate": { "$ref": "#/components/schemas/TssCertificate" }, "serial_number": { "$ref": "#/components/schemas/TssSerialNumber" }, "public_key": { "$ref": "#/components/schemas/TssPublicKey" }, "bsi_certification_id": { "type": "string", "description": "ID of the TSS certification issued by the German Federal Office for Information Security (BSI)" }, "signature_counter": { "$ref": "#/components/schemas/SignatureCounter" }, "signature_algorithm": { "$ref": "#/components/schemas/Algorithm" }, "signature_timestamp_format": { "$ref": "#/components/schemas/TimestampFormat" }, "transaction_counter": { "$ref": "#/components/schemas/TransactionCounter" }, "transaction_data_encoding": { "$ref": "#/components/schemas/DataEncoding" }, "number_registered_clients": { "$ref": "#/components/schemas/NumberRegisteredClients" }, "max_number_registered_clients": { "$ref": "#/components/schemas/MaxNumberRegisteredClients" }, "number_active_transactions": { "$ref": "#/components/schemas/NumberActiveTransactions" }, "max_number_active_transactions": { "$ref": "#/components/schemas/MaxNumberActiveTransactions" }, "supported_update_variants": { "$ref": "#/components/schemas/SupportedUpdateVariants" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_id": { "$ref": "#/components/schemas/Uuid" }, "_type": { "type": "string", "example": "TSS", "enum": ["TSS"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_creation": { "$ref": "#/components/schemas/Timestamp" }, "time_uninit": { "$ref": "#/components/schemas/Timestamp" }, "time_init": { "$ref": "#/components/schemas/Timestamp" }, "time_defective": { "$ref": "#/components/schemas/Timestamp" }, "time_disable": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "state", "time_creation", "certificate", "serial_number", "public_key", "signature_algorithm", "signature_timestamp_format", "transaction_data_encoding", "max_number_registered_clients", "max_number_active_transactions", "supported_update_variants", "_id", "_type", "_env", "_version", "time_uninit" ] }, "TssRequest": { "description": "", "oneOf": [ { "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/MetadataRequest" } } }, { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/TssDescription" }, "state": { "type": "string", "enum": ["UNINITIALIZED", "INITIALIZED", "DISABLED"] }, "metadata": { "$ref": "#/components/schemas/MetadataRequest" } }, "required": ["state"], "additionalProperties": false } ] }, "TssResponse": { "description": "Returns the TSS resource", "properties": { "certificate": { "$ref": "#/components/schemas/TssCertificate" }, "serial_number": { "$ref": "#/components/schemas/TssSerialNumber" }, "public_key": { "$ref": "#/components/schemas/TssPublicKey" }, "signature_algorithm": { "$ref": "#/components/schemas/Algorithm" }, "signature_timestamp_format": { "$ref": "#/components/schemas/TimestampFormat" }, "transaction_data_encoding": { "$ref": "#/components/schemas/DataEncoding" }, "max_number_registered_clients": { "$ref": "#/components/schemas/MaxNumberRegisteredClients" }, "max_number_active_transactions": { "$ref": "#/components/schemas/MaxNumberActiveTransactions" }, "supported_update_variants": { "$ref": "#/components/schemas/SupportedUpdateVariants" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_id": { "$ref": "#/components/schemas/Uuid" }, "_type": { "type": "string", "example": "TSS", "enum": ["TSS"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_creation": { "$ref": "#/components/schemas/Timestamp" }, "admin_puk": { "$ref": "#/components/schemas/AdminPuk" }, "state": { "type": "string", "enum": [ "CREATED", "UNINITIALIZED", "INITIALIZED", "DISABLED", "DELETED", "DEFECTIVE", "EVICTED" ] }, "description": { "$ref": "#/components/schemas/TssDescription" }, "bsi_certification_id": { "type": "string", "description": "ID of the TSS certification issued by the German Federal Office for Information Security (BSI)" }, "signature_counter": { "$ref": "#/components/schemas/SignatureCounter" }, "transaction_counter": { "$ref": "#/components/schemas/TransactionCounter" }, "number_registered_clients": { "$ref": "#/components/schemas/NumberRegisteredClients" }, "number_active_transactions": { "$ref": "#/components/schemas/NumberActiveTransactions" }, "time_uninit": { "$ref": "#/components/schemas/Timestamp" }, "time_init": { "$ref": "#/components/schemas/Timestamp" }, "time_defective": { "$ref": "#/components/schemas/Timestamp" }, "time_disable": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "state", "certificate", "serial_number", "public_key", "signature_algorithm", "signature_timestamp_format", "transaction_data_encoding", "max_number_registered_clients", "max_number_active_transactions", "supported_update_variants", "_id", "_type", "_env", "_version", "time_creation" ] }, "RetrieveTssResponse": { "description": "Returns the TSS resource", "properties": { "certificate": { "$ref": "#/components/schemas/TssCertificate" }, "serial_number": { "$ref": "#/components/schemas/TssSerialNumber" }, "public_key": { "$ref": "#/components/schemas/TssPublicKey" }, "signature_algorithm": { "$ref": "#/components/schemas/Algorithm" }, "signature_timestamp_format": { "$ref": "#/components/schemas/TimestampFormat" }, "transaction_data_encoding": { "$ref": "#/components/schemas/DataEncoding" }, "max_number_registered_clients": { "$ref": "#/components/schemas/MaxNumberRegisteredClients" }, "max_number_active_transactions": { "$ref": "#/components/schemas/MaxNumberActiveTransactions" }, "supported_update_variants": { "$ref": "#/components/schemas/SupportedUpdateVariants" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_id": { "$ref": "#/components/schemas/Uuid" }, "_type": { "type": "string", "example": "TSS", "enum": ["TSS"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_creation": { "$ref": "#/components/schemas/Timestamp" }, "description": { "$ref": "#/components/schemas/TssDescription" }, "state": { "type": "string", "enum": [ "CREATED", "UNINITIALIZED", "INITIALIZED", "DISABLED", "DELETED", "DEFECTIVE", "EVICTED" ] }, "bsi_certification_id": { "type": "string", "description": "ID of the TSS certification issued by the German Federal Office for Information Security (BSI)" }, "signature_counter": { "$ref": "#/components/schemas/SignatureCounter" }, "transaction_counter": { "$ref": "#/components/schemas/TransactionCounter" }, "number_registered_clients": { "$ref": "#/components/schemas/NumberRegisteredClients" }, "number_active_transactions": { "$ref": "#/components/schemas/NumberActiveTransactions" }, "time_uninit": { "$ref": "#/components/schemas/Timestamp" }, "time_init": { "$ref": "#/components/schemas/Timestamp" }, "time_defective": { "$ref": "#/components/schemas/Timestamp" }, "time_disable": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "state", "certificate", "serial_number", "public_key", "signature_algorithm", "signature_timestamp_format", "transaction_data_encoding", "max_number_registered_clients", "max_number_active_transactions", "supported_update_variants", "_id", "_type", "_env", "_version", "time_creation" ] }, "ListTssResponse": { "type": "object", "description": "Returns the TSS list", "properties": { "data": { "type": "array", "items": { "description": "Returns the TSS resource", "properties": { "certificate": { "$ref": "#/components/schemas/TssCertificate" }, "serial_number": { "$ref": "#/components/schemas/TssSerialNumber" }, "public_key": { "$ref": "#/components/schemas/TssPublicKey" }, "signature_algorithm": { "$ref": "#/components/schemas/Algorithm" }, "signature_timestamp_format": { "$ref": "#/components/schemas/TimestampFormat" }, "transaction_data_encoding": { "$ref": "#/components/schemas/DataEncoding" }, "max_number_registered_clients": { "$ref": "#/components/schemas/MaxNumberRegisteredClients" }, "max_number_active_transactions": { "$ref": "#/components/schemas/MaxNumberActiveTransactions" }, "supported_update_variants": { "$ref": "#/components/schemas/SupportedUpdateVariants" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_id": { "$ref": "#/components/schemas/Uuid" }, "_type": { "type": "string", "example": "TSS", "enum": ["TSS"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_creation": { "$ref": "#/components/schemas/Timestamp" }, "description": { "$ref": "#/components/schemas/TssDescription" }, "state": { "type": "string", "enum": [ "CREATED", "UNINITIALIZED", "INITIALIZED", "DISABLED", "DELETED", "DEFECTIVE", "EVICTED" ] }, "bsi_certification_id": { "type": "string", "description": "ID of the TSS certification issued by the German Federal Office for Information Security (BSI)" }, "signature_counter": { "$ref": "#/components/schemas/SignatureCounter" }, "transaction_counter": { "$ref": "#/components/schemas/TransactionCounter" }, "number_registered_clients": { "$ref": "#/components/schemas/NumberRegisteredClients" }, "number_active_transactions": { "$ref": "#/components/schemas/NumberActiveTransactions" }, "time_uninit": { "$ref": "#/components/schemas/Timestamp" }, "time_init": { "$ref": "#/components/schemas/Timestamp" }, "time_defective": { "$ref": "#/components/schemas/Timestamp" }, "time_disable": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "state", "certificate", "serial_number", "public_key", "signature_algorithm", "signature_timestamp_format", "transaction_data_encoding", "max_number_registered_clients", "max_number_active_transactions", "supported_update_variants", "_id", "_type", "_env", "_version", "time_creation" ] } }, "count": { "$ref": "#/components/schemas/Count" }, "_type": { "type": "string", "example": "TSS_LIST", "enum": ["TSS_LIST"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" } }, "required": ["data", "count", "_type", "_env", "_version"] }, "ChangeAdminPinRequest": { "type": "object", "properties": { "admin_puk": { "$ref": "#/components/schemas/AdminPuk" }, "new_admin_pin": { "$ref": "#/components/schemas/AdminPin" } }, "required": ["admin_puk", "new_admin_pin"] }, "TxResponse": { "type": "object", "properties": { "number": { "$ref": "#/components/schemas/TxNum" }, "time_start": { "$ref": "#/components/schemas/Timestamp" }, "client_serial_number": { "$ref": "#/components/schemas/ClientSerialNumber" }, "tss_serial_number": { "$ref": "#/components/schemas/TssSerialNumber" }, "state": { "$ref": "#/components/schemas/TxState" }, "client_id": { "$ref": "#/components/schemas/ClientId" }, "schema": { "type": "object", "properties": { "standard_v1": { "$ref": "#/components/schemas/ProcessDataStandardV1" }, "dsfinvtw_v1": { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1Response" }, "raw": { "$ref": "#/components/schemas/ProcessDataRaw" } } }, "revision": { "$ref": "#/components/schemas/TxRevisionRetrieval" }, "latest_revision": { "$ref": "#/components/schemas/TxRevisionRetrieval" }, "tss_id": { "$ref": "#/components/schemas/TssId" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_type": { "type": "string", "example": "TRANSACTION", "enum": ["TRANSACTION"] }, "_id": { "$ref": "#/components/schemas/TxId" }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_end": { "$ref": "#/components/schemas/Timestamp" }, "qr_code_data": { "type": "string", "description": "Data of the QR Code according to Appendix I of [DSFinV-K](https://www.bzst.de/DE/Unternehmen/Aussenpruefungen/DigitaleSchnittstelleFinV/digitaleschnittstellefinv_node.html)", "example": "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": { "type": "object", "properties": { "operation": { "$ref": "#/components/schemas/TxLogOperationType" }, "timestamp": { "$ref": "#/components/schemas/Timestamp" }, "timestamp_format": { "$ref": "#/components/schemas/TimestampFormat" } }, "required": ["operation", "timestamp", "timestamp_format"] }, "signature": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/SignatureValue" }, "algorithm": { "$ref": "#/components/schemas/Algorithm" }, "counter": { "$ref": "#/components/schemas/BigintCounter" }, "public_key": { "$ref": "#/components/schemas/TssPublicKey" } }, "required": ["value", "algorithm", "counter", "public_key"] } }, "description": "Returns the Transaction resource", "required": [ "tss_id", "tss_serial_number", "client_id", "client_serial_number", "state", "revision", "latest_revision", "_type", "_id", "_env", "_version", "number", "time_start", "log", "signature" ] }, "TxListResponse": { "type": "object", "description": "Returns a list of transactions", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TxResponse" } }, "count": { "$ref": "#/components/schemas/Count" }, "_type": { "type": "string", "example": "TRANSACTION_LIST", "enum": ["TRANSACTION_LIST"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" } }, "required": ["data", "count", "_type", "_env", "_version"] }, "ExportListResponse": { "type": "object", "description": "Returns the Export list", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExportResponse" } }, "count": { "$ref": "#/components/schemas/Count" }, "_type": { "type": "string", "example": "EXPORT_LIST", "enum": ["EXPORT_LIST"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" } }, "required": ["data", "count", "_type", "_env", "_version"] }, "ClientParams": { "type": "object", "properties": { "tss_id": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000", "description": "Identifies a TSS" }, "client_id": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000", "description": "Identifies a client by a self-generated [UUIDv4](https://datatracker.ietf.org/doc/html/rfc4122)" } }, "required": ["tss_id", "client_id"] }, "TxParams": { "type": "object", "properties": { "tss_id": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000", "description": "Identifies a TSS" }, "tx_id_or_number": { "description": "Identifies a transaction by a `tx_id` (i.e. a self-generated [UUIDv4](https://datatracker.ietf.org/doc/html/rfc4122)) or a `tx_number` that gets assigned by us", "anyOf": [ { "$ref": "#/components/schemas/TxId" }, { "$ref": "#/components/schemas/TxNum" } ] } }, "required": ["tss_id", "tx_id_or_number"] }, "TxQuerystring": { "type": "object", "properties": { "tx_revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } } }, "ExportListParams": { "type": "object", "properties": { "tss_id": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000", "description": "Identifies a TSS" } }, "required": ["tss_id"] }, "ExportParams": { "type": "object", "properties": { "tss_id": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000", "description": "Identifies a TSS" }, "export_id": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000", "description": "Identifies an Export" } }, "required": ["tss_id", "export_id"] }, "CapacitiesDepletedErrorResponse": { "type": "object", "description": "TSS creation locked", "properties": { "code": { "type": "string", "enum": [ "E_BOOTSTRAP_FILE_NOT_AVAILABLE", "E_SMAERS_GATEWAY_CAPACITIES_DEPLETED" ], "example": "E_BOOTSTRAP_FILE_NOT_AVAILABLE" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 503 }, "error": { "type": "string", "example": "Service Unavailable" } } }, "ExportDuplicateRateLimitResponse": { "type": "object", "description": "Cannot trigger concurrent identical exports for a TSS", "properties": { "code": { "type": "string", "example": "E_EXPORT_DUPLICATE_RATE_LIMITED", "enum": ["E_EXPORT_DUPLICATE_RATE_LIMITED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 409 }, "error": { "type": "string", "example": "Conflict" } } }, "TooManyExportsResponse": { "type": "object", "description": "You cannot trigger more than 10 exports per TSS in PENDING or WORKING state. Please try again later", "properties": { "code": { "type": "string", "example": "E_EXPORT_DUPLICATE_RATE_LIMITED", "enum": ["E_EXPORT_DUPLICATE_RATE_LIMITED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 409 }, "error": { "type": "string", "example": "Conflict" } } }, "ExportUnavailableErrorResponse": { "type": "object", "description": "Export temporarily unavailable", "properties": { "code": { "type": "string", "example": "E_EXPORT_TEMPORARILY_UNAVAILABLE", "enum": ["E_EXPORT_TEMPORARILY_UNAVAILABLE"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 503 }, "error": { "type": "string", "example": "Service Unavailable" } } }, "TssNotFoundErrorResponse": { "type": "object", "description": "TSS not found", "properties": { "code": { "type": "string", "example": "E_TSS_NOT_FOUND", "enum": ["E_TSS_NOT_FOUND"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } }, "ClientDeregisteredErrorResponse": { "type": "object", "description": "Client is `\"DEREGISTERED\"`", "properties": { "code": { "type": "string", "example": "E_CLIENT_DEREGISTERED", "enum": ["E_CLIENT_DEREGISTERED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 401 }, "error": { "type": "string", "example": "Unauthorized" } } }, "TssNotMutableErrorResponse": { "type": "object", "description": "Locked", "properties": { "code": { "type": "string", "enum": ["E_TSS_DEFECTIVE", "E_TSS_DELETED", "E_TSS_EVICTED"], "example": "E_TSS_DEFECTIVE" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 423 }, "error": { "type": "string", "example": "Locked" } } }, "TssDefectiveErrorResponse": { "type": "object", "description": "Operation cannot be performed because TSS is in state `DEFECTIVE`", "properties": { "code": { "type": "string", "example": "E_TSS_DEFECTIVE", "enum": ["E_TSS_DEFECTIVE"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 423 }, "error": { "type": "string", "example": "Locked" } } }, "AccessDeniedErrorResponse": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } }, "ExportNotCompletedErrorResponse": { "type": "object", "description": "Export is not COMPLETED", "properties": { "code": { "type": "string", "example": "E_EXPORT_NOT_COMPLETED", "enum": ["E_EXPORT_NOT_COMPLETED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } }, "AdminSetConfigResponse": { "type": "object", "description": "Admin config property successfully set" }, "CsplNotFoundErrorResponse": { "type": "object", "description": "CSPL not found", "properties": { "code": { "type": "string", "example": "E_CSPL_NOT_FOUND", "enum": ["E_CSPL_NOT_FOUND"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } }, "TssWithLockedCsplErrorResponse": { "type": "object", "description": "The TSS resource is locked.", "properties": { "code": { "type": "string", "example": "E_TSS_LOCKED", "enum": ["E_TSS_LOCKED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 503 }, "error": { "type": "string", "example": "Service Unavailable" } } }, "def-0": { "title": "com.fiskaly.sign-api:2.2.2" } } }, "paths": { "/api/v2/auth": { "post": { "operationId": "authenticateApi", "summary": "Authenticate API", "tags": ["Authentication"], "description": "To access our API, you need to have a valid JWT token. This endpoint creates the token with your `api_key` and `api_secret`. \nIf you don't have an `api_key`, you can create one via the [fiskaly dashboard](https://dashboard.fiskaly.com).\nThe `api_secret` will be generated for you after you create the `api_key`.\nThe token must be sent with every following request in the `Authorization` header field using the `Bearer` authentication scheme.\nSee details [here](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1).\n\nWARNING: even if you delete or otherwise deactivate your API credentials, any generated tokens will remain valid until they expire (currently up to 24 hours).", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiKeyAuthentication" }, { "$ref": "#/components/schemas/RefreshTokenAuthentication" } ] } } } }, "responses": { "200": { "description": "Successful authentication", "content": { "application/json": { "schema": { "type": "object", "description": "Successful authentication", "properties": { "access_token": { "type": "string" }, "access_token_claims": { "type": "object", "description": "Contains information about the claims that are embedded within the access token. Can be used to retrieve one's own `organization_id`.", "properties": { "env": { "$ref": "#/components/schemas/Env" }, "organization_id": { "$ref": "#/components/schemas/OrganizationId" } }, "required": ["env"] }, "access_token_expires_in": { "type": "integer" }, "access_token_expires_at": { "$ref": "#/components/schemas/Timestamp" }, "refresh_token": { "$ref": "#/components/schemas/RefreshToken" }, "refresh_token_expires_in": { "type": "integer" }, "refresh_token_expires_at": { "$ref": "#/components/schemas/Timestamp" } }, "required": ["access_token"] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "description": "Unauthorized", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 401 }, "error": { "type": "string", "example": "Unauthorized" } } } } } } } } }, "/api/v2/tss/{tss_id}/admin/auth": { "post": { "operationId": "authenticateAdmin", "summary": "Authenticate Admin", "tags": ["Authentication"], "description": "Only available via Middleware\n\nThis endpoint allows the TSS administrator (the taxpayer) to access restricted functionality.\nThe administrator needs to provide their PIN. The PIN is then verified inside the TSS.\nThe login only happens within the current session.\nAfter a new TSS has been created, the administrator needs to [set a new PIN](#operation/changeAdminPin).\nWe recommend choosing a unique PIN for every TSS. This will increase the security of your resources.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "admin_pin": { "$ref": "#/components/schemas/AdminPin" } }, "required": ["admin_pin"] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Successful authentication", "content": { "application/json": { "schema": { "type": "object", "description": "Successful authentication" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "description": "Unauthorized", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 401 }, "error": { "type": "string", "example": "Unauthorized" } } } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "TSS not found", "content": { "application/json": { "schema": { "type": "object", "description": "TSS not found", "properties": { "code": { "type": "string", "example": "E_TSS_NOT_FOUND", "enum": ["E_TSS_NOT_FOUND"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } }, "423": { "description": "Locked", "content": { "application/json": { "schema": { "type": "object", "description": "Locked", "properties": { "code": { "type": "string", "enum": [ "E_TSS_DEFECTIVE", "E_TSS_DELETED", "E_TSS_EVICTED" ], "example": "E_TSS_DEFECTIVE" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 423 }, "error": { "type": "string", "example": "Locked" } } } } } }, "432": { "description": "The requested resource is available only through the fiskaly sign Middleware", "content": { "application/json": { "schema": { "type": "object", "description": "The requested resource is available only through the fiskaly sign Middleware", "properties": { "code": { "type": "string", "example": "E_USE_MIDDLEWARE", "enum": ["E_USE_MIDDLEWARE"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 432 }, "error": { "type": "string" } } } } } }, "503": { "description": "The TSS resource is locked.", "content": { "application/json": { "schema": { "type": "object", "description": "The TSS resource is locked.", "properties": { "code": { "type": "string", "example": "E_TSS_LOCKED", "enum": ["E_TSS_LOCKED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 503 }, "error": { "type": "string", "example": "Service Unavailable" } } } } } } } } }, "/api/v2/tss/{tss_id}/admin/logout": { "post": { "operationId": "logoutAdmin", "summary": "Logout Admin", "tags": ["Authentication"], "description": "Only available via Middleware\n\nUse this endpoint to exit the administrator mode.\n\nLog out as soon as you have finished making administrative changes.\n\nThis operation can be called safely even if no admin is authenticated.", "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Successful Admin session logout", "content": { "application/json": { "schema": { "type": "object", "description": "Successful Admin session logout" } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "TSS not found", "content": { "application/json": { "schema": { "type": "object", "description": "TSS not found", "properties": { "code": { "type": "string", "example": "E_TSS_NOT_FOUND", "enum": ["E_TSS_NOT_FOUND"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } }, "423": { "description": "Locked", "content": { "application/json": { "schema": { "type": "object", "description": "Locked", "properties": { "code": { "type": "string", "enum": [ "E_TSS_DEFECTIVE", "E_TSS_DELETED", "E_TSS_EVICTED" ], "example": "E_TSS_DEFECTIVE" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 423 }, "error": { "type": "string", "example": "Locked" } } } } } }, "432": { "description": "The requested resource is available only through the fiskaly sign Middleware", "content": { "application/json": { "schema": { "type": "object", "description": "The requested resource is available only through the fiskaly sign Middleware", "properties": { "code": { "type": "string", "example": "E_USE_MIDDLEWARE", "enum": ["E_USE_MIDDLEWARE"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 432 }, "error": { "type": "string" } } } } } }, "503": { "description": "The TSS resource is locked.", "content": { "application/json": { "schema": { "type": "object", "description": "The TSS resource is locked.", "properties": { "code": { "type": "string", "example": "E_TSS_LOCKED", "enum": ["E_TSS_LOCKED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 503 }, "error": { "type": "string", "example": "Service Unavailable" } } } } } } } } }, "/api/v2/tss/{tss_id}": { "put": { "operationId": "createTss", "summary": "Create a TSS", "tags": ["Technical Security System"], "description": "This endpoint creates a TSS. The TSS is identified by a `tss_id`. The `tss_id` must comply with the [UUIDv4](https://datatracker.ietf.org/doc/html/rfc4122) standard and should be generated on your side.\nWhen you create a TSS, its state is set to `\"CREATED\"`. \nThe response for this endpoint will contain the admin PUK.\nThe administrator will need the PUK to set the admin PIN.\nMake sure to store the PUK securely. \nWhen the TSS has left the state `\"CREATED\"`, you will no longer be able to see the PUK.\nUse the [Update a TSS](#operation/updateTss) endpoint to transition to state `\"UNINITIALIZED\"`.\n\nWARNING: Future major versions of SIGN DE API will strictly enforce UUIDv4 format requirements.\nVerifying that your \"tss_id\" conforms to the UUIDv4 standard to ensure compatibility is recommended.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/MetadataRequest" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns the created TSS resource", "content": { "application/json": { "schema": { "type": "object", "description": "Returns the created TSS resource", "properties": { "certificate": { "$ref": "#/components/schemas/TssCertificate" }, "serial_number": { "$ref": "#/components/schemas/TssSerialNumber" }, "public_key": { "$ref": "#/components/schemas/TssPublicKey" }, "signature_algorithm": { "$ref": "#/components/schemas/Algorithm" }, "signature_timestamp_format": { "$ref": "#/components/schemas/TimestampFormat" }, "transaction_data_encoding": { "$ref": "#/components/schemas/DataEncoding" }, "max_number_registered_clients": { "$ref": "#/components/schemas/MaxNumberRegisteredClients" }, "max_number_active_transactions": { "$ref": "#/components/schemas/MaxNumberActiveTransactions" }, "supported_update_variants": { "$ref": "#/components/schemas/SupportedUpdateVariants" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_id": { "$ref": "#/components/schemas/Uuid" }, "_type": { "type": "string", "example": "TSS", "enum": ["TSS"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_creation": { "$ref": "#/components/schemas/Timestamp" }, "admin_puk": { "$ref": "#/components/schemas/AdminPuk" }, "state": { "type": "string", "enum": ["CREATED"] } }, "required": [ "admin_puk", "state", "certificate", "serial_number", "public_key", "signature_algorithm", "signature_timestamp_format", "transaction_data_encoding", "max_number_registered_clients", "max_number_active_transactions", "supported_update_variants", "_id", "_type", "_env", "_version", "time_creation" ] } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "enum": [ "E_TSS_LIMIT_REACHED", "E_TSS_LIMIT_PER_DAY_REACHED" ], "example": "E_TSS_LIMIT_REACHED" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "409": { "description": "TSS already exists in a lifecycle state different from `\"CREATED\"`", "content": { "application/json": { "schema": { "type": "object", "description": "TSS already exists in a lifecycle state different from `\"CREATED\"`", "properties": { "code": { "type": "string", "example": "E_TSS_CONFLICT", "enum": ["E_TSS_CONFLICT"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 409 }, "error": { "type": "string", "example": "Conflict" } } } } } }, "503": { "description": "TSS creation locked", "content": { "application/json": { "schema": { "type": "object", "description": "TSS creation locked", "properties": { "code": { "type": "string", "enum": [ "E_BOOTSTRAP_FILE_NOT_AVAILABLE", "E_SMAERS_GATEWAY_CAPACITIES_DEPLETED" ], "example": "E_BOOTSTRAP_FILE_NOT_AVAILABLE" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 503 }, "error": { "type": "string", "example": "Service Unavailable" } } } } } } } }, "get": { "operationId": "retrieveTss", "summary": "Retrieve a TSS", "tags": ["Technical Security System"], "description": "This endpoint returns information about a specific TSS.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns the TSS resource", "content": { "application/json": { "schema": { "description": "Returns the TSS resource", "properties": { "certificate": { "$ref": "#/components/schemas/TssCertificate" }, "serial_number": { "$ref": "#/components/schemas/TssSerialNumber" }, "public_key": { "$ref": "#/components/schemas/TssPublicKey" }, "signature_algorithm": { "$ref": "#/components/schemas/Algorithm" }, "signature_timestamp_format": { "$ref": "#/components/schemas/TimestampFormat" }, "transaction_data_encoding": { "$ref": "#/components/schemas/DataEncoding" }, "max_number_registered_clients": { "$ref": "#/components/schemas/MaxNumberRegisteredClients" }, "max_number_active_transactions": { "$ref": "#/components/schemas/MaxNumberActiveTransactions" }, "supported_update_variants": { "$ref": "#/components/schemas/SupportedUpdateVariants" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_id": { "$ref": "#/components/schemas/Uuid" }, "_type": { "type": "string", "example": "TSS", "enum": ["TSS"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_creation": { "$ref": "#/components/schemas/Timestamp" }, "description": { "$ref": "#/components/schemas/TssDescription" }, "state": { "type": "string", "enum": [ "CREATED", "UNINITIALIZED", "INITIALIZED", "DISABLED", "DELETED", "DEFECTIVE", "EVICTED" ] }, "bsi_certification_id": { "type": "string", "description": "ID of the TSS certification issued by the German Federal Office for Information Security (BSI)" }, "signature_counter": { "$ref": "#/components/schemas/SignatureCounter" }, "transaction_counter": { "$ref": "#/components/schemas/TransactionCounter" }, "number_registered_clients": { "$ref": "#/components/schemas/NumberRegisteredClients" }, "number_active_transactions": { "$ref": "#/components/schemas/NumberActiveTransactions" }, "time_uninit": { "$ref": "#/components/schemas/Timestamp" }, "time_init": { "$ref": "#/components/schemas/Timestamp" }, "time_defective": { "$ref": "#/components/schemas/Timestamp" }, "time_disable": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "state", "certificate", "serial_number", "public_key", "signature_algorithm", "signature_timestamp_format", "transaction_data_encoding", "max_number_registered_clients", "max_number_active_transactions", "supported_update_variants", "_id", "_type", "_env", "_version", "time_creation" ], "type": "object" } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "TSS not found", "content": { "application/json": { "schema": { "type": "object", "description": "TSS not found", "properties": { "code": { "type": "string", "example": "E_TSS_NOT_FOUND", "enum": ["E_TSS_NOT_FOUND"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } } } }, "patch": { "operationId": "updateTss", "summary": "Update a TSS", "tags": ["Technical Security System"], "description": "Only available via Middleware\n\nRequires Admin Authentication for state change to INITIALIZED and DISABLED\n\n\nWhen you create a TSS, its state is set to `\"CREATED\"`. \nAfter creating the TSS, you need to deploy it. Deploying the TSS means starting a new SMAERS process associated with it.\nTo deploy a TSS, set its state to `\"UNINITIALIZED\"`.\n\nThis 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! \n\nIf 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.\n\nAfter deploying the TSS, you need to initialize it. Only initialized TSS can process transactions.\nTo initialize the TSS, set its state to `\"INITIALIZED\"`.\nOnly when initializing a TSS, a `description` may be provided.\n\nIf you don't need the TSS anymore, you can disable it.\nTo disable the TSS, set its state to `\"DISABLED\"`.\nOnly the TSS in the states `\"UNINITIALIZED\"` or `\"INITIALIZED\"` can be disabled.\nDisabling a TSS is permanent and can't be undone.\n\nTSS `metadata` can be updated alongside state, or by providing the same state along with the new `metadata`.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/TssDescription" }, "state": { "type": "string", "enum": ["UNINITIALIZED", "INITIALIZED", "DISABLED"] }, "metadata": { "$ref": "#/components/schemas/MetadataRequest" } }, "required": ["state"], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns the updated TSS resource", "content": { "application/json": { "schema": { "type": "object", "description": "Returns the updated TSS resource", "properties": { "description": { "$ref": "#/components/schemas/TssDescription" }, "state": { "type": "string", "enum": ["UNINITIALIZED", "INITIALIZED", "DISABLED"] }, "certificate": { "$ref": "#/components/schemas/TssCertificate" }, "serial_number": { "$ref": "#/components/schemas/TssSerialNumber" }, "public_key": { "$ref": "#/components/schemas/TssPublicKey" }, "bsi_certification_id": { "type": "string", "description": "ID of the TSS certification issued by the German Federal Office for Information Security (BSI)" }, "signature_counter": { "$ref": "#/components/schemas/SignatureCounter" }, "signature_algorithm": { "$ref": "#/components/schemas/Algorithm" }, "signature_timestamp_format": { "$ref": "#/components/schemas/TimestampFormat" }, "transaction_counter": { "$ref": "#/components/schemas/TransactionCounter" }, "transaction_data_encoding": { "$ref": "#/components/schemas/DataEncoding" }, "number_registered_clients": { "$ref": "#/components/schemas/NumberRegisteredClients" }, "max_number_registered_clients": { "$ref": "#/components/schemas/MaxNumberRegisteredClients" }, "number_active_transactions": { "$ref": "#/components/schemas/NumberActiveTransactions" }, "max_number_active_transactions": { "$ref": "#/components/schemas/MaxNumberActiveTransactions" }, "supported_update_variants": { "$ref": "#/components/schemas/SupportedUpdateVariants" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_id": { "$ref": "#/components/schemas/Uuid" }, "_type": { "type": "string", "example": "TSS", "enum": ["TSS"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_creation": { "$ref": "#/components/schemas/Timestamp" }, "time_uninit": { "$ref": "#/components/schemas/Timestamp" }, "time_init": { "$ref": "#/components/schemas/Timestamp" }, "time_defective": { "$ref": "#/components/schemas/Timestamp" }, "time_disable": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "state", "time_creation", "certificate", "serial_number", "public_key", "signature_algorithm", "signature_timestamp_format", "transaction_data_encoding", "max_number_registered_clients", "max_number_active_transactions", "supported_update_variants", "_id", "_type", "_env", "_version", "time_uninit" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "description": "Bad Request", "properties": { "code": { "type": "string", "example": "E_ILLEGAL_TSS_STATE_CHANGE", "enum": ["E_ILLEGAL_TSS_STATE_CHANGE"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 400 }, "error": { "type": "string", "example": "Bad Request" } } } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "423": { "description": "Locked", "content": { "application/json": { "schema": { "type": "object", "description": "Locked", "properties": { "code": { "type": "string", "enum": [ "E_ADMIN_PIN_BLOCKED", "E_TSS_DEFECTIVE", "E_TSS_DELETED", "E_TSS_EVICTED" ], "example": "E_ADMIN_PIN_BLOCKED" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 423 }, "error": { "type": "string", "example": "Locked" } } } } } }, "432": { "description": "The requested resource is available only through the fiskaly sign Middleware", "content": { "application/json": { "schema": { "type": "object", "description": "The requested resource is available only through the fiskaly sign Middleware", "properties": { "code": { "type": "string", "example": "E_USE_MIDDLEWARE", "enum": ["E_USE_MIDDLEWARE"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 432 }, "error": { "type": "string" } } } } } }, "503": { "description": "The TSS resource is locked.", "content": { "application/json": { "schema": { "type": "object", "description": "The TSS resource is locked.", "properties": { "code": { "type": "string", "example": "E_TSS_LOCKED", "enum": ["E_TSS_LOCKED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 503 }, "error": { "type": "string", "example": "Service Unavailable" } } } } } } } } }, "/api/v2/tss/{tss_id}/admin": { "patch": { "operationId": "changeAdminPin", "summary": "Change or Unblock Admin PIN", "tags": ["Technical Security System"], "description": "Only available via Middleware\n\nThis endpoint allows the administrator to change or unblock their PIN.\nThe admin PIN is blocked and must be reset after the initial creation of a TSS and after five unsuccessful authentication attempts.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "admin_puk": { "$ref": "#/components/schemas/AdminPuk" }, "new_admin_pin": { "$ref": "#/components/schemas/AdminPin" } }, "required": ["admin_puk", "new_admin_pin"] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Admin PIN has been changed.", "content": { "application/json": { "schema": { "type": "object", "description": "Admin PIN has been changed." } } } }, "400": { "description": "Changing the Admin PIN failed", "content": { "application/json": { "schema": { "type": "object", "description": "Changing the Admin PIN failed", "properties": { "code": { "type": "string", "example": "E_CHANGE_ADMIN_PIN_FAILED", "enum": ["E_CHANGE_ADMIN_PIN_FAILED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 400 }, "error": { "type": "string", "example": "Bad Request" } } } } } }, "401": { "description": "Unauthorized Admin PIN change request", "content": { "application/json": { "schema": { "type": "object", "description": "Unauthorized Admin PIN change request", "properties": { "code": { "type": "string", "enum": ["E_UNAUTHORIZED", "E_ADMIN_LOGIN_FAILED"], "example": "E_UNAUTHORIZED" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 401 }, "error": { "type": "string", "example": "Unauthorized" } } } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "TSS not found", "content": { "application/json": { "schema": { "type": "object", "description": "TSS not found", "properties": { "code": { "type": "string", "example": "E_TSS_NOT_FOUND", "enum": ["E_TSS_NOT_FOUND"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } }, "423": { "description": "Locked", "content": { "application/json": { "schema": { "type": "object", "description": "Locked", "properties": { "code": { "type": "string", "enum": [ "E_TSS_DEFECTIVE", "E_TSS_DELETED", "E_TSS_EVICTED" ], "example": "E_TSS_DEFECTIVE" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 423 }, "error": { "type": "string", "example": "Locked" } } } } } }, "432": { "description": "The requested resource is available only through the fiskaly sign Middleware", "content": { "application/json": { "schema": { "type": "object", "description": "The requested resource is available only through the fiskaly sign Middleware", "properties": { "code": { "type": "string", "example": "E_USE_MIDDLEWARE", "enum": ["E_USE_MIDDLEWARE"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 432 }, "error": { "type": "string" } } } } } }, "503": { "description": "The TSS resource is locked.", "content": { "application/json": { "schema": { "type": "object", "description": "The TSS resource is locked.", "properties": { "code": { "type": "string", "example": "E_TSS_LOCKED", "enum": ["E_TSS_LOCKED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 503 }, "error": { "type": "string", "example": "Service Unavailable" } } } } } } } } }, "/api/v2/tss": { "get": { "operationId": "listTss", "summary": "List TSS", "tags": ["Technical Security System"], "description": "This endpoint lists all available TSS.", "parameters": [ { "schema": { "type": "string", "enum": [ "description", "state", "time_creation", "time_init", "time_disable" ] }, "in": "query", "name": "order_by", "required": false, "description": "Specifies the property to sort by" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "CREATED", "UNINITIALIZED", "INITIALIZED", "DISABLED", "DELETED", "DEFECTIVE", "EVICTED" ], "uniqueItems": true } }, "in": "query", "name": "states", "required": false, "description": "Filter to include only specific states of TSS \n\nExample: `states%5B0%5D=DISABLED&states%5B1%5D=INITIALIZED`" }, { "schema": { "type": "string", "enum": ["asc", "desc"], "default": "asc" }, "in": "query", "name": "order", "required": false, "description": "Determines the sorting order" }, { "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 100 }, "in": "query", "name": "limit", "required": false, "description": "Limits the number of returned results" }, { "schema": { "type": "integer", "default": 0, "minimum": 0 }, "in": "query", "name": "offset", "required": false, "description": "Skips the specified number of results from the result set" }, { "schema": { "type": "boolean", "enum": [false, true], "default": true }, "in": "query", "name": "show_deleted", "required": false, "description": "Set to `true` to include the resources of deleted TSS, set to `false` to hide them." } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns the TSS list", "content": { "application/json": { "schema": { "type": "object", "description": "Returns the TSS list", "properties": { "data": { "type": "array", "items": { "description": "Returns the TSS resource", "properties": { "certificate": { "$ref": "#/components/schemas/TssCertificate" }, "serial_number": { "$ref": "#/components/schemas/TssSerialNumber" }, "public_key": { "$ref": "#/components/schemas/TssPublicKey" }, "signature_algorithm": { "$ref": "#/components/schemas/Algorithm" }, "signature_timestamp_format": { "$ref": "#/components/schemas/TimestampFormat" }, "transaction_data_encoding": { "$ref": "#/components/schemas/DataEncoding" }, "max_number_registered_clients": { "$ref": "#/components/schemas/MaxNumberRegisteredClients" }, "max_number_active_transactions": { "$ref": "#/components/schemas/MaxNumberActiveTransactions" }, "supported_update_variants": { "$ref": "#/components/schemas/SupportedUpdateVariants" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_id": { "$ref": "#/components/schemas/Uuid" }, "_type": { "type": "string", "example": "TSS", "enum": ["TSS"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_creation": { "$ref": "#/components/schemas/Timestamp" }, "description": { "$ref": "#/components/schemas/TssDescription" }, "state": { "type": "string", "enum": [ "CREATED", "UNINITIALIZED", "INITIALIZED", "DISABLED", "DELETED", "DEFECTIVE", "EVICTED" ] }, "bsi_certification_id": { "type": "string", "description": "ID of the TSS certification issued by the German Federal Office for Information Security (BSI)" }, "signature_counter": { "$ref": "#/components/schemas/SignatureCounter" }, "transaction_counter": { "$ref": "#/components/schemas/TransactionCounter" }, "number_registered_clients": { "$ref": "#/components/schemas/NumberRegisteredClients" }, "number_active_transactions": { "$ref": "#/components/schemas/NumberActiveTransactions" }, "time_uninit": { "$ref": "#/components/schemas/Timestamp" }, "time_init": { "$ref": "#/components/schemas/Timestamp" }, "time_defective": { "$ref": "#/components/schemas/Timestamp" }, "time_disable": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "state", "certificate", "serial_number", "public_key", "signature_algorithm", "signature_timestamp_format", "transaction_data_encoding", "max_number_registered_clients", "max_number_active_transactions", "supported_update_variants", "_id", "_type", "_env", "_version", "time_creation" ], "type": "object" } }, "count": { "$ref": "#/components/schemas/Count" }, "_type": { "type": "string", "example": "TSS_LIST", "enum": ["TSS_LIST"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" } }, "required": ["data", "count", "_type", "_env", "_version"] } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } } } } }, "/api/v2/tss/{tss_id}/client/{client_id}": { "put": { "operationId": "createClient", "summary": "Create a client", "tags": ["Clients"], "description": "Only available via Middleware\n\nRequires Admin Authentication\n\nThis endpoint creates a new client and associates it with a TSS.\n\nThe state of a new client is automatically set to `\"REGISTERED\"`. \nOnly a client in a `\"REGISTERED\"` state can use the TSS. \n\nThe `client_id` must be a randomly generated UUIDv4. The `client_id` must stay unique throughout the system. \nYou cannot use the same `client_id` to create a client for a different TSS.\n\nThe `serial_number` is required by the SIGN DE API to be unique within each TSS.\nHowever, please be aware that [BSI TR-03153-1](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR03153/TR-03153-1_Version1-1-1.pdf?__blob=publicationFile&v=3) Chapter 9.3.1 requires the\nthe `serial_number` to be uniquely assigned to a single ERS within the context of each ERS manufacturer.\n\nPlease 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 (\"_\").\nFurther information on the DSFinV-K can be found on the [German Federal Central Tax Office website](https://www.bzst.de/DE/Unternehmen/Aussenpruefungen/DigitaleSchnittstelleFinV/digitaleschnittstellefinv_node.html#js-toc-entry2).\n\nBefore 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.\n\nAccording to DSFinV-K `serial_number` must not be longer than 70 characters.\n\nWARNING: Future major versions of SIGN DE API will strictly enforce UUIDv4 format requirements.\nVerifying that your \"client_id\" conforms to the UUIDv4 standard to ensure compatibility is recommended.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "serial_number": { "$ref": "#/components/schemas/ClientSerialNumber" }, "metadata": { "$ref": "#/components/schemas/MetadataRequest" } }, "required": ["serial_number"] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" }, { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "client_id", "required": true, "description": "Identifies a client by a self-generated [UUIDv4](https://datatracker.ietf.org/doc/html/rfc4122)" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns the created Client resource", "content": { "application/json": { "schema": { "type": "object", "description": "Returns the created Client resource", "properties": { "serial_number": { "$ref": "#/components/schemas/ClientSerialNumber" }, "state": { "type": "string", "enum": ["REGISTERED", "DEREGISTERED"], "description": "Defines the state of a Client in the TSS. Only registered clients are able to write transactions.", "example": "REGISTERED" }, "tss_id": { "$ref": "#/components/schemas/TssId" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_id": { "$ref": "#/components/schemas/ClientId" }, "_type": { "type": "string", "example": "CLIENT", "enum": ["CLIENT"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_creation": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "serial_number", "state", "tss_id", "_id", "_type", "_env", "_version", "time_creation" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "description": "Bad request", "properties": { "code": { "type": "string", "enum": [ "E_ILLEGAL_CLIENT_SERIAL", "E_TSS_DISABLED", "E_TSS_NOT_INITIALIZED" ], "example": "E_ILLEGAL_CLIENT_SERIAL" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 400 }, "error": { "type": "string", "example": "Bad Request" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "description": "Forbidden", "properties": { "code": { "type": "string", "enum": ["E_CLIENT_LIMIT_REACHED", "E_ACCESS_DENIED"], "example": "E_CLIENT_LIMIT_REACHED" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "TSS not found", "content": { "application/json": { "schema": { "type": "object", "description": "TSS not found", "properties": { "code": { "type": "string", "example": "E_TSS_NOT_FOUND", "enum": ["E_TSS_NOT_FOUND"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } }, "409": { "description": "Client or pending request for this client_id already exists in the system (client_id must be unique system-wide)", "content": { "application/json": { "schema": { "type": "object", "description": "Client or pending request for this client_id already exists in the system (client_id must be unique system-wide)", "properties": { "code": { "type": "string", "example": "E_CLIENT_CONFLICT", "enum": ["E_CLIENT_CONFLICT"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 409 }, "error": { "type": "string", "example": "Conflict" } } } } } }, "423": { "description": "Locked", "content": { "application/json": { "schema": { "type": "object", "description": "Locked", "properties": { "code": { "type": "string", "enum": [ "E_TSS_DEFECTIVE", "E_TSS_DELETED", "E_TSS_EVICTED" ], "example": "E_TSS_DEFECTIVE" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 423 }, "error": { "type": "string", "example": "Locked" } } } } } }, "432": { "description": "The requested resource is available only through the fiskaly sign Middleware", "content": { "application/json": { "schema": { "type": "object", "description": "The requested resource is available only through the fiskaly sign Middleware", "properties": { "code": { "type": "string", "example": "E_USE_MIDDLEWARE", "enum": ["E_USE_MIDDLEWARE"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 432 }, "error": { "type": "string" } } } } } }, "503": { "description": "The TSS resource is locked.", "content": { "application/json": { "schema": { "type": "object", "description": "The TSS resource is locked.", "properties": { "code": { "type": "string", "example": "E_TSS_LOCKED", "enum": ["E_TSS_LOCKED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 503 }, "error": { "type": "string", "example": "Service Unavailable" } } } } } } } }, "get": { "operationId": "retrieveClient", "summary": "Retrieve a client", "tags": ["Clients"], "description": "This endpoint retrieves information about a specific client.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" }, { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "client_id", "required": true, "description": "Identifies a client by a self-generated [UUIDv4](https://datatracker.ietf.org/doc/html/rfc4122)" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns the Client resource", "content": { "application/json": { "schema": { "type": "object", "description": "Returns the Client resource", "properties": { "serial_number": { "$ref": "#/components/schemas/ClientSerialNumber" }, "state": { "type": "string", "enum": ["REGISTERED", "DEREGISTERED"], "description": "Defines the state of a Client in the TSS. Only registered clients are able to write transactions.", "example": "REGISTERED" }, "tss_id": { "$ref": "#/components/schemas/TssId" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_id": { "$ref": "#/components/schemas/ClientId" }, "_type": { "type": "string", "example": "CLIENT", "enum": ["CLIENT"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_creation": { "$ref": "#/components/schemas/Timestamp" }, "time_update": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "serial_number", "state", "tss_id", "_id", "_type", "_env", "_version", "time_creation", "time_update" ] } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "description": "Resource does not exist", "properties": { "code": { "type": "string", "enum": ["E_TSS_NOT_FOUND", "E_CLIENT_NOT_FOUND"], "example": "E_TSS_NOT_FOUND" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } } } }, "patch": { "operationId": "updateClient", "summary": "Update a client", "tags": ["Clients"], "description": "Only available via Middleware\n\nRequires Admin Authentication\n\nUse this endpoint to update a client. \nOnly a client in a `\"REGISTERED\"` state can use the TSS. \n\n*Note*: This endpoint updates the existing metadata without overwriting it. When new metadata is provided, it is merged with the existing metadata.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": ["REGISTERED", "DEREGISTERED"], "description": "Defines the state of a Client in the TSS. Only registered clients are able to write transactions.", "example": "REGISTERED" }, "metadata": { "$ref": "#/components/schemas/MetadataRequest" } }, "required": ["state"] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" }, { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "client_id", "required": true, "description": "Identifies a client by a self-generated [UUIDv4](https://datatracker.ietf.org/doc/html/rfc4122)" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns the updated Client resource", "content": { "application/json": { "schema": { "type": "object", "description": "Returns the updated Client resource", "properties": { "serial_number": { "$ref": "#/components/schemas/ClientSerialNumber" }, "state": { "type": "string", "enum": ["REGISTERED", "DEREGISTERED"], "description": "Defines the state of a Client in the TSS. Only registered clients are able to write transactions.", "example": "REGISTERED" }, "tss_id": { "$ref": "#/components/schemas/TssId" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_id": { "$ref": "#/components/schemas/ClientId" }, "_type": { "type": "string", "example": "CLIENT", "enum": ["CLIENT"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_creation": { "$ref": "#/components/schemas/Timestamp" }, "time_update": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "serial_number", "state", "tss_id", "_id", "_type", "_env", "_version", "time_creation", "time_update" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "description": "Bad request", "properties": { "code": { "type": "string", "example": "E_TSS_DISABLED", "enum": ["E_TSS_DISABLED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 400 }, "error": { "type": "string", "example": "Bad Request" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "description": "Forbidden", "properties": { "code": { "type": "string", "enum": ["E_CLIENT_LIMIT_REACHED", "E_ACCESS_DENIED"], "example": "E_CLIENT_LIMIT_REACHED" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "description": "Resource does not exist", "properties": { "code": { "type": "string", "enum": ["E_TSS_NOT_FOUND", "E_CLIENT_NOT_FOUND"], "example": "E_TSS_NOT_FOUND" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } }, "423": { "description": "Locked", "content": { "application/json": { "schema": { "type": "object", "description": "Locked", "properties": { "code": { "type": "string", "enum": [ "E_TSS_DEFECTIVE", "E_TSS_DELETED", "E_TSS_EVICTED" ], "example": "E_TSS_DEFECTIVE" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 423 }, "error": { "type": "string", "example": "Locked" } } } } } }, "432": { "description": "The requested resource is available only through the fiskaly sign Middleware", "content": { "application/json": { "schema": { "type": "object", "description": "The requested resource is available only through the fiskaly sign Middleware", "properties": { "code": { "type": "string", "example": "E_USE_MIDDLEWARE", "enum": ["E_USE_MIDDLEWARE"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 432 }, "error": { "type": "string" } } } } } }, "503": { "description": "The TSS resource is locked.", "content": { "application/json": { "schema": { "type": "object", "description": "The TSS resource is locked.", "properties": { "code": { "type": "string", "example": "E_TSS_LOCKED", "enum": ["E_TSS_LOCKED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 503 }, "error": { "type": "string", "example": "Service Unavailable" } } } } } } } } }, "/api/v2/client": { "get": { "operationId": "listAllClients", "summary": "List all clients", "tags": ["Clients"], "description": "This endpoint lists the clients of all available TSS.", "parameters": [ { "schema": { "type": "string", "enum": ["serial_number", "time_creation"] }, "in": "query", "name": "order_by", "required": false, "description": "Specifies the property to sort by" }, { "schema": { "type": "string" }, "in": "query", "name": "serial_number", "required": false, "description": "Filter to return only specific clients" }, { "schema": { "type": "string", "enum": ["REGISTERED", "DEREGISTERED"], "example": "REGISTERED" }, "in": "query", "name": "state", "required": false, "description": "Defines the state of a Client in the TSS. Only registered clients are able to write transactions." }, { "schema": { "type": "string", "enum": ["asc", "desc"], "default": "asc" }, "in": "query", "name": "order", "required": false, "description": "Determines the sorting order" }, { "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 100 }, "in": "query", "name": "limit", "required": false, "description": "Limits the number of returned results" }, { "schema": { "type": "integer", "default": 0, "minimum": 0 }, "in": "query", "name": "offset", "required": false, "description": "Skips the specified number of results from the result set" }, { "schema": { "type": "boolean", "enum": [false, true], "default": true }, "in": "query", "name": "show_deleted", "required": false, "description": "Set to `true` to include the resources of deleted TSS, set to `false` to hide them." } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns the Clients list", "content": { "application/json": { "schema": { "type": "object", "description": "Returns the Clients list", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClientResponse" } }, "count": { "$ref": "#/components/schemas/Count" }, "_type": { "type": "string", "example": "CLIENT_LIST", "enum": ["CLIENT_LIST"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" } }, "required": ["data", "count", "_type", "_env", "_version"] } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "TSS not found", "content": { "application/json": { "schema": { "type": "object", "description": "TSS not found", "properties": { "code": { "type": "string", "example": "E_TSS_NOT_FOUND", "enum": ["E_TSS_NOT_FOUND"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } } } } }, "/api/v2/tss/{tss_id}/client": { "get": { "operationId": "listClients", "summary": "List clients of a TSS", "tags": ["Clients"], "description": "This endpoint lists the clients of a specific TSS.", "parameters": [ { "schema": { "type": "string", "enum": ["serial_number", "time_creation"] }, "in": "query", "name": "order_by", "required": false, "description": "Specifies the property to sort by" }, { "schema": { "type": "string" }, "in": "query", "name": "serial_number", "required": false, "description": "Filter to return only specific clients" }, { "schema": { "type": "string", "enum": ["REGISTERED", "DEREGISTERED"], "example": "REGISTERED" }, "in": "query", "name": "state", "required": false, "description": "Defines the state of a Client in the TSS. Only registered clients are able to write transactions." }, { "schema": { "type": "string", "enum": ["asc", "desc"], "default": "asc" }, "in": "query", "name": "order", "required": false, "description": "Determines the sorting order" }, { "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 100 }, "in": "query", "name": "limit", "required": false, "description": "Limits the number of returned results" }, { "schema": { "type": "integer", "default": 0, "minimum": 0 }, "in": "query", "name": "offset", "required": false, "description": "Skips the specified number of results from the result set" }, { "schema": { "type": "boolean", "enum": [false, true], "default": true }, "in": "query", "name": "show_deleted", "required": false, "description": "Set to `true` to include the resources of deleted TSS, set to `false` to hide them." }, { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns the Clients list", "content": { "application/json": { "schema": { "type": "object", "description": "Returns the Clients list", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClientResponse" } }, "count": { "$ref": "#/components/schemas/Count" }, "_type": { "type": "string", "example": "CLIENT_LIST", "enum": ["CLIENT_LIST"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" } }, "required": ["data", "count", "_type", "_env", "_version"] } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "TSS not found", "content": { "application/json": { "schema": { "type": "object", "description": "TSS not found", "properties": { "code": { "type": "string", "example": "E_TSS_NOT_FOUND", "enum": ["E_TSS_NOT_FOUND"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } } } } }, "/api/v2/tss/{tss_id}/client/{client_id}/tx": { "get": { "operationId": "listClientTransactions", "summary": "List transactions of a client", "tags": ["Clients"], "description": "This endpoint lists the transactions of a specific client.", "parameters": [ { "schema": { "type": "string", "enum": ["number", "state", "time_start", "time_end"] }, "in": "query", "name": "order_by", "required": false, "description": "Specifies the property to sort by" }, { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TxState" } }, "in": "query", "name": "states", "required": false, "description": "Filter to include only specific states \n\nExample: `states%5B0%5D=FINISHED&states%5B1%5D=CANCELLED`" }, { "schema": { "type": "string", "enum": ["asc", "desc"], "default": "asc" }, "in": "query", "name": "order", "required": false, "description": "Determines the sorting order" }, { "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 100 }, "in": "query", "name": "limit", "required": false, "description": "Limits the number of returned results" }, { "schema": { "type": "integer", "default": 0, "minimum": 0 }, "in": "query", "name": "offset", "required": false, "description": "Skips the specified number of results from the result set" }, { "schema": { "type": "boolean", "enum": [false, true], "default": true }, "in": "query", "name": "show_deleted", "required": false, "description": "Set to `true` to include the resources of deleted TSS, set to `false` to hide them." }, { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" }, { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "client_id", "required": true, "description": "Identifies a client by a self-generated [UUIDv4](https://datatracker.ietf.org/doc/html/rfc4122)" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns a list of transactions", "content": { "application/json": { "schema": { "type": "object", "description": "Returns a list of transactions", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TxResponse" } }, "count": { "$ref": "#/components/schemas/Count" }, "_type": { "type": "string", "example": "TRANSACTION_LIST", "enum": ["TRANSACTION_LIST"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" } }, "required": ["data", "count", "_type", "_env", "_version"] } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "description": "Resource does not exist", "properties": { "code": { "type": "string", "enum": [ "E_TSS_NOT_FOUND", "E_CLIENT_NOT_FOUND", "E_LATEST_TX_REVISION_NOT_FOUND" ], "example": "E_TSS_NOT_FOUND" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } } } } }, "/api/v2/tx": { "get": { "operationId": "listAllTransactions", "summary": "List all transactions", "tags": ["Transactions"], "description": "This endpoint lists the transactions of all available TSS.", "parameters": [ { "schema": { "type": "string", "enum": ["number", "state", "time_start", "time_end"] }, "in": "query", "name": "order_by", "required": false, "description": "Specifies the property to sort by" }, { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TxState" } }, "in": "query", "name": "states", "required": false, "description": "Filter to include only specific states \n\nExample: `states%5B0%5D=FINISHED&states%5B1%5D=CANCELLED`" }, { "schema": { "type": "string", "enum": ["asc", "desc"], "default": "asc" }, "in": "query", "name": "order", "required": false, "description": "Determines the sorting order" }, { "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 100 }, "in": "query", "name": "limit", "required": false, "description": "Limits the number of returned results" }, { "schema": { "type": "integer", "default": 0, "minimum": 0 }, "in": "query", "name": "offset", "required": false, "description": "Skips the specified number of results from the result set" }, { "schema": { "type": "boolean", "enum": [false, true], "default": true }, "in": "query", "name": "show_deleted", "required": false, "description": "Set to `true` to include the resources of deleted TSS, set to `false` to hide them." } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns a list of transactions", "content": { "application/json": { "schema": { "type": "object", "description": "Returns a list of transactions", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TxResponse" } }, "count": { "$ref": "#/components/schemas/Count" }, "_type": { "type": "string", "example": "TRANSACTION_LIST", "enum": ["TRANSACTION_LIST"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" } }, "required": ["data", "count", "_type", "_env", "_version"] } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "description": "Resource does not exist", "properties": { "code": { "type": "string", "enum": [ "E_TSS_NOT_FOUND", "E_CLIENT_NOT_FOUND", "E_LATEST_TX_REVISION_NOT_FOUND" ], "example": "E_TSS_NOT_FOUND" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } } } } }, "/api/v2/tss/{tss_id}/tx": { "get": { "operationId": "listTransactions", "summary": "List transactions of a TSS", "tags": ["Transactions"], "description": "This endpoint lists the transactions of a specific TSS.", "parameters": [ { "schema": { "type": "string", "enum": ["number", "state", "time_start", "time_end"] }, "in": "query", "name": "order_by", "required": false, "description": "Specifies the property to sort by" }, { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TxState" } }, "in": "query", "name": "states", "required": false, "description": "Filter to include only specific states \n\nExample: `states%5B0%5D=FINISHED&states%5B1%5D=CANCELLED`" }, { "schema": { "type": "string", "enum": ["asc", "desc"], "default": "asc" }, "in": "query", "name": "order", "required": false, "description": "Determines the sorting order" }, { "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 100 }, "in": "query", "name": "limit", "required": false, "description": "Limits the number of returned results" }, { "schema": { "type": "integer", "default": 0, "minimum": 0 }, "in": "query", "name": "offset", "required": false, "description": "Skips the specified number of results from the result set" }, { "schema": { "type": "boolean", "enum": [false, true], "default": true }, "in": "query", "name": "show_deleted", "required": false, "description": "Set to `true` to include the resources of deleted TSS, set to `false` to hide them." }, { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns a list of transactions", "content": { "application/json": { "schema": { "type": "object", "description": "Returns a list of transactions", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TxResponse" } }, "count": { "$ref": "#/components/schemas/Count" }, "_type": { "type": "string", "example": "TRANSACTION_LIST", "enum": ["TRANSACTION_LIST"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" } }, "required": ["data", "count", "_type", "_env", "_version"] } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "description": "Resource does not exist", "properties": { "code": { "type": "string", "enum": [ "E_TSS_NOT_FOUND", "E_CLIENT_NOT_FOUND", "E_LATEST_TX_REVISION_NOT_FOUND" ], "example": "E_TSS_NOT_FOUND" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } } } } }, "/api/v2/tss/{tss_id}/tx/{tx_id_or_number}": { "get": { "operationId": "retrieveTransaction", "summary": "Retrieve a transaction", "tags": ["Transactions"], "description": "This endpoint returns information about a specific transaction.\nThe transaction is identified by the `tx_id_or_number` path parameter.\nThis endpoint will return a specific revision of the transaction if the `tx_revision` query parameter is set.\nIf no revision is present in the query, the latest revision is returned.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "in": "query", "name": "tx_revision", "required": false }, { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" }, { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TxId" }, { "$ref": "#/components/schemas/TxNum" } ] }, "in": "path", "name": "tx_id_or_number", "required": true, "description": "Identifies a transaction by a `tx_id` (i.e. a self-generated [UUIDv4](https://datatracker.ietf.org/doc/html/rfc4122)) or a `tx_number` that gets assigned by us" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns the Transaction resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "$ref": "#/components/schemas/TxNum" }, "time_start": { "$ref": "#/components/schemas/Timestamp" }, "client_serial_number": { "$ref": "#/components/schemas/ClientSerialNumber" }, "tss_serial_number": { "$ref": "#/components/schemas/TssSerialNumber" }, "state": { "$ref": "#/components/schemas/TxState" }, "client_id": { "$ref": "#/components/schemas/ClientId" }, "schema": { "type": "object", "properties": { "standard_v1": { "$ref": "#/components/schemas/ProcessDataStandardV1" }, "dsfinvtw_v1": { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1Response" }, "raw": { "$ref": "#/components/schemas/ProcessDataRaw" } } }, "revision": { "$ref": "#/components/schemas/TxRevisionRetrieval" }, "latest_revision": { "$ref": "#/components/schemas/TxRevisionRetrieval" }, "tss_id": { "$ref": "#/components/schemas/TssId" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_type": { "type": "string", "example": "TRANSACTION", "enum": ["TRANSACTION"] }, "_id": { "$ref": "#/components/schemas/TxId" }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_end": { "$ref": "#/components/schemas/Timestamp" }, "qr_code_data": { "type": "string", "description": "Data of the QR Code according to Appendix I of [DSFinV-K](https://www.bzst.de/DE/Unternehmen/Aussenpruefungen/DigitaleSchnittstelleFinV/digitaleschnittstellefinv_node.html)", "example": "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": { "type": "object", "properties": { "operation": { "$ref": "#/components/schemas/TxLogOperationType" }, "timestamp": { "$ref": "#/components/schemas/Timestamp" }, "timestamp_format": { "$ref": "#/components/schemas/TimestampFormat" } }, "required": ["operation", "timestamp", "timestamp_format"] }, "signature": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/SignatureValue" }, "algorithm": { "$ref": "#/components/schemas/Algorithm" }, "counter": { "$ref": "#/components/schemas/BigintCounter" }, "public_key": { "$ref": "#/components/schemas/TssPublicKey" } }, "required": [ "value", "algorithm", "counter", "public_key" ] } }, "description": "Returns the Transaction resource", "required": [ "tss_id", "tss_serial_number", "client_id", "client_serial_number", "state", "revision", "latest_revision", "_type", "_id", "_env", "_version", "number", "time_start", "log", "signature" ] } } } }, "400": { "description": "Revision number does not exist", "content": { "application/json": { "schema": { "type": "object", "description": "Revision number does not exist", "properties": { "code": { "type": "string", "example": "E_TX_REVISION_NOT_FOUND", "enum": ["E_TX_REVISION_NOT_FOUND"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 400 }, "error": { "type": "string", "example": "Bad Request" } } } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "description": "Resource does not exist", "properties": { "code": { "type": "string", "enum": ["E_TSS_NOT_FOUND", "E_TX_NOT_FOUND"], "example": "E_TSS_NOT_FOUND" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } } } }, "put": { "operationId": "upsertTransaction", "summary": "Start, update or finish a transaction", "tags": ["Transactions"], "description": "Only available via Middleware\n\nUse this endpoint to change the state of a transaction. \n\nTo start a transaction, set the state field of the request body to `\"ACTIVE\"`.\nWhen you update the transaction, the state must also be set to `\"ACTIVE\"`.\n \nThere are two ways to end a transaction:\n1. If the transaction has finished as expected, set the state to `\"FINISHED\"`.\n2. If something went wrong and you want to cancel the transaction, set the state to `\"CANCELLED\"`. \n \nThe query string for this endpoint must include the `tx_revision` parameter . Set `tx_revision` to `1` when you start the transaction.\nAfter each call, the `tx_revision` must be incremented. Pass an incremented `tx_revision` in the query string for the next call.\n\nAll the data in the schema field of the request body must be UTF-8 encoded.\n\nWhen you start a transaction, the type and data of the transaction must be empty. This is required by the [DSFinV-K](https://www.bzst.de/DE/Unternehmen/Aussenpruefungen/DigitaleSchnittstelleFinV/digitaleschnittstellefinv_node.html) (v2.1).\n\n*Note*: A TSS is only allowed to have 2000 open (type= `\"ACTIVE\"`) transactions. \nIn case a TSS reaches this limit, you need to manually close (set to `\"CANCELLED\"` / `\"FINISHED\"`, depending on your process) the open transactions. \n\n*Note*: This endpoint updates the existing metadata without overwriting it. When new metadata is provided, it is merged with the existing metadata.\n\n*Note*: A transaction with the `dsfinvtw_v1` schema can be only be started and finished. Updates and cancelling are not possible.\n\n*Note*: For transaction UUID uniqueness requirements refer to the [transaction resource description](#section/Resources/Transaction) section.\n\nWARNING: Future major versions of SIGN DE API will strictly enforce UUIDv4 format requirements.\nIf a UUID is being used in \"tx_id_or_number\", verifying that it conforms to the UUIDv4 standard to ensure compatibility is recommended.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "$ref": "#/components/schemas/TxState" }, "client_id": { "$ref": "#/components/schemas/ClientId" }, "schema": { "$ref": "#/components/schemas/TxSchema" }, "metadata": { "$ref": "#/components/schemas/MetadataRequest" } }, "required": ["state", "client_id"] } } }, "required": true }, "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "in": "query", "name": "tx_revision", "required": false }, { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" }, { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TxId" }, { "$ref": "#/components/schemas/TxNum" } ] }, "in": "path", "name": "tx_id_or_number", "required": true, "description": "Identifies a transaction by a `tx_id` (i.e. a self-generated [UUIDv4](https://datatracker.ietf.org/doc/html/rfc4122)) or a `tx_number` that gets assigned by us" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns the Transaction resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "$ref": "#/components/schemas/TxNum" }, "time_start": { "$ref": "#/components/schemas/Timestamp" }, "client_serial_number": { "$ref": "#/components/schemas/ClientSerialNumber" }, "tss_serial_number": { "$ref": "#/components/schemas/TssSerialNumber" }, "state": { "$ref": "#/components/schemas/TxState" }, "client_id": { "$ref": "#/components/schemas/ClientId" }, "schema": { "type": "object", "properties": { "standard_v1": { "$ref": "#/components/schemas/ProcessDataStandardV1" }, "dsfinvtw_v1": { "$ref": "#/components/schemas/ProcessDataDSFinVTWV1Response" }, "raw": { "$ref": "#/components/schemas/ProcessDataRaw" } } }, "revision": { "$ref": "#/components/schemas/TxRevisionRetrieval" }, "latest_revision": { "$ref": "#/components/schemas/TxRevisionRetrieval" }, "tss_id": { "$ref": "#/components/schemas/TssId" }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "_type": { "type": "string", "example": "TRANSACTION", "enum": ["TRANSACTION"] }, "_id": { "$ref": "#/components/schemas/TxId" }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" }, "time_end": { "$ref": "#/components/schemas/Timestamp" }, "qr_code_data": { "type": "string", "description": "Data of the QR Code according to Appendix I of [DSFinV-K](https://www.bzst.de/DE/Unternehmen/Aussenpruefungen/DigitaleSchnittstelleFinV/digitaleschnittstellefinv_node.html)", "example": "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": { "type": "object", "properties": { "operation": { "$ref": "#/components/schemas/TxLogOperationType" }, "timestamp": { "$ref": "#/components/schemas/Timestamp" }, "timestamp_format": { "$ref": "#/components/schemas/TimestampFormat" } }, "required": ["operation", "timestamp", "timestamp_format"] }, "signature": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/SignatureValue" }, "algorithm": { "$ref": "#/components/schemas/Algorithm" }, "counter": { "$ref": "#/components/schemas/BigintCounter" }, "public_key": { "$ref": "#/components/schemas/TssPublicKey" } }, "required": [ "value", "algorithm", "counter", "public_key" ] } }, "description": "Returns the Transaction resource", "required": [ "tss_id", "tss_serial_number", "client_id", "client_serial_number", "state", "revision", "latest_revision", "_type", "_id", "_env", "_version", "number", "time_start", "log", "signature" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "description": "Bad Request", "properties": { "code": { "type": "string", "enum": [ "E_TX_UPSERT", "E_TSS_DISABLED", "E_TSS_NOT_INITIALIZED", "E_CLIENT_NOT_FOUND", "E_CLIENT_DEREGISTERED", "E_TX_LIMIT_REACHED" ], "example": "E_TX_UPSERT" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 400 }, "error": { "type": "string", "example": "Bad Request" } } } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "TSS not found", "content": { "application/json": { "schema": { "type": "object", "description": "TSS not found", "properties": { "code": { "type": "string", "example": "E_TSS_NOT_FOUND", "enum": ["E_TSS_NOT_FOUND"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } }, "409": { "description": "Illegal `process_type` or `process_type` change", "content": { "application/json": { "schema": { "type": "object", "description": "Illegal `process_type` or `process_type` change", "properties": { "code": { "type": "string", "enum": [ "E_TX_ILLEGAL_TYPE_CHANGE", "E_TX_NO_TYPE_DEFINED", "E_PENDING_TX_CONFLICT" ], "example": "E_TX_ILLEGAL_TYPE_CHANGE" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 409 }, "error": { "type": "string", "example": "Conflict" } } } } } }, "423": { "description": "Locked", "content": { "application/json": { "schema": { "type": "object", "description": "Locked", "properties": { "code": { "type": "string", "enum": [ "E_TSS_DEFECTIVE", "E_TSS_DELETED", "E_TSS_EVICTED" ], "example": "E_TSS_DEFECTIVE" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 423 }, "error": { "type": "string", "example": "Locked" } } } } } }, "432": { "description": "The requested resource is available only through the fiskaly sign Middleware", "content": { "application/json": { "schema": { "type": "object", "description": "The requested resource is available only through the fiskaly sign Middleware", "properties": { "code": { "type": "string", "example": "E_USE_MIDDLEWARE", "enum": ["E_USE_MIDDLEWARE"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 432 }, "error": { "type": "string" } } } } } }, "503": { "description": "The TSS resource is locked.", "content": { "application/json": { "schema": { "type": "object", "description": "The TSS resource is locked.", "properties": { "code": { "type": "string", "example": "E_TSS_LOCKED", "enum": ["E_TSS_LOCKED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 503 }, "error": { "type": "string", "example": "Service Unavailable" } } } } } } } } }, "/api/v2/tss/{tss_id}/tx/{tx_id_or_number}/log": { "get": { "operationId": "retrieveTransactionLog", "summary": "Retrieve a signed transaction log", "tags": ["Transactions"], "description": "This endpoint returns the log message of a specific transaction.\nThe transaction is identified by the `tx_id_or_number` path parameter.\nThis endpoint will return a specific revision of the transaction if the `tx_revision` query parameter is set.\nIf no revision is present in the query, the latest revision is returned.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "in": "query", "name": "tx_revision", "required": false }, { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" }, { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TxId" }, { "$ref": "#/components/schemas/TxNum" } ] }, "in": "path", "name": "tx_id_or_number", "required": true, "description": "Identifies a transaction by a `tx_id` (i.e. a self-generated [UUIDv4](https://datatracker.ietf.org/doc/html/rfc4122)) or a `tx_number` that gets assigned by us" } ], "deprecated": true, "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns a signed log message", "content": { "application/octet-stream": { "schema": { "type": "object", "description": "Returns a signed log message" } } } }, "400": { "description": "Revision number does not exist", "content": { "application/octet-stream": { "schema": { "type": "object", "description": "Revision number does not exist", "properties": { "code": { "type": "string", "example": "E_TX_REVISION_NOT_FOUND", "enum": ["E_TX_REVISION_NOT_FOUND"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 400 }, "error": { "type": "string", "example": "Bad Request" } } } } } }, "403": { "description": "You may not access this resource", "content": { "application/octet-stream": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "Resource does not exist", "content": { "application/octet-stream": { "schema": { "type": "object", "description": "Resource does not exist", "properties": { "code": { "type": "string", "enum": [ "E_TSS_NOT_FOUND", "E_TX_NOT_FOUND", "E_LOG_NOT_FOUND" ], "example": "E_TSS_NOT_FOUND" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } } } } }, "/api/v2/tss/{tss_id}/export/{export_id}": { "delete": { "operationId": "cancelExport", "summary": "Cancel an export", "tags": ["Data Exports"], "description": "This endpoint cancels an ongoing export operation.\n\nYou can cancel the export when it is in the states `\"PENDING\"` or `\"WORKING\"`.\nIf you run this endpoint before the export is complete, the export TAR file will not be generated.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" }, { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "export_id", "required": true, "description": "Identifies an Export" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns the export resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "$ref": "#/components/schemas/ExportState" }, "exception": { "$ref": "#/components/schemas/ExportException" }, "time_request": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Time of the initial request.", "example": 1577833200 }, "time_start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Time of the start of the export operation.", "example": 1577833200 }, "time_end": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Time of the end of the export operation.", "example": 1577833200 }, "time_expiration": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Time of the expiration of the generated TAR file.", "example": 1577833200 }, "time_error": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Time of the error of the export operation.", "example": 1577833200 }, "estimated_time_of_completion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Estimated point in time when the state will change to `COMPLETED`", "example": 1577833200 }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "tss_id": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000", "description": "Identifies a TSS" }, "_type": { "type": "string", "example": "EXPORT", "enum": ["EXPORT"] }, "_id": { "$ref": "#/components/schemas/ExportId" }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" } }, "required": [ "state", "time_request", "_type", "_id", "_env", "_version" ], "description": "Returns the export resource", "example": { "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" } } } } }, "400": { "description": "Bad request. A cancellation is only possible if the export is in state `\"PENDING\"` or `\"WORKING\"`", "content": { "application/json": { "schema": { "type": "object", "description": "Bad request. A cancellation is only possible if the export is in state `\"PENDING\"` or `\"WORKING\"`", "properties": { "code": { "type": "string", "example": "E_CANCEL_EXPORT", "enum": ["E_CANCEL_EXPORT"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 400 }, "error": { "type": "string", "example": "Bad Request" } } } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "description": "Resource does not exist", "properties": { "code": { "type": "string", "enum": ["E_TSS_NOT_FOUND", "E_EXPORT_NOT_FOUND"], "example": "E_TSS_NOT_FOUND" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } }, "423": { "description": "Locked", "content": { "application/json": { "schema": { "type": "object", "description": "Locked", "properties": { "code": { "type": "string", "enum": [ "E_TSS_DEFECTIVE", "E_TSS_DELETED", "E_TSS_EVICTED" ], "example": "E_TSS_DEFECTIVE" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 423 }, "error": { "type": "string", "example": "Locked" } } } } } } } }, "get": { "operationId": "retrieveExport", "summary": "Retrieve an export", "tags": ["Data Exports"], "description": "This endpoint returns the export resource.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" }, { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "export_id", "required": true, "description": "Identifies an Export" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns the export resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "$ref": "#/components/schemas/ExportState" }, "exception": { "$ref": "#/components/schemas/ExportException" }, "time_request": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Time of the initial request.", "example": 1577833200 }, "time_start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Time of the start of the export operation.", "example": 1577833200 }, "time_end": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Time of the end of the export operation.", "example": 1577833200 }, "time_expiration": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Time of the expiration of the generated TAR file.", "example": 1577833200 }, "time_error": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Time of the error of the export operation.", "example": 1577833200 }, "estimated_time_of_completion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Estimated point in time when the state will change to `COMPLETED`", "example": 1577833200 }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "tss_id": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000", "description": "Identifies a TSS" }, "_type": { "type": "string", "example": "EXPORT", "enum": ["EXPORT"] }, "_id": { "$ref": "#/components/schemas/ExportId" }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" } }, "required": [ "state", "time_request", "_type", "_id", "_env", "_version" ], "description": "Returns the export resource", "example": { "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" } } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "description": "Resource does not exist", "properties": { "code": { "type": "string", "enum": ["E_TSS_NOT_FOUND", "E_EXPORT_NOT_FOUND"], "example": "E_TSS_NOT_FOUND" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } } } }, "put": { "operationId": "triggerExport", "summary": "Trigger an export", "tags": ["Data Exports"], "description": "This endpoint triggers an export and returns a reference to the export resource.\n\nNote: The query parameter client_id is not meant to be used in combination with other query parameters.\n\nWARNING: triggering an export may interfere with the normal operations of the TSS. A large export can prevent the TSS from signing transaction data.\nTrigger exports when you don't need to sign transactions. For example, when doing a cash point closing.\n\nWARNING: 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.\n\nWARNING: 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.\n\nPlease pay attention so that the parameters `start_signature_counter` and `end_signature_counter` do not exceed the range defined in `maximum_number_records`. \nThe default setting for `maximum_number_records` is `1000000`, which is also the maximal allowed number.\n\nIf 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.\n\nE.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:\n1. First export with `end_signature_counter=1000000`\n2. Second export with `start_signature_counter=1000001` and `end_signature_counter=2000000`\n3. Third export with `start_signature_counter=2000001`\n\nWARNING: Future major versions of SIGN DE API will strictly enforce UUIDv4 format requirements.\nVerifying that your \"export_id\" conforms to the UUIDv4 standard to ensure compatibility is recommended.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "client_id", "required": false, "description": "Only return log messages associated with the given client (other query parameters will be ignored)." }, { "schema": { "type": "string", "pattern": "^\\d+$" }, "in": "query", "name": "transaction_number", "required": false, "description": "Only return log messages associated with the given transaction number." }, { "schema": { "type": "string", "pattern": "^\\d+$" }, "in": "query", "name": "start_transaction_number", "required": false, "description": "Only return log messages greater than or equal to the given start transaction number." }, { "schema": { "type": "string", "pattern": "^\\d+$" }, "in": "query", "name": "end_transaction_number", "required": false, "description": "Only return log messages less than or equal to the given end transaction number." }, { "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 1577833200 }, "in": "query", "name": "start_date", "required": false, "description": "Only return log messages with dates larger than or equal to the given start date." }, { "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 1577833200 }, "in": "query", "name": "end_date", "required": false, "description": "Only return log messages with dates smaller than or equal to the given start date." }, { "schema": { "type": "string", "pattern": "^\\d+$", "default": "1000000" }, "in": "query", "name": "maximum_number_records", "required": false, "description": "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. \n\nMinimal value is `\"1\"`. \n\nMaximal value is `\"1000000\"`." }, { "schema": { "type": "string", "pattern": "^\\d+$" }, "in": "query", "name": "start_signature_counter", "required": false, "description": "Only return log messages with signature counters larger than or equal to the given value." }, { "schema": { "type": "string", "pattern": "^\\d+$" }, "in": "query", "name": "end_signature_counter", "required": false, "description": "Only return log messages with signature counters smaller than or equal to the given value." }, { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" }, { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "export_id", "required": true, "description": "Identifies an Export" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns the export resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "$ref": "#/components/schemas/ExportState" }, "exception": { "$ref": "#/components/schemas/ExportException" }, "time_request": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Time of the initial request.", "example": 1577833200 }, "time_start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Time of the start of the export operation.", "example": 1577833200 }, "time_end": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Time of the end of the export operation.", "example": 1577833200 }, "time_expiration": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Time of the expiration of the generated TAR file.", "example": 1577833200 }, "time_error": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Time of the error of the export operation.", "example": 1577833200 }, "estimated_time_of_completion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Estimated point in time when the state will change to `COMPLETED`", "example": 1577833200 }, "metadata": { "$ref": "#/components/schemas/MetadataResponse" }, "tss_id": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000", "description": "Identifies a TSS" }, "_type": { "type": "string", "example": "EXPORT", "enum": ["EXPORT"] }, "_id": { "$ref": "#/components/schemas/ExportId" }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" } }, "required": [ "state", "time_request", "_type", "_id", "_env", "_version" ], "description": "Returns the export resource", "example": { "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" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "description": "Bad Request", "properties": { "code": { "type": "string", "enum": [ "E_DUPLICATE_EXPORT", "E_PARAMETER_MISMATCH", "E_CLIENT_NOT_FOUND", "E_TX_NOT_FOUND" ], "example": "E_DUPLICATE_EXPORT" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 400 }, "error": { "type": "string", "example": "Bad Request" } } } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "TSS not found", "content": { "application/json": { "schema": { "type": "object", "description": "TSS not found", "properties": { "code": { "type": "string", "example": "E_TSS_NOT_FOUND", "enum": ["E_TSS_NOT_FOUND"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "description": "Conflict", "properties": { "code": { "type": "string", "enum": [ "E_TSS_ILLEGAL_STATE_TO_PERFORM_EXPORT", "E_EXPORT_DUPLICATE_RATE_LIMITED", "E_TOO_MANY_EXPORTS" ], "example": "E_TSS_ILLEGAL_STATE_TO_PERFORM_EXPORT" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 409 }, "error": { "type": "string", "example": "Conflict" } } } } } }, "423": { "description": "Locked", "content": { "application/json": { "schema": { "type": "object", "description": "Locked", "properties": { "code": { "type": "string", "enum": [ "E_TSS_DEFECTIVE", "E_TSS_DELETED", "E_TSS_EVICTED", "E_EXPORT_FORBIDDEN" ], "example": "E_TSS_DEFECTIVE" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 423 }, "error": { "type": "string", "example": "Locked" } } } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "type": "object", "description": "Service Unavailable", "properties": { "code": { "type": "string", "enum": [ "E_EXPORT_TEMPORARILY_UNAVAILABLE", "E_TSS_LOCKED" ], "example": "E_EXPORT_TEMPORARILY_UNAVAILABLE" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 503 }, "error": { "type": "string", "example": "Service Unavailable" } } } } } } } } }, "/api/v2/export": { "get": { "operationId": "listAllExports", "summary": "List all exports", "tags": ["Data Exports"], "description": "This endpoint lists the exports of all available TSS.", "parameters": [ { "schema": { "type": "string", "enum": [ "state", "time_request", "time_start", "time_end", "time_expiration", "time_error" ] }, "in": "query", "name": "order_by", "required": false, "description": "Specifies the property to sort by" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "CANCELLED", "PENDING", "WORKING", "COMPLETED", "ERROR" ], "uniqueItems": true } }, "in": "query", "name": "states", "required": false, "description": "Filter to include only specific states \n\nExample: `states%5B0%5D=PENDING&states%5B1%5D=WORKING`" }, { "schema": { "type": "string", "enum": ["asc", "desc"], "default": "asc" }, "in": "query", "name": "order", "required": false, "description": "Determines the sorting order" }, { "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 100 }, "in": "query", "name": "limit", "required": false, "description": "Limits the number of returned results" }, { "schema": { "type": "integer", "default": 0, "minimum": 0 }, "in": "query", "name": "offset", "required": false, "description": "Skips the specified number of results from the result set" }, { "schema": { "type": "boolean", "enum": [false, true], "default": true }, "in": "query", "name": "show_deleted", "required": false, "description": "Set to `true` to include the resources of deleted TSS, set to `false` to hide them." } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns the Export list", "content": { "application/json": { "schema": { "type": "object", "description": "Returns the Export list", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExportResponse" } }, "count": { "$ref": "#/components/schemas/Count" }, "_type": { "type": "string", "example": "EXPORT_LIST", "enum": ["EXPORT_LIST"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" } }, "required": ["data", "count", "_type", "_env", "_version"] } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } } } } }, "/api/v2/tss/{tss_id}/export": { "get": { "operationId": "listExports", "summary": "List exports of a TSS", "tags": ["Data Exports"], "description": "This endpoint lists the exports of a specific TSS.", "parameters": [ { "schema": { "type": "string", "enum": [ "state", "time_request", "time_start", "time_end", "time_expiration", "time_error" ] }, "in": "query", "name": "order_by", "required": false, "description": "Specifies the property to sort by" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "CANCELLED", "PENDING", "WORKING", "COMPLETED", "ERROR" ], "uniqueItems": true } }, "in": "query", "name": "states", "required": false, "description": "Filter to include only specific states \n\nExample: `states%5B0%5D=PENDING&states%5B1%5D=WORKING`" }, { "schema": { "type": "string", "enum": ["asc", "desc"], "default": "asc" }, "in": "query", "name": "order", "required": false, "description": "Determines the sorting order" }, { "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 100 }, "in": "query", "name": "limit", "required": false, "description": "Limits the number of returned results" }, { "schema": { "type": "integer", "default": 0, "minimum": 0 }, "in": "query", "name": "offset", "required": false, "description": "Skips the specified number of results from the result set" }, { "schema": { "type": "boolean", "enum": [false, true], "default": true }, "in": "query", "name": "show_deleted", "required": false, "description": "Set to `true` to include the resources of deleted TSS, set to `false` to hide them." }, { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns the Export list", "content": { "application/json": { "schema": { "type": "object", "description": "Returns the Export list", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExportResponse" } }, "count": { "$ref": "#/components/schemas/Count" }, "_type": { "type": "string", "example": "EXPORT_LIST", "enum": ["EXPORT_LIST"] }, "_env": { "$ref": "#/components/schemas/Environment" }, "_version": { "$ref": "#/components/schemas/Version" } }, "required": ["data", "count", "_type", "_env", "_version"] } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "TSS not found", "content": { "application/json": { "schema": { "type": "object", "description": "TSS not found", "properties": { "code": { "type": "string", "example": "E_TSS_NOT_FOUND", "enum": ["E_TSS_NOT_FOUND"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } } } } }, "/api/v2/tss/{tss_id}/export/{export_id}/file": { "get": { "operationId": "retrieveExportFile", "summary": "Retrieve the TAR file generated by an export operation", "tags": ["Data Exports"], "description": "This endpoint returns the TAR file generated by the export operation.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" }, { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "export_id", "required": true, "description": "Identifies an Export" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "TAR file containing the exported data", "content": { "application/x-tar": { "schema": { "type": "object", "description": "TAR file containing the exported data" } } } }, "403": { "description": "You may not access this resource", "content": { "application/x-tar": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "Resource does not exist", "content": { "application/x-tar": { "schema": { "type": "object", "description": "Resource does not exist", "properties": { "code": { "type": "string", "enum": [ "E_TSS_NOT_FOUND", "E_EXPORT_NOT_FOUND", "E_EXPORT_NOT_COMPLETED" ], "example": "E_TSS_NOT_FOUND" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } } } } }, "/api/v2/tss/{tss_id}/client/{client_id}/metadata": { "get": { "operationId": "retrieveClientMetadata", "summary": "Retrieve metadata of a client", "tags": ["Clients"], "description": "This endpoint retrieves additional structured information about a client.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" }, { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "client_id", "required": true, "description": "Identifies a client by a self-generated [UUIDv4](https://datatracker.ietf.org/doc/html/rfc4122)" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns metadata", "content": { "application/json": { "schema": { "type": "object", "example": { "my_property_1": "1234", "my_property_2": "https://my-internal-system/path/to/resource/1234" }, "maxProperties": 40, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Returns metadata" } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "description": "Resource does not exist", "properties": { "code": { "type": "string", "enum": ["E_TSS_NOT_FOUND", "E_CLIENT_NOT_FOUND"], "example": "E_TSS_NOT_FOUND" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } } } }, "patch": { "operationId": "updateClientMetadata", "summary": "Update metadata of a client", "tags": ["Clients"], "description": "This endpoint creates or updates additional structured information about a client.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "my_property_1": "1234", "my_property_2": "https://my-internal-system/path/to/resource/1234" }, "maxProperties": 40, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "You can use this parameter to attach custom key-value data to an object.\nMetadata is useful for storing additional, structured information on an object.\n*Note:* You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long." } } }, "description": "You can use this parameter to attach custom key-value data to an object.\nMetadata is useful for storing additional, structured information on an object.\n*Note:* You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long." }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" }, { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "client_id", "required": true, "description": "Identifies a client by a self-generated [UUIDv4](https://datatracker.ietf.org/doc/html/rfc4122)" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns metadata", "content": { "application/json": { "schema": { "type": "object", "example": { "my_property_1": "1234", "my_property_2": "https://my-internal-system/path/to/resource/1234" }, "maxProperties": 40, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Returns metadata" } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "description": "Resource does not exist", "properties": { "code": { "type": "string", "enum": ["E_TSS_NOT_FOUND", "E_CLIENT_NOT_FOUND"], "example": "E_TSS_NOT_FOUND" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } } } } }, "/api/v2/tss/{tss_id}/export/{export_id}/metadata": { "get": { "operationId": "retrieveExportMetadata", "summary": "Retrieve metadata of an export", "tags": ["Data Exports"], "description": "This endpoint retrieves additional structured information about an export.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" }, { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "export_id", "required": true, "description": "Identifies an Export" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns metadata", "content": { "application/json": { "schema": { "type": "object", "example": { "my_property_1": "1234", "my_property_2": "https://my-internal-system/path/to/resource/1234" }, "maxProperties": 40, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Returns metadata" } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "description": "Resource does not exist", "properties": { "code": { "type": "string", "enum": ["E_TSS_NOT_FOUND", "E_EXPORT_NOT_FOUND"], "example": "E_TSS_NOT_FOUND" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } } } }, "patch": { "operationId": "updateExportMetadata", "summary": "Update metadata of an export", "tags": ["Data Exports"], "description": "This endpoint creates or updates additional structured information about an export.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "my_property_1": "1234", "my_property_2": "https://my-internal-system/path/to/resource/1234" }, "maxProperties": 40, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "You can use this parameter to attach custom key-value data to an object.\nMetadata is useful for storing additional, structured information on an object.\n*Note:* You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long." } } }, "description": "You can use this parameter to attach custom key-value data to an object.\nMetadata is useful for storing additional, structured information on an object.\n*Note:* You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long." }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" }, { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "export_id", "required": true, "description": "Identifies an Export" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns metadata", "content": { "application/json": { "schema": { "type": "object", "example": { "my_property_1": "1234", "my_property_2": "https://my-internal-system/path/to/resource/1234" }, "maxProperties": 40, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Returns metadata" } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "description": "Resource does not exist", "properties": { "code": { "type": "string", "enum": ["E_TSS_NOT_FOUND", "E_EXPORT_NOT_FOUND"], "example": "E_TSS_NOT_FOUND" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } } } } }, "/api/v2/tss/{tss_id}/tx/{tx_id_or_number}/metadata": { "get": { "operationId": "retrieveTransactionMetadata", "summary": "Retrieve metadata of a transaction", "tags": ["Transactions"], "description": "This endpoint retrieves additional structured information about a transaction.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" }, { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TxId" }, { "$ref": "#/components/schemas/TxNum" } ] }, "in": "path", "name": "tx_id_or_number", "required": true, "description": "Identifies a transaction by a `tx_id` (i.e. a self-generated [UUIDv4](https://datatracker.ietf.org/doc/html/rfc4122)) or a `tx_number` that gets assigned by us" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns metadata", "content": { "application/json": { "schema": { "type": "object", "example": { "my_property_1": "1234", "my_property_2": "https://my-internal-system/path/to/resource/1234" }, "maxProperties": 40, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Returns metadata" } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "description": "Resource does not exist", "properties": { "code": { "type": "string", "enum": ["E_TSS_NOT_FOUND", "E_TX_NOT_FOUND"], "example": "E_TSS_NOT_FOUND" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } } } }, "patch": { "operationId": "updateTransactionMetadata", "summary": "Update metadata of a transaction", "tags": ["Transactions"], "description": "This endpoint creates or updates additional structured information about a transaction.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "my_property_1": "1234", "my_property_2": "https://my-internal-system/path/to/resource/1234" }, "maxProperties": 40, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "You can use this parameter to attach custom key-value data to an object.\nMetadata is useful for storing additional, structured information on an object.\n*Note:* You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long." } } }, "description": "You can use this parameter to attach custom key-value data to an object.\nMetadata is useful for storing additional, structured information on an object.\n*Note:* You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long." }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" }, { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TxId" }, { "$ref": "#/components/schemas/TxNum" } ] }, "in": "path", "name": "tx_id_or_number", "required": true, "description": "Identifies a transaction by a `tx_id` (i.e. a self-generated [UUIDv4](https://datatracker.ietf.org/doc/html/rfc4122)) or a `tx_number` that gets assigned by us" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns metadata", "content": { "application/json": { "schema": { "type": "object", "example": { "my_property_1": "1234", "my_property_2": "https://my-internal-system/path/to/resource/1234" }, "maxProperties": 40, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Returns metadata" } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "description": "Resource does not exist", "properties": { "code": { "type": "string", "enum": ["E_TSS_NOT_FOUND", "E_TX_NOT_FOUND"], "example": "E_TSS_NOT_FOUND" }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } } } } }, "/api/v2/tss/{tss_id}/metadata": { "get": { "operationId": "retrieveTssMetadata", "summary": "Retrieve metadata of a TSS", "tags": ["Technical Security System"], "description": "This endpoint retrieves additional structured information about a TSS.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns metadata", "content": { "application/json": { "schema": { "type": "object", "example": { "my_property_1": "1234", "my_property_2": "https://my-internal-system/path/to/resource/1234" }, "maxProperties": 40, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Returns metadata" } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "TSS not found", "content": { "application/json": { "schema": { "type": "object", "description": "TSS not found", "properties": { "code": { "type": "string", "example": "E_TSS_NOT_FOUND", "enum": ["E_TSS_NOT_FOUND"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } } } }, "patch": { "operationId": "updateTssMetadata", "summary": "Update metadata of a TSS", "tags": ["Technical Security System"], "description": "This endpoint creates or updates additional structured information about a TSS.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "my_property_1": "1234", "my_property_2": "https://my-internal-system/path/to/resource/1234" }, "maxProperties": 40, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "You can use this parameter to attach custom key-value data to an object.\nMetadata is useful for storing additional, structured information on an object.\n*Note:* You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long." } } }, "description": "You can use this parameter to attach custom key-value data to an object.\nMetadata is useful for storing additional, structured information on an object.\n*Note:* You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long." }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000" }, "in": "path", "name": "tss_id", "required": true, "description": "Identifies a TSS" } ], "security": [{ "JWT": [] }], "responses": { "200": { "description": "Returns metadata", "content": { "application/json": { "schema": { "type": "object", "example": { "my_property_1": "1234", "my_property_2": "https://my-internal-system/path/to/resource/1234" }, "maxProperties": 40, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Returns metadata" } } } }, "403": { "description": "You may not access this resource", "content": { "application/json": { "schema": { "type": "object", "description": "You may not access this resource", "properties": { "code": { "type": "string", "example": "E_ACCESS_DENIED", "enum": ["E_ACCESS_DENIED"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "TSS not found", "content": { "application/json": { "schema": { "type": "object", "description": "TSS not found", "properties": { "code": { "type": "string", "example": "E_TSS_NOT_FOUND", "enum": ["E_TSS_NOT_FOUND"] }, "message": { "type": "string" }, "status_code": { "type": "number", "example": 404 }, "error": { "type": "string", "example": "Not Found" } } } } } } } } } }, "servers": [{ "url": "https://kassensichv-middleware.fiskaly.com" }], "security": [{ "JWT": [] }], "x-tagGroups": [ { "name": "Authentication", "tags": ["Authentication"] }, { "name": "Maintenance", "tags": [ "Technical Security System", "Clients", "Administration", "Complete Exports" ] }, { "name": "Input", "tags": ["Transactions"] }, { "name": "Exports", "tags": ["Data Exports"] } ] }