Skip to content

Create or update a vat definition

fiskaly
API docs by Redocly

fiskaly DSFinV-K API (1.27.5)

Download OpenAPI specification:

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

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

Further information on the DSFinV-K can be found on the German Federal Central Tax Office website.

Introduction

The fiskaly DSFinV-K API is a RESTful API that takes a cash point closing and stores data to be later exported according to the DSFinV-K. The payload expected by the API closely resembles the DFKA Taxonomy 2.1.1, but links the data with entries from the KassenSichV and Management API.

Usage of the API Endpoints:

  • Masterdata such as VAT Definitions, Cash Registers and Purchaser Agencies should be submitted once whenever they change in the setup
  • The Cash Point Closing endpoint should be called with each cash point closing ("Kassenabschluss").
  • Exports can be triggered at any time

Background

To support international cash register manufacturers and providers, the tax authorities offer an English translation of the chapters that are most important for understanding. The tax authorities do not currently provide a complete translation of the DSFinV-K.

The translation of the individual chapters is exclusively an aid for non-German-speaking readers. Any deviations or differences that may occur in the translations of the official valid German version of the DSFinV-K are not binding and have no legal effect.

Versioning

Our API follows Semantic Versioning.

That means, given a version number MAJOR.MINOR.PATCH, we increment the:

  • MAJOR version when we make incompatible API changes,
  • MINOR version when we add functionality in a backwards-compatible manner, and
  • PATCH version when we make backwards-compatible bug fixes.

The current MAJOR version 1 is reflected in the APIs base URL: /api/v1.

Upcoming Changes

  • Announced with version 1.24.0:
    • Beginning with version 1.25.0 insertCashPointClosing cash_statement.payment.payment_types[] schema will be fixed to require at least 1 item. The release of version 1.25.0 is planned for calendar week 30.

Changelog

  • 1.27.5 (2025-12-03):
    • Fixed an edge case issue regarding cancelled exports.
  • 1.27.4 (2025-09-11):
    • Fixed edge case issues regarding failing exports.
  • 1.27.3 (2025-08-18):
    • Fixed edge case issues regarding failing Cash Point Closings.
  • 1.27.2 (2025-04-08):
    • Fixed edge case issues when using Purchaser Agent.
  • 1.27.1 (2025-01-27):
    • Updated VAT definition 3
    • Added historic VAT definition 43
  • 1.27.0 (2024-12-16):
    • Fixed misleading error object on a completed Cash Point Closing.
    • Fixed wrong reference date for certain edge cases.
  • 1.26.0 (2024-10-17):
    • Improve export processing engine
    • Fixed missing metadata when listing exports.
    • Fixed missing business_date when retrieving a Cash Point Closing.
  • 1.25.2 (2024-08-13):
    • Minor bug fixes in purchaser agency
  • 1.25.1 (2024-07-25):
    • Minor bug fix in schema validation
  • 1.25.0 (2024-07-24):
    • Improved API documentation
    • Fixed insertCashPointClosing.cash_statement.payment.payment_types[] schema to require at least 1 item
    • Disabled updating cash register types
    • Minor bug fixes
  • 1.24.0 (2024-06-27):
    • Updated postman collection
    • Minor bug fixes
    • Announced cash_statement.payment.payment_types schema fix to be released with v1.25.0
  • 1.23.0 (2024-05-02):
    • Added historic VAT ID 33
    • Minor bug fixes
  • 1.22.1 (2024-02-28):
    • Minor bug fix in export creation process
  • 1.22.0 (2024-01-30):
    • Added context on export error messages
    • Improved cash point closings error messages
    • Improved SLAVE_WITH_TSS cash register creation process
    • Improved transactions existence verification process
    • Fix client ID handling in certain edge cases
  • 1.21.0 (2024-01-10):
    • Fixed retrieving the first revision of a Cash Register when multiple revisions are available.
    • Fixed misleading fields when retrieving a Cash Point Closing in ERROR state.
    • Fixed misleading time fields when retrieving Exports.
    • Extended validity of vat definition 8.
  • 1.20.1 (2023-11-09):
    • Minor bug fix in export processing
  • 1.20.0 (2023-10-30):
    • Improved cash point closings processing
    • Improved exports processing
    • Improved parts of API documentation
    • Minor bug fixes
  • 1.19.1 (2023-08-28):
    • Fixed timestamp format of reports
    • Fixed potential issue with exports
  • 1.19.0 (2023-08-11):
    • Further improved export engine
    • Fixed insert cash point closing bug
    • Updated amounts per VAT description
    • Added list cash point closing reports endpoint
  • 1.18.1 (2023-06-14):
    • Fixed minor issues with the Export Engine and further improvements
  • 1.18.0 (2023-05-03):
    • Updated announcement of audit logs instead of a breaking change when amounts_per_vat_ids is missing on the root business_cases field in insertCashPointClosing
    • Improved documentation for certain fields with the insertCashPointClosing endpoint
    • Fixed edge case where TSE_ID might be wrong when a TSS has multiple clients
    • Fixed certain response errors that were marked as Internal Server Errors instead of Bad Requests
    • Fixed postman download links
