Skip to main content

DSFinV-K Endpoints

On this page, you get an overview of the most relevant DSFinV‑K endpoints, as well as optional endpoints.

Optional Endpoints​

Vat Definitions and Purchaser Agencies are described as “optional” as they are not relevant for most taxpayers. Most customers can directly start with the endpoint Insert or update a cash register.

Create or Update a Vat Definition (optional)​

The commonly used vat rates defined by law are provided via the API in the exact same order as in the DSFinV‑K Documents issued by the German Federal Central Tax Office (Bundeszentralamt für Steuern- BZSt), see Anlage 2 zur DSFinV‑K.

Some taxpayers may need to create additional Vat Definitions with vat_definition_export_id above 1000.

The additional individual Vat Definitions are to be defined for each Managed Organization and for the respective environment (LIVE or TEST). This means a Vat Definition created in a Managed Organization will only exist within this specific organization and in the environment it was defined for.

Create or Update a Purchaser Agency (optional)​

Purchaser Agencies are not required for every taxpayer. A Purchaser Agency is needed in case amounts are recorded on behalf of a third party (e.g. ‘shop-in-shop’).

For more information, please refer to the chapter Annex A Definitions of terms in the DSFinV‑K document issued by the German Federal Central Tax Office (Bundeszentralamt für Steuern- BZSt).

Insert or Update a Cash Register​

For every PoS device in use, you need to create a Cash Register. Cash Point Closings are done at the level of each individual Cash Register. Inserting a Cash Register is not part of daily operations, however, existing Cash Registers need to be updated in case of changes, for example software version updates on the PoS.

Master-Terminal Relationship in Cash Registers​

In most cases, the cash_register_type will be 'MASTER'. This type of Cash Register is considered as an individual recording system operating independently. It needs to be directly connected to a TSS (see Client in SIGN DE).

In particular scenarios, so-called Terminal Cash Registers are used in addition to the 'MASTER' Cash Register described above. Details on this Master-Terminal constellation are given in the DSFinV‑K document issued by the German Federal Central Tax Office (Bundeszentralamt für Steuern- BZSt) on page 39. The FAQs published by the German Federal Ministry of Finance might also be helpful (specifically no. 7 regarding handhelds in the section Anwendungsbereich).

Works independently in offline modeNeeds to be directly connected to a TSS
Master Cash RegisterYesYes
Terminal Cash RegisterNoNo

Insert a Cash Point Closing​

This endpoint is part of daily operations. A Cash Point Closing is a summary of all relevant processes - see Process (receipt) types & business transaction types - within a Cash Register (of type 'MASTER') for a specified timeframe. It should be created at least once a day, for example after closing the store.

From a technical perspective, some fields are marked as ‘required’ while others are not. However, this does not mean they can be left empty from a legal perspective. Whenever transactions have been performed on a particular day, the relevant data must be included in the Cash Point Closing in the transactions and cash_statement section.

The Structure of a Cash Point Closing​

A Cash Point Closing consists of 3 main parts:

  • Head: This section sets the scope of the Cash Point Closing by indicating the specific day and the range of transactions covered.

  • Cash Statement: This part is the aggregation of all transactions represented in two blocks:

    • business_cases includes the total payment flow at the cash register separated per business case.
    • payment_type includes the total payment flow at the cash register separated per payment type.

  • Transactions: This part includes detailed information about each individual transaction within the Cash Point Closing:

    • head contains essential information about the transaction.
    • data provides details of the transaction.
    • security creates the link to the TSS signature. If there is no corresponding TSS signature, an error message should be provided.

Trigger an Export​

Use this endpoint to trigger a DSFinV‑K Export including Cash Point Closings. Although it is also possible to trigger Exports via the fiskaly Dashboard, we recommend implementing this endpoint in a way that enables the taxpayer to get the Exports directly via your system.

You have two options to select which Cash Point Closings to include in the Export: ByCreationDate and ByBusinessDate. The creation date refers to the day the Cash Point Closings were submitted to the DSFinV‑K API. The business date refers to the day the Cash Point Closings are meant for.

You can choose TAR or ZIP as export formats. We recommend choosing the ZIP format, as it is supported by common validation tools.

Depending on the amount of data, generating the exports may take from a few seconds to an hour.

Directly Download an Export​

Once the Exports are completed, they can be downloaded via the endpoint Directly download an export in the format that was specified in the previous step.