Older entries
  • 1.17.0 (2023-03-29):
    • changed api specs from openapi v3.1.0 to openapi v3.0.3
    • Updated download export response type
    • Minor improvements
  • 1.16.0 (2023-03-08):
    • General improvements of our Export Engine
    • Improved exported binary fields
    • Fixed potential issue exporting VAT definitions
  • 1.15.0 (2023-02-15):
    • Resolved caveats of exporting cash point closings of multiple sources
    • Improved export engine error handling
    • Fixed exporting source_cash_register as terminals.
    • Fixed transaction lookup errors
  • 1.14.1 (2023-02-02):
    • Bug fix within exported csv files
  • 1.14.0 (2023-01-30):
    • Fixed problems for terminals that are linked to a SIGN DE master cash register and are being used in source_cash_register.
    • Fixed problems when using terminals of type SLAVE_WITH_TSS in closing_client_id.
  • 1.13.2 (2023-01-19):
    • Fixed a bug when triggering exports
  • 1.13.1 (2023-01-11):
    • Fixed a bug within schema validation
  • 1.13.0 (2023-01-10):
    • Further improved exports
    • Updated average vat definition
    • Clarified SLAVE_WITH_TSS object name
    • Fixed misleading default values in exports
    • Fixed response error on retrieving vat definition
    • Fixed schema validation for price_per_unit
    • Fixed integer limit
  • 1.12.2 (2023-01-02):
    • Minor bug fix
  • 1.12.1 (2022-12-29):
    • Added new predefined VAT definition 8 which is being available from 2023-01-01.
    • Further improved internal data handling for transactions.
    • Fixed invalid master_client_id response field for upsertCashRegister.
  • 1.12.0 (2022-12-20):
    • Improved amounts_per_vat_ids for line items.
    • Fixed missing fields in API documentation.
    • Fixed issue of amounts_per_vat_ids on business_cases in Cash Point Closings where only one would have been exported.
    • Fixed TSE_PUBLIC_KEY and TSE_TA_SIG field when exporting data from SIGN DE v0/v1.
  • 1.11.0 (2022-12-05):
    • Improved internal data handling for transactions.
    • Fixed specifying non-UUID tx_id for insertCashPointClosing transactions[].head.tx_id.
    • Fixed example request body for Cash Point Closings in Postman collection.
  • 1.10.1 (2022-10-25):
    • Fixed an issue with InterneTransaktion.
    • Fixed exporting TSS certificates from SIGN DE V1, making sure to only contain data in base64.
    • Fixed an issue with processing exports.
  • 1.10.0 (2022-10-13):
    • Improved API documentation.
    • Improved insertCashPointClosing, transactions[].head.tx_id and transactions[].lines[].item are now optional. Please be aware that tx_id is needed to create InterneTransaktion references.
    • Revised transactions[].head.tx_id no longer needs to be a UUID.
    • Added missing response error code on upsertCashRegister.
    • Fixed error for insertCashPointClosing when providing export_creation_date with milliseconds by setting its max value.
    • Fixed TSE_TA_ENDE in exports when no value was provided.
    • Fixed tax_number/vat_id_number for upsertPurchaserAgency. Only one of them needs to be provided.
  • 1.9.0 (2022-09-28):
    • Optimized Export Engine for a better throughput.
    • Optimized validation of payloads, throwing new E_INVALID_CHARSET error if an invalid charset was sent.
    • Improved API documentation, providing all possible error codes.
    • Added serial_number field for SLAVE_WITHOUT_TSS cash registers.
    • Fixed SLAVE_WITHOUT_TSS cash registers in exports.
    • Fixed exported TSE_TA_START and TSE_TA_ENDE fields and their format for non SIGN DE transactions.
    • Fixed potential server error on empty process_data of non SIGN DE transactions.
    • Fixed potential server error for upsertCashRegister.
    • Fixed retrieveCashPointClosingDetails endpoint for Cash Point Closings containing null values.
  • 1.8.1 (2022-09-08):
    • Fixed v0 root endpoint.
    • Async endpoints are now more resilient against short downtimes of internal services.
  • 1.8.0 (2022-09-01):
    • Revised fields buyer, user and closing_client_id which are now optional in a Cash Point Closings transactions[].head.
    • Improved overall health check of the API.
    • Fixed E_MULTIPLE_CASH_POINT_CLOSINGS_FOUND error which was erroneously returned when using references of type InterneTransaktion on line level.
    • Fixed Purchaser Agency revision handling when creating a Cash Point Closing.
  • 1.7.1 (2022-07-29):
    • Fixing error code when trying to create a Cash Point Closing of a SLAVE_* cash register.
  • 1.7.0 (2022-07-28):
    • Improved Insert a cash point closing, making it idempotent. Sending the same request again will send back the existing entity.
    • SLAVE_* cash registers no longer can create Cash Point Closings as it is defined in the DSFinV-K legal text.
    • Added predefined VAT definitions 1-999 (if available) for List all vat definitions and Retrieve a vat definition.
    • Added new _next field for all list endpoints, which contains the URL for the next page if more data is available.
    • Upgrading the specification to OpenAPI 3.1
  • 1.6.1 (2022-07-12):
    • Fixed InterneTransaktion when used within the same Cash Point Closing.
    • Fixed wrong sign_api_version when creating Cash Point Closings.
    • Fixed postman links.
    • Performance improvements for listing all Cash Point Closings.
  • 1.6.0 (2022-06-30):
    • Implements DSFinV-K 2.3 and DFKA taxonomy 2.3.
      Note: Some changes must be addressed when using the DSFinV-K. Please have a look at the DSFinV-K legal text for more information.
    • Added new format field for Trigger an Export making it possible to export Cash Point Closings into a ZIP instead of TAR.
    • Added new filters for Trigger an Export to export Cash Point Closings by their business_date (or export_creation_date as its fallback).
    • Added Guthabenkarte (with a lowercase k) to payment types.
    • Fixed exporting GuthabenKarte defined in the DFKA taxonomy and turning it into the corresponding Guthabenkarte as defined in DSFinV-K.
    • Fixed potential race condition when exporting Cash Point Closings.
    • Clarifying the date field of a Transaktion reference.
  • 1.5.0 (2022-06-14):
    • Revised InterneTransaktion references. It is now possible to also reference transactions of newly created Cash Point Closings which have no security.tss_tx_id set.
  • 1.4.0 (2022-05-20):
    • Making it possible to use non-fiskaly TSS with fiskaly DSFinV-K.
      We recommend to export Cash Point Closings separately for each client_id for now when using non-fiskaly TSS.
    • Added new historic VAT definitions.
    • Added missing TSE_ZERTIFIKAT_V to tse.csv.
    • Fixed a problem when using historic vat definitions.
    • Fixed an error when sending larger quantity_factor.
    • Fixed query parameters for listCashPointClosings.
    • Fixed problem when vat_definition_export_id is being reused in another environment.
  • 1.3.0 (2022-04-13):
    • Fixed missing error messages for Cash Point Closings
    • Fixed triggering exports with Cash Point Closings that were created before 2021-12-24.
      Note: Old exports in the TEST environments might get removed in the future. Please trigger a new export with the old Cash Point Closings in the TEST environment.
    • Fixed spelling.
  • 1.2.0 (2022-02-24):
    • Added order_by and order query parameters to the List all vat definitions endpoint.
    • Fixed a problem with Cash Point Closings that contained transactions that were not signed by the SIGN API.
    • Fixed number validation for big numbers.
  • 1.1.1 (2022-02-21):
    • Fixed a problem with creating exports of cash point closings with a specific client_id.
  • 1.1.0 (2022-02-17):
    • Increased performance of insertCashPointClosing.
    • Added possibility to filter results of listExports by business date.
    • Making transaction IDs case-insensitive for cash point closings.
    • Fixed duplicate API specs.
    • Fixed duplicate Cash Point Closings on the listCashPointClosings endpoint.
    • Fixed a problem when using multiple cash registers with multiple revisions.
    • Fixed a bug in the exported lines.csv.
  • 1.0.0 (2022-02-02):
    • Improved performance of exports.
      Update 2022-04-13: Exports that contain old Cash Point Closings created before 2021-12-24 can now be triggered.
      We currently process older exports that were created before 2021-12-24.
      Previous note: Cash Point Closings that were created before 2021-12-24 and would be included in an export will be postponed as that data is currently being migrated.
      We update this Changelog once older data was migrated.
    • Multiple bugfixes on various CSV files.
    • Fixed documented response types of list endpoints.
  • 0.14.0 (2021-12-06):
    • Improved description for exports and added a new cash_point_closings field in the response to show which are included.
    • Improved performance of Retrieve details of a cash point closing.
    • Added order_by and order for List all purchaser agencies endpoint.
    • Fixed multiple exported field values.
    • Fixed endpoints for retrieving metadata when no metadata is available.
  • 0.13.0 (2021-10-28):
  • 0.12.0 (2021-10-12):
    • Added new endpoint that allows to delete Cash Point Closings.
    • Fixed time_creation field to only show the actual creation timestamp of when a Cash Register was created.
  • 0.11.1 (2021-10-04):
    • Fixed Cash Registers that were created between 2021-08-11 and 2021-09-27. They can be used to create Cash Point Closings again. The old Cash Point Closings that ran into an ERROR need to be retriggered with a new closing_id.
  • 0.11.0 (2021-09-30):
    • Making sign_api_version obsolete in the request body. The field will be ignored if it is being used.
    • Marking sign_api_version as deprecated in the response.
    • Known issues
      • Cash Registers and Cash Point Closing which were created between 2021-08-11 and 2021-09-27 are currently not working. It will be fixed in the next couple of days.
      • Triggering Exports including Cash Point Closings with Cash Registers from multiple sign API versions will only export the sign API version 2. A possible workaround is to export Cash Registers from sign API v1 one by one. It will be fixed in a future version.
  • 0.10.0 (2021-09-27):
    • Extend API with sign_api_version fields to allow for a better integration with sign API v2.
    • Added order_by and order options for List all cash registers.
    • Fixed exports with sign API v2 entities.
    • Fixed creation of vat definitions with numbers in the specified range.
    • Fixed error code when triggering export with an already existing UUID.
    • Fixed missing csv files (references.csv, allocation_groups.csv, datapayment.csv).
    • Known issues
      • tse.csv might be missing in exports for sign_api_version=2.
  • 0.9.0 (2021-08-11):
    • Added Support for fiskaly sign API v2 for most enpoints.
    • Changed validation of country_code and currency definition.
    • Fixed multiple issues with exported CSV files.
  • 0.8.0 (2021-06-25):
    • Fixed TSE_SERIAL field in tse.csv.
    • Fixed UST_SCHLUESSEL field in business_cases.csv.
    • Fixed inserting Cash Point Closing with coupons.
    • Fixed count field on responses of list endpoints.
    • Performance improvements.
  • 0.7.0 (2021-05-20):
    • Translated documentation into English.
    • Fixed missing businesscases.csv in exports.
    • Fixed missing itemamounts.csv in exports.
    • Fixed missing subitems.csv in exports.
    • Fixed order of CSV columns in multiple exported files.
    • Fixed the use of historic vat definitions ("Historische Steuersätze") in a Cash Point Closing.
    • Fixed inconsistent revisions for Cash Registries.
    • Fixed response of upsertCashRegister to include the processing_flag and software field.
    • Wording improvements in the documentation.
  • 0.6.1 (2021-03-26):
  • 0.6.0 (2021-03-19):
    • Added linked dtd file to export.
    • Better error handling on invalid time formats.
    • Fixed MAX_PARAMETERS_EXCEEDED error for Cash Point Closings.
    • Fixed misleading E_CLIENT_NOT_FOUND error for Cash Point Closings.
    • Fixed input of incl_vat, excl_vat and vat and allowing up to 5 decimal places.
  • 0.5.1-alpha (2021-03-03):
    • Fixed Cash Point Closing requests that contains either an empty transaction list or only transactions that
      have the security.error_message set.
    • Fixed the client_id filter in listExports.
  • 0.5.0-alpha (2020-09-07):
    • Marked multiple required fields
    • Better error handling
  • 0.4.0-draft:
    • Cash Point Closing and Export implemented
    • Change Cash Point Closing retrieve response to match the insert response. This drastically reduces the response time.
    • Expose new Cash Point Closing details endpoint to be able to retrieve the whole Cash Point Closing.
    • Error response properties do now include the error code and message.
  • 0.3.0-draft:
    • Cash Point Closing insert endpoint is now asyncronous.
    • Use Vat Definition Export ID as key in schema.
  • 0.2.0-draft:
    • Schema adopted to include all required fields for export
    • Implements now DFKA taxonomy 2.1.1
    • All date-time fields are now unix timestamps
  • 0.1.0-draft:
    • Initial API draft.

Errors and Status Codes

Our API uses standard HTTP status codes to indicate the success or failure of requests:

Status 2xx

Status codes in the 200-299 range indicate success.

Status 4xx

Status codes in the 400-499 range indicate errors that have been caused by the client (e.g., a malformed request body has been sent).
Retrying such requests with the same request body is pointless and will result in the same status code again. Some 4xx errors can be handled programmatically may therefore include an additional error code like the following example:

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

Status 5xx

Status codes in the 500-599 range indicate errors on our side. Errors on our side can be considered temporary. This means that you may safely retry (see Idempotent Requests) the same request after a certain delay. We recommend an exponential backoff in your retry logic. Otherwise you might risk running into a 429 (Too Many Requests) error.

Request IDs

For each request, our API associates a unique request identifier to it. You will find this request identifier in the response headers, under X-Request-ID. If you need to contact us about a specific request (e.g. for debugging purposes) you have issued, please be sure to include the request identifier as this will greatly facilitate resolution on both sides.

Metadata

Another concept of our API is custom, user-defined metadata. Most resources in our API (e.g. Cash Register) include a metadata property, that can be used to attach and store additional, structured information such as resources.

For example, you could store a unique identifier for a particular cash register from your system on Cash Register object.

Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Revisions

For the defined master data resources, VAT Definition, Purchaser Agency, Cash Register, we provide a revision mechanic, to ensure historical data integrity. On every update (except metadata updates) of a given resource, we automatically create a new revision. This means, that the state of all master data resources on a future data export, is always equal to the state of the resource at the exact time of the insert of a cash point closing.

Note: You can retrieve a specific revision of a resource by providing the "revision" query param on the "Retrieve" methods.

IDs and Export IDs

All data in this API is referenced and uniquely identified by UUIDs. In the schema those are named "id". The IDs that are passed in from the source system (cash register) are named "export_id". Those IDs are not used for referencing, but ensure compliancy with DSFinV-K on the export side.

Make sure that your client_id is unique throughout all systems when using multiple sign API versions!
You can re-use the serial number but need to assign a new UUID.

Quick Start

For a quick first demo, you may use Postman. We prepared a Postman collection that allows you to step through the most important functions of this API.

  1. First of all, download the Postman application.

  2. Create an API key and API secret via the fiskaly dashboard (necessary for step 6).

  3. Download the Postman collection and the Postman environment.

  4. Start Postman and import the downloaded Postman collection and environment files.

File > Import (Ctrl+O)

  1. Select the imported environment.

  2. Use the created API key and API secret from step 2 to set api_key and api_secret in the environment files.

  3. Run the demo.

Run > Run fiskaly demo ...

Authentication

Our API uses JWT tokens to authenticate requests. API requests without authentication will fail. All API requests have to be made over HTTPS, while requests made over plain HTTP will fail.

If an /auth request using refresh_token fails in a 401 error, a regular /auth request with api_key and api_secret must be sent.

JWT

A JSON Web Token (JWT) used for access control and authorization.

API keys have to be obtained via the fiskaly dashboard.

  • Usage format: Bearer <JWT>
  • Example HTTP header: Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Security Scheme Type: HTTP
HTTP Authorization Scheme: bearer
Bearer format: JWT

Retrieve token

Access to our API is only granted with a valid JWT / authorization token that must be obtained using this endpoint.

Note: If you do not have an api_key yet, you have to create one yourself.

Authorizations:
None
Request Body schema: application/json
One of
api_key
required
string

Key of an API Key

api_secret
required
string

Secret of an API Key (only given, when POST request)

Responses

Request samples

Content type
application/json
{
  • "refresh_token": "string"
}

Response samples

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

VAT Definition

Definition of the turnover tax keys

The assignment of the sales tax keys used is defined within the taxonomy cash data in the master data. In the following overview, the keys are shown with a description and the currently and the currently valid VAT percentage rates. In the case of a change of the percentage rates, a new taxonomy version is not necessary. The adjustment can be made at any time after a cash at any time. The description can be adapted individually (e.g. descriptions that are also printed on the receipts). printed on the receipts).

ID percentage (VAT rate) description (description) /date of cash closure
1 Standard tax rate
2 Reduced tax rate
3 Average rate (§ 24 para. 1 no. 3 UStG) other cases
4 Average rate (§ 24 para. 1 no. 1 UStG)
5 0.00 % Non-taxable
6 0.00 % Exempt from VAT
7 0.00 % Non-taxable for turnover tax
8-10 Reserved for changes in taxonomy
11 19.00 % Historic general tax rate (§ 12 para. 1 UStG)
12 7.00 % Historic reduced tax rate (§ 12 para. 2 UStG)
13 10.70 % Historic average rate (§ 24 para. 1 no. 3 UStG) other cases
14 5.50 % Historic average rate (§ 24 para. 1 no. 1 UStG)
21 16.00 % Historic general tax rate (§ 12 para. 1 UStG)
22 5.00 % Historic reduced tax rate (§ 12 para. 2 UStG)
23 9.50 % Historic average rate (§ 24 para. 1 no. 3 UStG) other cases
33 9.00 % Historic average tax rate (§ 24 para. 1 no. 3 UStG)
43 8.40 % Historic average tax rate (§ 24 para. 1 no. 3 UStG)
up to 999 reserved for changes in taxonomy
from 1000 individual circumstances (old tax rates, § 13b UStG, or similar)

The API provides ID 1-7 automatically. Only IDs from 1000 can be added or changed via the API.

List all vat definitions

List all vat definitions according to DSFinV-K.

Authorizations:
JWT
query Parameters
order_by
string
Default: "time_creation"
Enum: "vat_definition_export_id" "time_creation" "time_update" "percentage"

Specifies the property to sort by

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

Determines the sorting order

limit
integer <= 100
Default: 100

Limits the number of returned results

offset
integer
Default: 0

Skips the specified number of results from the result set

Responses

Response samples

Content type
application/json
{}

Retrieve a vat definition

Retrieve a vat definition according to DSFinV-K.

Authorizations:
JWT
path Parameters
vat_definition_export_id
required
integer [ 1 .. 9999999999 ]

Fixed sales tax references are assigned here. Tax rates 1-7 are fixed, 8-999 are reserved, and 1000-99999999 are available for free use.

query Parameters
revision
number >= 0
Example: revision=0

Revision of the Masterdata

Responses

Response samples

Content type
application/json
{
  • "vat_definition_export_id": 1,
  • "percentage": 100,
  • "description": "string",
  • "metadata": {},
  • "revision": 0,
  • "time_creation": 1577833200,
  • "time_update": 1577833200,
  • "_type": "VAT_DEFINITION",
  • "_env": "TEST",
  • "_version": "1.27.5"
}

Create or update a vat definition

Create or update a vat definition according to DSFinV-K. You are only allowed to create or update vat definitions with vat_definition_export_id > 1000. For updates to those definitions we will create revisions.

Authorizations:
JWT
path Parameters
vat_definition_export_id
required
integer [ 1000 .. 9999999999 ]

Fixed sales tax references are assigned here. Tax rates 1-7 are fixed, 8-999 are reserved, and 1000-99999999 are available for free use.

Request Body schema: application/json
percentage
required
number decimal places <= 5 [ 0 .. 100 ]
description
string [ 1 .. 55 ] characters
object or null

You can use this parameter to attach custom key-value data to an object. Metadata is useful for storing additional, structured information on an object. Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "vat_definition_export_id": 1,
  • "percentage": 100,
  • "description": "string",
  • "metadata": {},
  • "revision": 0,
  • "time_creation": 1577833200,
  • "time_update": 1577833200,
  • "_type": "VAT_DEFINITION",
  • "_env": "TEST",
  • "_version": "1.27.5"
}

Create or update metadata of a vat definition

Create or update additional structured information about a vat definition.

Authorizations:
JWT
path Parameters
vat_definition_export_id
required
integer [ 1000 .. 9999999999 ]

Fixed sales tax references are assigned here. Tax rates 1-7 are fixed, 8-999 are reserved, and 1000-99999999 are available for free use.

Request Body schema: application/json

You can use this parameter to attach custom key-value data to an object. Metadata is useful for storing additional, structured information on an object. Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

property name*
additional property
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Retrieve metadata of a vat definition

Retrieve additional structured information about a vat definition.

Authorizations:
JWT
path Parameters
vat_definition_export_id
required
integer [ 1000 .. 9999999999 ]

Fixed sales tax references are assigned here. Tax rates 1-7 are fixed, 8-999 are reserved, and 1000-99999999 are available for free use.

Responses

Response samples

Content type
application/json
{}

Purchaser Agency

Agency information

There are companies that collect so-called agency revenues on behalf of third parties. This circumstance taxonomy takes this into account in that it is possible to define and reference several agencies for a cash register. and to reference them.

List all purchaser agencies

List all purchaser agencies according to DSFinV-K.

Authorizations:
JWT
query Parameters
client_id
string <uuid>
Example: client_id=00000000-0000-0000-0000-000000000000

The UUID of the SIGN DE client. If there is no corresponding SIGN DE client, it is user-definable.

order_by
string
Default: "time_creation"
Enum: "name" "time_creation" "time_update" "purchaser_agency_export_id"

Specifies the property to sort by

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

Determines the sorting order

limit
integer <= 100
Default: 100

Limits the number of returned results

offset
integer
Default: 0

Skips the specified number of results from the result set

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 9007199254740991,
  • "_type": "PURCHASER_AGENCIES",
  • "_env": "TEST",
  • "_version": "1.27.5",
  • "_next": "https://dsfinvk.fiskaly.com/api/v1/cash_registers?offset=10&limit=10"
}

Retrieve a purchaser agency

Retrieve a purchaser agency according to DSFinV-K.

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

The UUID of the purchasing agency.

query Parameters
revision
number >= 0
Example: revision=0

Revision of the Masterdata

Responses

Response samples

Content type
application/json
{
  • "purchaser_agency_id": "00000000-0000-0000-0000-000000000000",
  • "revision": 0,
  • "name": "string",
  • "address": {
    },
  • "purchaser_agency_export_id": 2147483647,
  • "client_id": "00000000-0000-0000-0000-000000000000",
  • "metadata": {},
  • "time_creation": 1577833200,
  • "time_update": 1577833200,
  • "_type": "PURCHASER_AGENCY",
  • "_env": "TEST",
  • "_version": "1.27.5",
  • "sign_api_version": 1,
  • "tax_number": "string",
  • "vat_id_number": "string"
}

Create or update a purchaser agency

Create or update a purchaser agency according to DSFinV-K.

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

The UUID of the purchasing agency.

Request Body schema: application/json
One of
name
required
string [ 1 .. 60 ] characters

Specify the current official (company) name here.

required
object
purchaser_agency_export_id
required
integer [ 0 .. 2147483647 ]

Referencing all agency purchaser data for agency sales to an ID is done at this location. Numbers 1 - 9999999999 are accepted for the ID. Only whole numbers are accepted. The order must be ascending in increments of 1.

client_id
required
string <uuid>

The client ID of the MASTER cash register or SLAVE cash register already created via upsertCashRegister endpoint.

object or null <= 20 properties

This parameter allows you to attach custom key value data to an object. Metadata is useful for storing additional, structured information about an object. Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

tax_number
required
string [ 1 .. 20 ] characters

Either the tax number (tax_number) or VAT number (vat_id_number) of the company must be specified (§ 14 para. 4 no. 2 UStG)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "address": {
    },
  • "purchaser_agency_export_id": 2147483647,
  • "client_id": "00000000-0000-0000-0000-000000000000",
  • "metadata": {},
  • "vat_id_number": "string"
}

Response samples

Content type
application/json
{
  • "purchaser_agency_id": "00000000-0000-0000-0000-000000000000",
  • "revision": 0,
  • "name": "string",
  • "address": {
    },
  • "purchaser_agency_export_id": 2147483647,
  • "client_id": "00000000-0000-0000-0000-000000000000",
  • "metadata": {},
  • "time_creation": 1577833200,
  • "time_update": 1577833200,
  • "_type": "PURCHASER_AGENCY",
  • "_env": "TEST",
  • "_version": "1.27.5",
  • "sign_api_version": 1,
  • "tax_number": "string",
  • "vat_id_number": "string"
}

Create or update metadata of a purchaser agency

Create or update additional structured information about a purchaser agency.

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

The UUID of the purchasing agency.

Request Body schema: application/json

You can use this parameter to attach custom key-value data to an object. Metadata is useful for storing additional, structured information on an object. Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

property name*
additional property
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Retrieve metadata of a purchaser agency

Retrieve additional structured information about a purchaser agency.

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

The UUID of the purchasing agency.

Responses

Response samples

Content type
application/json
{}

Cash Register

Cash register

A cash register is characterised by the ability to both electronically accept incoming orders and to complete the payment process electronically.

Master-slave relationship in cash registers

In many companies there are cash registers that both record business transactions and complete payment transactions. However, if individual cash registers (slaves) are closed via a central cash register (master), this is referred to as a master-slave cash register architecture. Purely digital ordering aids are not referred to as slave checkouts in this context. In this API, the master-slave relationship is established through the link to the corresponding client ID.

List all cash registers

Lists all cash registers.

Authorizations:
JWT
query Parameters
order_by
string
Default: "time_creation"
Enum: "cash_register_type" "time_creation" "time_update"

Specifies the property to sort by

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

Determines the sorting order

limit
integer <= 100
Default: 100

Limits the number of returned results

offset
integer
Default: 0

Skips the specified number of results from the result set

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 9007199254740991,
  • "_type": "CASH_REGISTERS",
  • "_env": "TEST",
  • "_version": "1.27.5",
  • "_next": "https://dsfinvk.fiskaly.com/api/v1/cash_registers?offset=10&limit=10"
}

Retrieve a cash register

Retrieve one cash register.

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

The client ID of the MASTER cash register or SLAVE cash register (terminal).

query Parameters
revision
number >= 0
Example: revision=0

Revision of the Masterdata

Responses

Response samples

Content type
application/json
{
  • "cash_register_type": "MASTER",
  • "client_id": "00000000-0000-0000-0000-000000000000",
  • "revision": 0,
  • "tss_id": "00000000-0000-0000-0000-000000000000",
  • "brand": "string",
  • "model": "string",
  • "software": {
    },
  • "base_currency_code": "str",
  • "processing_flags": {
    },
  • "master_client_id": "00000000-0000-0000-0000-000000000000",
  • "metadata": {},
  • "time_creation": 1577833200,
  • "time_update": 1577833200,
  • "_type": "CASH_REGISTER",
  • "_env": "TEST",
  • "_version": "1.27.5",
  • "sign_api_version": 1,
  • "serial_number": "fd00000aa8660b5b010006acdc",
  • "signature_algorithm": "SHA-256",
  • "signature_timestamp_format": "unixTime",
  • "transaction_data_encoding": "UTF-8",
  • "public_key": "MDN3TkJ8VSdcWDlLd0lfIjVhVjxXeFM7",
  • "certificate": "MDN3TkJ8VSdcWDlLd0lfIjVhVjxXeFM7"
}

Insert or update a cash register

Insert or update a cash register/slave when a client already exists.

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

The UUID of the SIGN DE client. If there is no corresponding SIGN DE client, it is user-definable.

Request Body schema: application/json

Request Body Schema to either insert CashRegisters or Slaves.

required
MasterCashRegisterSignDe (object) or MasterCashRegister (object) or TerminalCashRegister (object) or TerminalCashRegisterWithTss (object)
brand
required
string [ 1 .. 50 ] characters

Identifies the brand of the cash register manufacturer.

model
required
string [ 1 .. 50 ] characters

Describes the model of the particular cash register.

required
object or object
base_currency_code
required
string = 3 characters ^[A-Z]{3}$

Each cash statement has only one base currency. The base currency specification refers to the base currency of the cash register. The base currency is represented according to ISO 4217 (column: ISO code) Ex: Euro = EUR; All payments in foreign currency on the single document are converted to the base currency in the cash statement.

object

Enabling this field indicates that this cash register cannot make a sales tax assignment at the time the receivable is closed. If this setting is to be changed, it is mandatory to create a cash closing first. Thus, the sales tax assignment is made at the time of delivery and service in any case.

object or null <= 20 properties

This parameter allows you to attach custom key value data to an object. Metadata is useful for storing additional, structured information about an object. Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Responses

Request samples

Content type
application/json
{
  • "cash_register_type": {
    },
  • "brand": "string",
  • "model": "string",
  • "software": {
    },
  • "base_currency_code": "str",
  • "processing_flags": {
    },
  • "metadata": {}
}

Response samples

Content type
application/json
{
  • "cash_register_type": "MASTER",
  • "client_id": "00000000-0000-0000-0000-000000000000",
  • "revision": 0,
  • "tss_id": "00000000-0000-0000-0000-000000000000",
  • "brand": "string",
  • "model": "string",
  • "software": {
    },
  • "base_currency_code": "str",
  • "processing_flags": {
    },
  • "master_client_id": "00000000-0000-0000-0000-000000000000",
  • "metadata": {},
  • "time_creation": 1577833200,
  • "time_update": 1577833200,
  • "_type": "CASH_REGISTER",
  • "_env": "TEST",
  • "_version": "1.27.5",
  • "sign_api_version": 1,
  • "serial_number": "fd00000aa8660b5b010006acdc",
  • "signature_algorithm": "SHA-256",
  • "signature_timestamp_format": "unixTime",
  • "transaction_data_encoding": "UTF-8",
  • "public_key": "MDN3TkJ8VSdcWDlLd0lfIjVhVjxXeFM7",
  • "certificate": "MDN3TkJ8VSdcWDlLd0lfIjVhVjxXeFM7"
}

Create or update metadata of a cash register

Create or update additional structured information about a cash register.

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

The UUID of the SIGN DE client. If there is no corresponding SIGN DE client, it is user-definable.

Request Body schema: application/json

You can use this parameter to attach custom key-value data to an object. Metadata is useful for storing additional, structured information on an object. Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

property name*
additional property
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Retrieve metadata of a cash register

Retrieve additional structured information about a cash register.

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

The UUID of the SIGN DE client. If there is no corresponding SIGN DE client, it is user-definable.

Responses

Response samples

Content type
application/json
{}

Cash Point Closing

Cash closing

The cash point closing is the aggregating summary of a cash point of all individual movements (transactions) with the transaction type 'receipt' for a certain period of time. This means that only transactions are aggregated that are relevant for further processing for VAT and/or further processing for VAT and/or income tax purposes.

All amounts are displayed to two decimal places.

Objective of the cash balance statement

  • The cash balance statement provides the possibility to mathematically represent the counted cash balance of a cash register.
  • The cash balance statement provides an aggregated, systematised overview of the above-mentioned business transactions at the respective cash desk.

The cash statement is created once, several times or for all calendar days for a cash register.

List all cash point closings

List all cash point closings.

Authorizations:
JWT
query Parameters
client_id
string <uuid>
Example: client_id=00000000-0000-0000-0000-000000000000

The client ID of the MASTER cash register already created via upsertCashRegister endpoint.

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

A timestamp / point in time, measured in seconds since the Unix epoch

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

A timestamp / point in time, measured in seconds since the Unix epoch

Array of strings or string

Either states=PENDING or states=PENDING&states=WORKING

order_by
string
Default: "time_creation"
Enum: "time_creation" "state" "business_date"

Specifies the property to sort by

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

Determines the sorting order

limit
integer <= 100
Default: 100

Limits the number of returned results

offset
integer
Default: 0

Skips the specified number of results from the result set

business_date_start
string <date>

Filter for exports containing cash_point_closings with date >= business_date or if not defined export_creation_date in the format 'YYYY-MM-DD'.

business_date_end
string <date>

Filter for exports containing cash_point_closings with date <= business_date or if not defined export_creation_date in the format 'YYYY-MM-DD'.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 9007199254740991,
  • "_type": "CASH_POINT_CLOSING_LIST",
  • "_env": "TEST",
  • "_version": "1.27.5",
  • "_next": "https://dsfinvk.fiskaly.com/api/v1/cash_registers?offset=10&limit=10"
}

Retrieve a cash point closing

Retrieve one cash point closing.

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

ID of the cash point closing

Responses

Response samples

Content type
application/json
{
  • "closing_id": "00000000-0000-0000-0000-000000000000",
  • "cash_point_closing_export_id": 0,
  • "state": "PENDING",
  • "error": {
    },
  • "client_id": "00000000-0000-0000-0000-000000000000",
  • "business_date": "2019-08-24",
  • "first_transaction_export_id": "string",
  • "last_transaction_export_id": "string",
  • "export_creation_date": 1577833200,
  • "full_amount": -9999999999.99,
  • "cash_amount": -9999999999.99,
  • "metadata": {},
  • "time_creation": 1577833200,
  • "time_update": 1577833200,
  • "time_deleted": 1577833200,
  • "_type": "CASH_POINT_CLOSING",
  • "_env": "TEST",
  • "_version": "1.27.5",
  • "sign_api_version": 1,
  • "taxonomy_version": "1.27.5"
}

Insert a cash point closing

Insert a cash point closing according to DSFinV-K.

Attention: the processing of the data in this endpoint is asynchronous. The answer to a request will return partial data including a state field. This state field can have the following values: PENDING,WORKING,COMPLETED,CANCELLED,EXPIRED,DELETED,ERROR When sending a request to this endpoint, only the schema and base data will be validated and the initial state returned will be PENDING. In the background the data will be validated and persisted. Once processing has finished the state will be either COMPLETED if successful, or ERROR if not. In this case the field error will return the reason for the failure.

Attention: Only COMPLETED cash point closings will be considered for exports!

Notice: Requests should be sent in UTF-8 format

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

ID of the cash point closing

Request Body schema: application/json

The cash closing is created once, multiple times, or across calendar days for a cash register.

required
object

This bracket displays the central master data of the cash closing.

object

All transactions of a cash register are represented in the CashStatement. The cash statement of a cash register represents the business transactions in one block and the cash flows in a second block.

Array of objects

Forms the bracket around all individual transactions of a cash point closing.

client_id
required
string <uuid>

The client ID of the MASTER cash register already created via upsertCashRegister endpoint.

cash_point_closing_export_id
required
integer [ 0 .. 2147483647 ]

Each cash point closing has a 'Z_NR'. This number is ascending and consecutive per cash point closing within a cash register. It is not resettable.
Corresponds to 'Z_NR' of the official DSFinV-K documentation.

object or null <= 20 properties

This parameter allows you to attach custom key value data to an object. Metadata is useful for storing additional, structured information about an object. Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Responses

Request samples

Content type
application/json
{
  • "head": {
    },
  • "cash_statement": {
    },
  • "transactions": [
    ],
  • "client_id": "00000000-0000-0000-0000-000000000000",
  • "cash_point_closing_export_id": 2147483647,
  • "metadata": {}
}

Response samples

Content type
application/json
{
  • "closing_id": "00000000-0000-0000-0000-000000000000",
  • "cash_point_closing_export_id": 0,
  • "state": "PENDING",
  • "error": {
    },
  • "client_id": "00000000-0000-0000-0000-000000000000",
  • "business_date": "2019-08-24",
  • "first_transaction_export_id": "string",
  • "last_transaction_export_id": "string",
  • "export_creation_date": 1577833200,
  • "full_amount": -9999999999.99,
  • "cash_amount": -9999999999.99,
  • "metadata": {},
  • "time_creation": 1577833200,
  • "time_update": 1577833200,
  • "time_deleted": 1577833200,
  • "_type": "CASH_POINT_CLOSING",
  • "_env": "TEST",
  • "_version": "1.27.5",
  • "sign_api_version": 1,
  • "taxonomy_version": "1.27.5"
}

Delete a cash point closing

Delete a cash point closing. A cash point closing can only be deleted when in state PENDING, WORKING or COMPLETED.

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

ID of the cash point closing

Responses

Response samples

Content type
application/json
{
  • "closing_id": "00000000-0000-0000-0000-000000000000",
  • "cash_point_closing_export_id": 0,
  • "state": "PENDING",
  • "error": {
    },
  • "client_id": "00000000-0000-0000-0000-000000000000",
  • "business_date": "2019-08-24",
  • "first_transaction_export_id": "string",
  • "last_transaction_export_id": "string",
  • "export_creation_date": 1577833200,
  • "full_amount": -9999999999.99,
  • "cash_amount": -9999999999.99,
  • "metadata": {},
  • "time_creation": 1577833200,
  • "time_update": 1577833200,
  • "time_deleted": 1577833200,
  • "_type": "CASH_POINT_CLOSING",
  • "_env": "TEST",
  • "_version": "1.27.5",
  • "sign_api_version": 1,
  • "taxonomy_version": "1.27.5"
}

Retrieve details of a cash point closing

Retrieve details of one cash point closing.

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

ID of the cash point closing

Responses

Response samples

Content type
application/json
{
  • "cash_point_closing": {
    },
  • "state": "PENDING",
  • "error": {
    },
  • "time_creation": 1577833200,
  • "time_update": 1577833200,
  • "time_deleted": 1577833200,
  • "metadata": {},
  • "_id": "00000000-0000-0000-0000-000000000000",
  • "_type": "CASH_POINT_CLOSING",
  • "_env": "TEST",
  • "_version": "1.27.5",
  • "taxonomy_version": "1.27.5"
}

Create or update metadata of a cash point closing

Create or update additional structured information about a cash point closing.

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

ID of the cash point closing

Request Body schema: application/json

You can use this parameter to attach custom key-value data to an object. Metadata is useful for storing additional, structured information on an object. Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

property name*
additional property
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Retrieve metadata of a cash point closing

Retrieve additional structured information about a cash point closing.

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

ID of the cash point closing

Responses

Response samples

Content type
application/json
{}

Retrieve cash point closing reports

Retrieves cash point closing reports.

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

ID of the cash point closing

query Parameters
limit
integer
Default: 100
Example: limit=50

Number of reports to return.

offset
integer
Default: 0
Example: offset=20

Number of reports to skip.

order
string
Default: "DESC"
Enum: "ASC" "DESC"
Example: order=ASC

Ordering of the reports list.

Responses

Response samples

Content type
application/json
{}

Exports

This export will provide a set of csv files according to DSFinV-K standard to comply with financial regulations.

Endpoints for data export based on the Unified Digital Interface (Einheitliche Digitale Schnittstelle).

List all exports

List all exports.

Authorizations:
JWT
query Parameters
limit
integer <= 100
Default: 100

Limits the number of returned results

offset
integer
Default: 0

Skips the specified number of results from the result set

order_by
string
Default: "time_request"
Enum: "state" "time_request" "time_start" "time_completed" "time_error" "version"

Specifies the property to sort by

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

Determines the sorting order

Array of strings or string

Either states=PENDING or states=PENDING&states=WORKING

client_id
string <uuid>
Example: client_id=00000000-0000-0000-0000-000000000000

The client ID of the MASTER cash register already created via upsertCashRegister endpoint.

business_date_start
string <date>

Filter for exports containing cash_point_closings with date >= business_date or if not defined export_creation_date in the format 'YYYY-MM-DD'.

business_date_end
string <date>

Filter for exports containing cash_point_closings with date <= business_date or if not defined export_creation_date in the format 'YYYY-MM-DD'.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 9007199254740991,
  • "_type": "EXPORT_LIST",
  • "_env": "TEST",
  • "_version": "1.27.5",
  • "_next": "https://dsfinvk.fiskaly.com/api/v1/cash_registers?offset=10&limit=10"
}

Retrieve an export

Retrieve an export.

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

Identifies an Export

Responses

Response samples

Content type
application/json
{
  • "state": "PENDING",
  • "error": {
    },
  • "format": "zip",
  • "time_request": 1577833200,
  • "time_start": 1577833200,
  • "time_completed": 1577833200,
  • "time_expiration": 1577833200,
  • "time_error": 1577833200,
  • "cash_point_closings": [
    ],
  • "metadata": {},
  • "_type": "EXPORT",
  • "_id": "00000000-0000-0000-0000-000000000000",
  • "_env": "TEST",
  • "_version": "1.27.5",
  • "sign_api_version": 1
}

Trigger an export

Trigger an export.

Attention: the processing of the data in this endpoint is asyncronous. The answer to a request will return base export data including a state field. This state field can have the following values: PENDING,WORKING,COMPLETED,CANCELLED,EXPIRED,DELETED,ERROR When sending a request to this endpoint, only the schema and base data will be validated and the initial state returned will be PENDING. In the background the export will be performed. Once processing has finished the state will be either COMPLETED if successful, or ERROR if not. In this case the field error will return the reason for the failure.

Once successfully finished you can download the export with a separate call.

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

Identifies an Export

Request Body schema: application/json
One of
start_date
required
integer [ 0 .. 4102441199 ]

Only export cash point closings with time_creation larger than or equal to the given start date.

end_date
required
integer [ 0 .. 4102441199 ]

Only export cash point closings with time_creation smaller than or equal to the given end date.

format
string
Default: "tar"
Enum: "tar" "zip"

Format of the export archive

client_id
string <uuid>

The client ID of the MASTER cash register already created via upsertCashRegister endpoint.

object or null

You can use this parameter to attach custom key-value data to an object. Metadata is useful for storing additional, structured information on an object. Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Responses

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json
{
  • "state": "PENDING",
  • "error": {
    },
  • "format": "zip",
  • "time_request": 1577833200,
  • "time_start": 1577833200,
  • "time_completed": 1577833200,
  • "time_expiration": 1577833200,
  • "time_error": 1577833200,
  • "cash_point_closings": [
    ],
  • "metadata": {},
  • "_type": "EXPORT",
  • "_id": "00000000-0000-0000-0000-000000000000",
  • "_env": "TEST",
  • "_version": "1.27.5",
  • "sign_api_version": 1
}

Cancel an export

Cancel an export.

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

Identifies an Export

Responses

Response samples

Content type
application/json
{
  • "state": "PENDING",
  • "error": {
    },
  • "format": "zip",
  • "time_request": 1577833200,
  • "time_start": 1577833200,
  • "time_completed": 1577833200,
  • "time_expiration": 1577833200,
  • "time_error": 1577833200,
  • "cash_point_closings": [
    ],
  • "metadata": {},
  • "_type": "EXPORT",
  • "_id": "00000000-0000-0000-0000-000000000000",
  • "_env": "TEST",
  • "_version": "1.27.5",
  • "sign_api_version": 1
}

Create or update metadata of an export

Create or update additional structured information about an export.

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

Identifies an Export

Request Body schema: application/json

You can use this parameter to attach custom key-value data to an object. Metadata is useful for storing additional, structured information on an object. Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

property name*
additional property
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Retrieve metadata of an export

Retrieve additional structured information about an export.

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

Identifies an Export

Responses

Response samples

Content type
application/json
{}

Retrieve an export download url

Retrieve an export download url.

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

Identifies an Export

Responses

Response samples

Content type
application/json
{}

Directly download an export

Directly download an export tar file.

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

Identifies an Export

Responses

Response samples

Content type
application/json
{
  • "code": "E_FAILED_SCHEMA_VALIDATION",
  • "message": "Schema validation failed",
  • "status_code": 400,
  • "error": "Bad Request"
}

Was this page helpful?