Skip to content

Retrieve taxpayer information

API docs by Redocly

fiskaly SUBMIT DE (1.0.16)

Download OpenAPI specification:

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

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

Introduction

The fiskaly SUBMIT DE (formerly SIGN DE x Submission API) is a RESTful API that allows the management of taxpayer, establishment, client and submission information as relates to the requirements for submitting a declaration on the use of Electronic Record-keeping Systems/ERS (Elektronische Aufzeichnungssysteme/EAS in German) in § 146a (4) of the German Tax Code (AO) and section "1.16. Mitteilungspflicht nach § 146a Abs. 4 AO" of the corresponding application decree for the tax code (AEAO). The fiskaly SUBMIT DE supports the input and validation of all relevant information, the generation of the submission in the required XML format, and finally the transmission of the submission to the fiscal authorities.

Important notes

The declaration requirement (Mitteilungspflicht) under §146a (4) AO has entered into force nationwide in Germany on 1 January 2025, with a grace period until 31 July 2025. The declaration requirement affects digital cash registers as well as taximeters and odometers.

The fiskaly SUBMIT DE API has been developed as part of a joint pilot project together with the fiscal administration of the state of Hesse (Hessische Finanzverwaltung) and partners from industry.

Note: Integrators should consult the German Finance Ministry's (BMF) FAQ and the official data entry guide.

Ontology

The fiskaly SUBMIT DE is structured so as to represent the entities and relationships required for a declaration submission according to § 146a (4) AO.

UUIDv4

This API uses UUIDv4. Requests like UpsertEstablishment or CreateSubmission create new resources. To run such requests, generate a random UUIDv4, then put the UUIDv4 in the request path as indicated for each endpoint. This UUIDv4 will be assigned to the newly created resource.

A good way to generate a UUIDv4 is to use a library in your programming language of choice (like this) or an online generator (like this). Barring extremely unlikely collisions with already extant UUIDs (in which case requests will fail due to a lack of access rights), a UUIDv4 created this way will be random and unique throughout the system.

Using your system's id or a UUID bound to your hardware is a bad way to create a UUIDv4. If you use a UUID of your cash register as the client_id in UpsertExternalClient, 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 properties of your system.

Please note that the UUIDs of fiskaly resources are used only in the context of fiskaly APIs. Unless also used in the data fields provided for the respective resources, they will not be included in the submissions to the tax authorities.

Strings

There are general character restrictions that apply to all string values in this API.
Strings must comply with the following UTF-8 character set:

  • Printable ASCII characters
  • Currency characters: ¢, £, ¥, €
  • Special symbols: ¡, §, ©, ¬, ®, °, ±, µ, ², ³, ¹, , ·, «, », ¿
  • Extended Latin characters: Œ, œ, Š, š, Ÿ, Ž, ž

The allowed characters match the following regular expression pattern:

[\u0020-\u007E\u00A1-\u00A3\u00A5\u00A7\u00A9-\u00AC\u00AE-\u00B3\u00B5-\u00B7\u00B9-\u00BB\u00BF-\u00FF\u0152-\u0153\u0160-\u0161\u0178\u017D-\u017E\u20AC]+

Taxpayer

The taxpayer is a registered entity (a physical person or legal entity) identifiable via a specific tax number. A taxpayer owns a number of clients (ERS) that are present in a number of establishments and thus falls under the requirements of § 146a (4) AO. For each establishment, the taxpayer is obliged to create a different submission listing the clients located there.

In the fiskaly SUBMIT DE, the taxpayer is identified with the organization ID contained in the JWT used by the API clients. Each organization can thus manage a single taxpayer entity. If the organization you have set up in the fiskaly dashboard covers more than one taxpayers, please contact our support team (dev-support@fiskaly.com).

Note: In the fiskaly SUBMIT DE you have to provide the 13-digit unified federal tax number (Vereinheitlichtes Bundesschema zur elektronischen Übermittlung), as well as the unified federal tax office number (Bundesfinanzamt-Nummer), which is required for the final transmission. If the tax office number is not provided, the API will extract it from the first four digits of the tax number. Please make sure that these numbers are correctly provided to the API. Many taxpayers will not be aware of their 13-digit tax number, but only the 10-digit or 11-digit variant, depending on their federal state. Please use the BMF conversion tool to retrieve the 13-digit tax number. If you are uncertain to which tax office you are assigned, you can consult the tax office search tool.

Establishment

The establishment is a business premises where the taxpayer has located a number of clients. A taxpayer can own and operate a number of establishments. For each establishment, the taxpayer is obliged to create a different submission listing the clients present there. All clients present in the premises of an establishment, whether actively used or not, shall be included in the submission. Clients that leave the establishment (e.g. for repairs or to be moved to another of the taxpayer's establishments) or the taxpayer's ownership altogether (e.g. when they are irretrievably defective or sold to another taxpayer) shall be declared as decommissioned.

TSS

The use of a TSS (Technical Security System, Technische Sicherheitseinrichtung/TSE in German) is mandatory with all ERS in active use according to §146a (1) AO to ensure the fiscalization of the transactions registered in the ERS. Inactive ERS or those in storage are not obliged to be connected to a TSS, but this step must be done before they are taken into operation.

For fiskaly SIGN DE users, the fiskaly SUBMIT DE automatically retrieves all relevant data from the information provided in the SIGN DE API. No additional integration is required. For non-SIGN DE TSS, see below.

Client

A client is equivalent to an ERS in the context of §146a (4) AO. A taxpayer can own and operate a number of clients, spread out across a number of establishments, but no client can be shared by two or more establishments at the same time. For each establishment, the taxpayer is obliged to create a different submission listing the clients present there.

For fiskaly SIGN DE clients, the fiskaly SUBMIT DE retrieves part of the client data from the data provided in the SIGN DE API. The remainder of the data (additional data) required in the context of §146a (4) AO need to be input separately via this API. For non-SIGN DE clients, see below.

Non-SIGN DE users

The fiskaly SUBMIT DE allows the submission of ERS using non-SIGN DE TSS as external resources. This requires the input of all necessary information on the client via UpsertExternalClient, as well as on its associated TSS, via UpsertExternalTss.

Note: As the API was primarily conceived for the SIGN DE use case, all clients are assigned to a TSS, rather than vice versa. As a result, it is currently not possible to cover cases where an ERS is present in an establishment without being associated with a TSS (e.g. when a cash register is in storage).

Submission

A submission is the set of information about an establishment and the clients operated there by the respective taxpayer.

The submission file is an XML-formatted document generated by the fiskaly SUBMIT DE that can be downloaded by the taxpayer to be checked for correctness. A preview PDF is also provided as a human-readable alternative. The API can then transmit the submission to the fiscal authorities.

The stages of the submission generation process are reflected in the state of the submission resource in the API. These stages can be seen in a UML-like activity diagram here. Likewise, the stages of the transmission of a submission, once generated, including the possibility of cancelling a transmission, can be seen here.

Note: Integrators of the API that offer its functionality to their customers as a service must ensure that the latter (i.e. the actual taxpayers or entities authorized by them) have seen the submission XML file/preview PDF and explicitly verified the correctness of each generated submission before it is transmitted to the fiscal authorities.

The purpose of the declaration requirement is to provide the tax authorities with a timeline of changes to the ERS available in an establishment. It is therefore strongly recommended to transmit the submissions in a sequential, chronological order, reflecting each change or set of changes that are subject to mandatory declaration as they have occurred. Should a submission reflecting a specific state of an establishment fail, we recommend first retrying submitting this same state (e.g. via retry of a transmission), before submitting a more up-to-date state for the same establishment, so that changes are submitted in the correct order.

Errors and Status Codes

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 requesting application (e.g., a malformed request body has been sent). Retrying such requests with the same request body is pointless and will result in the same status code again. Some 4xx errors can be handled programmatically. The error response is in JSON format and is structured like this:

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

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

  • 401 Unauthorized
    • E_UNAUTHORIZED_ACCESS
      • Authenticate API
  • 403 Forbidden
    • E_ACCESS_FORBIDDEN
  • 404 Resource does not exist
    • E_ESTABLISHMENT_NOT_FOUND
    • E_TAXPAYER_NOT_FOUND
    • E_TAXPAYER_ADDRESS_NOT_FOUND
    • E_TAXPAYER_PERSON_NOT_FOUND
    • E_SUBMISSION_NOT_FOUND
    • E_CLIENT_NOT_FOUND
    • E_CLIENT_ADDITIONAL_DATA_NOT_FOUND
  • 409 Conflict
  • 423 Locked
    • E_LOCKED_RESOURCE

Examples

Some examples of various error responses are shown below. The content of the error message is unstructured and may contain information in different languages.

  • OpenAPI schema validation errors
{
  "code": "E_BAD_REQUEST",
  "error": "Bad Request",
  "message": "API request validation failed",
  "status": 400,
  "validation": {
    "message": "request body has an error: doesn't match schema #/components/schemas/ExternalTss: Error at \"/serial_number\": minimum string length is 64\nSchema:\n  {\n    \"description\": \"The serial number in hexadecimal numbers. Seriennummer der technischen Sicherheitseinrichtung\",\n    \"maxLength\": 64,\n    \"minLength\": 64,\n    \"pattern\": \"^[a-fA-F0-9]{64,64}$\",\n    \"type\": \"string\"\n  }\n\nValue:\n  \"255091809035200255529997861609352212430648220283133286655640727\"\n"
  }
}    

{
  "code": "E_BAD_REQUEST",
  "error": "Bad Request",
  "message": "API request validation failed",
  "status": 400,
  "validation": {
    "message": "request body has an error: doesn't match schema #/components/schemas/Taxpayer: Error at \"/tax_number\": maximum string length is 13\nSchema:\n  {\n    \"description\": \"Tax number. Please check the note on tax number [above](#section/Ontology/Taxpayer). Steuernummer. Bitte die Anmerkung zur Steuernummer [oben](#section/Ontology/Taxpayer) betrachten.\",\n    \"example\": \"1234012345678\",\n    \"maxLength\": 13,\n    \"minLength\": 13,\n    \"pattern\": \"^[0-9]{4}0[0-9]{8}$\",\n    \"type\": \"string\"\n  }\n\nValue:\n  \"91980113100100\"\n"
  }
}
  • Taxpayer validation errors
{
  "code": "E_BAD_REQUEST",
  "error": "Bad Request",
  "message": "bad request\ninvalid Taxpayer fields: \"vat_number\": Ungültige UStIDNr",
  "status": 400,
  "validation": {
    "message": "invalid Taxpayer fields: \"vat_number\": Ungültige UStIDNr"
  }
}

{
  "code": "E_BAD_REQUEST",
  "error": "Bad Request",
  "message": "bad request\ninvalid Taxpayer fields: \"identification_number\": Ungültige Identifikationsnummer.",
  "status": 400,
  "validation": {
    "message": "invalid Taxpayer fields: \"identification_number\": Ungültige Identifikationsnummer"
  }
}
  • Internal validation errors
{
  "code": "E_BAD_REQUEST",
  "error": "Bad Request",
  "message": "bad request\nvalidation failed: Code: zahlZuKlein\nMessage: Der im Feld 'Firmenname' eingegebene Wert muss größer oder gleich <MinWert> sein.",
  "status": 400,
  "validation": {
    "code": "zahlZuKlein",
    "message": "Der im Feld 'Firmenname' eingegebene Wert muss größer oder gleich <MinWert> sein."
  }
}

{
  "code": "E_BAD_REQUEST",
  "error": "Bad Request",
  "message": "bad request\nvalidation failed: Code: Aufz146a_067\nMessage: Sie haben bei der Art des Aufzeichnungssystems die Auswahl Taxameter oder Wegstreckenzähler getroffen. Im Feld Bemerkungen (zum eAufzeichnungssystem) muss das jeweilige Kfz-Kennzeichen des Fahrzeuges angegeben werden. Bitte ergänzen Sie ihre Angaben zum Feld Bemerkungen (eAufzeichnungssystem).",
  "status": 400,
  "validation": {
    "code": "Aufz146a_067",
    "message": "Sie haben bei der Art des Aufzeichnungssystems die Auswahl Taxameter oder Wegstreckenzähler getroffen. Im Feld Bemerkungen (zum eAufzeichnungssystem) muss das jeweilige Kfz-Kennzeichen des Fahrzeuges angegeben werden. Bitte ergänzen Sie ihre Angaben zum Feld Bemerkungen (eAufzeichnungssystem)."
  }
}

Status 5xx

Status codes in the 500-599 range indicate errors on the server side. These errors can be considered temporary.

Failed external validation error

The EXTERNAL_VALIDATION_FAILED status occurs when the submitted XML file passes internal validation but fails ERiC's plausibility checks. Upon failure, the error details are retrieved in the form of an XML file detailing the exact error. If no XML file is provided by ERiC, the error details can be found in the field error_description. SUBMIT DE does not provide an exhaustive list of possible errors, as the validation logic is determined by ERiC and subject to updates by the German tax authorities.

This example XML file represents a validation error example.

How to raise an issue

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

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

Quick Start

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

  1. Download and install the Postman application.

  2. Create an API key and API secret via the fiskaly dashboard. See the relevant point of the SIGN DE V2 API Quick Start section for details.

  3. Insert your API key and API secret below, and click the Download Postman environment button to get your personalized Postman environment:



  4. Download the Postman collection. This collection includes examples of using the different endpoints of the SUBMIT DE.

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

    File > Import... (Ctrl+O)

    postman import screen

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

    postman files selected

  7. After importing the collection and environment files, the Postman screen should look like this:

    postman screen after import

  8. Select the SUBMIT DE environment:

    postman select environment

  9. Finally, click on the SUBMIT DE collection, and run it by clicking on the Run collection button:

    postman run collection

Frequent questions regarding the usage of the fiskaly SUBMIT DE are covered in the Support FAQs.

Disclaimer

The example responses provided in this documentation are for illustrative purposes only. Actual API responses may vary, especially regarding dynamic fields like state.

Changes

Up-to-date information of the changes made to the fiskaly SUBMIT DE formatted in the change log format. These changes are also available, for subscription, in the following feed formats: RSS, Atom, and JSON.

Versioning

The fiskaly SUBMIT DE follows Semantic Versioning.

The version number has a pattern of MAJOR.MINOR.PATCH. We increment the

  • MAJOR version when we make incompatible API changes,

  • MINOR version when we add functionality in a backwards-compatible manner, and

  • PATCH version when we make backwards-compatible bug fixes.


    1.0.16 [2025-12-29] Release

    • Improved validation for BSI certification IDs.

    1.0.15 [2025-11-10] Release

    • The ERiC library is updated to the version 42.4.4.0.
    • New plausibility check on the BSI certificate ID (BSIID_Inhalt, Aufz146a_084): For BSI certification IDs with year numbers from 2019 to 2023, it is now checked whether the entered combination (NNNN-YYYY) corresponds to one of the assigned BSI certification IDs. BSI certification IDs with year numbers before 2019 or from 2024 onwards are accepted without further verification.
    • New validation rule: The combination of the recording system’s serial number (SeriennummerAS) and manufacturer (Hersteller) may only be specified once. If the same combination occurs multiple times, the following error message is displayed: "Die Angaben zu den elektronischen Aufzeichnungssystemen sind unplausibel. Die Kombination aus Seriennummer und Hersteller wurde mehrfach verwendet. Bitte prüfen Sie Ihre Eingaben."

    1.0.14 [2025-08-11] Release

    • The fiskaly SIGN DE x Submission API has been renamed to fiskaly SUBMIT DE. This is a naming change only and does not affect API functionality or endpoints.

    1.0.13 [2025-07-29] Release

    • The getSubmissionFile operation now supports an XmlHeader URL parameter. When set to true, this parameter will prepend the standard XML declaration (<?xml version="1.0" encoding="UTF-8" standalone="yes"?>) to the beginning of the XML file.

    1.0.12 [2025-07-14] Release

    • The getClientList operation has been updated to return submission-specific metadata only

    1.0.11 [2025-07-03] Release

    • The ERiC library is updated to the version 42.2.2.0.
    • The field legal_form was extended with new values in the operation upsertTaxpayer:
      • 30 - Eingetragene Genossenschaft (eG)
      • 38 - Gemeinnützige Gesellschaft mit beschränkter Haftung (gGmbH)
      • 40 - Stiftung & Co. KG
      • 52 - Eingetragener Verein

    1.0.10 [2025-06-13] Release


    1.0.9 [2025-05-27] Release

    • Failed requests may contain a validation section with the details on the cause of failure in the message property, and an optional code property.

    1.0.8 [2025-05-20] Release

    • Introduced the GetClientListPerOrgEnv endpoint to list active clients belonging to the caller's organization and environment.

    1.0.7 [2025-05-08] Release

    • Introduced client_origin query parameter for filtering clients in GetClientList endpoint.

    1.0.6 [2025-05-07] Release

    • Allow creating a Taxpayer in UpsertTaxpayer for different environments under the same organization.

    1.0.5 [2025-04-16] Release

    • The field date_commissioning in upsertExternalTss has been set to optional.
    • The field date_tss_commissioning in upsertExternalClient was added as an optional field. This date should reflect the commissioning date of the TSS on the given ERS (client). This is the recommended usage. If this field is not set, but a valid TSS commissioning date is provided, the TSS commissioning date will be used as a fallback.

    1.0.4 [2025-04-15] Release

    • Return E_CLIENT_NOT_FOUND in UpsertClientAdditionalData instead of creating additional client data when the client does not exist.

    1.0.3 [2025-03-05] Release

    • Made the tax_office_number field in upsertTaxpayer optional. It must be provided if not contained in the tax_number otherwise, it is inferred from the first 4 digits of the tax_number.

    1.0.2 [2025-03-03] Release

    • Enforced stricter strings validation. Input is now restricted to a defined UTF-8 character set, validated using a regex. The allowed characters and regex pattern are documented in the API specification under Strings section.

    1.0.1 [2025-01-22] Release

    • Corrected the behavior of UUID validations to be compatible with all UUIDs of SignDEv2 TSSes and Clients.

    1.0.0 [2025-01-01] Release

    • fiskaly SIGN DE x Submission API is now available in the LIVE environment.

    0.1.19 [2024-12-19] Release


    0.1.18 [2024-12-12] Release

    • Corrected the Postman collection regarding wrong location of field web_address.
    • Removed the value 6 (Sonstiges) from the list of possible values of the field type in the endpoints upsertExternalClient and upsertClientAdditionalData.
    • Removed the value 4 (Sonstiges) from the list of possible values of the field type in the endpoint the upsertExternalTss.
    • Corrected the remaining field in the getClientList endpoint.
    • New endpoint introduced to list external TSS instances: getExternalTssList

    0.1.17-preview [2024-11-29] Preview Release

    • Attention! This release introduces several breaking changes including the latest changes in the ERiC/ELSTER requirements. Please review the changes carefully and adjust your integration accordingly. This release is expected to be the last set of API changes before the LIVE phase of the SIGN DE x Submission API starting in January 2025.

    • The ERiC library is updated to the version 41.2.6.0.

    • The field data_transmitter is removed from the request body of the createSubmission endpoint.

    • The field type_other is removed from the request body of the upsertExternalClient and upsertClientAdditionalData endpoints.

    • The fields type_other, date_installation, date_expiration, manufacturer and bsi_certificate_valid_to are removed from the request body of the upsertExternalTss endpoint.

    • New required field legal_consent is added to the endpoint triggerTransmission. See the OpenAPI description for more information.

    • The length and pattern of the field serial_number in the request body of the upsertExternalTss endpoint are updated.

    • Transmission of the submission now requires the preview PDF to be downloaded and viewed beforehand, through the Download submission preview PDF endpoint. Download of the preview PDF will change the state of the submission from VALIDATION_SUCCEEDED to READY_FOR_TRANSMISSION.

    • The description of the field remarks in the request body of the upsertExternalClient and upsertClientAdditionalData endpoints is updated.

    • The operation getTaxpayer now returns stored metadata as expected.

    • Representation and rendering of the fields country, legal_form in the operation upsertTaxpayer in OpenAPI specification and on the documentation page are improved.

    • Representation and rendering of the field type in the operations upsertExternalClient and upsertExternalTss in OpenAPI specification and on the documentation page is improved.

    • Updated Postman collection reflects the latest changes in the API.


    0.1.16-preview [2024-06-03] Preview Release

    • Corrected error code 500 Internal Server Error to 400 Bad Request for endpoint UpsertExternalClient when the external TSS or the Establishment could not be found.
    • Corrected error code 500 Internal Server Error to 400 Bad Request for endpoint CreateSubmission when the Establishment could not be found.

    0.1.15-preview [2024-02-29] Preview Release

    • The pilot phase has ended on 2024-02-29

    0.1.14-preview [2024-02-19] Preview Release

    • The creation of the submission now requires the information of the 'Datenübermittler' defined explicitly for legal reasons. The required field data_transmitter was added to Create submission operation for this reason.

    0.1.13-preview [2024-01-23] Preview Release

    • Added time_transmitted to Submission to hold the time the submission was successfully transmitted to ERiC/ELSTER and recieved a non-error response.

    0.1.12-preview [2024-01-22] Preview Release

    • Added additional validation for the fields tax_number, vat_number and general_information.information.identification_number of the Taxpayer

    0.1.11-preview [2024-01-18] Preview Release

    • Fixed omitted elements ArtTSE and HerstellerTSE in the XML in case of fiskaly TSS

    0.1.10-preview [2024-01-12] Preview Release

    • Documentation updates
      • Added link to the fiskaly Support FAQs for the fiskaly SIGN DE x Submission API
      • Added activity diagram for the submission generation
      • Added activity diagram for the submission transmission

    0.1.9-preview [2024-01-08] Preview Release

    • Stability improvements.
    • post_address is required for CompanyAddress.

    0.1.8-preview [2024-01-05] Preview Release

    • Stability improvements.
    • Add informative response body in the case of validation errors.

    0.1.7-preview [2023-12-14] Preview Release

    • The field web_address (InternetAdresse) was moved from the address structure to the person structure.

    0.1.6-preview [2023-12-07] Preview Release

    • The field economic_id (Wirtschafts-Identifikationsnummer) was removed from the taxpayer structure as the ID is not yet being assigned

    0.1.5-preview [2023-12-06] Preview Release

    • The field economic_id was removed from the legal person
    • The field economic_id was added to the taxpayer
    • The ERiC library has been updated to the version 39.2.4

    0.1.4-preview [2023-11-29] Preview Release

    • Corrections to the required fields of client and TSS endpoints
      • model is required for external clients / SIGN DE client additional data
      • date_commissioning is required for external TSS
      • date_expiration is required for external TSS
      • date_installation is optional for external TSS
      • manufacturer is optional for external TSS
      • bsi_certificate_valid_to is optional for external TSS

    0.1.3-preview [2023-11-15] Preview Release

    • Postman collection 'SIGN DE x Submission API' has been added including external and SIGN DE scenarios

    0.1.2-preview [2023-11-09] Preview Release

    • The serial number of the non-fiskaly ('external') Client is required

    0.1.1-preview [2023-10-30] Preview Release

    • The tax payer now needs a mandatory tax office number to be set. For testing purposes 5192 can be used.
    • The pilot phase will only allow the tax offices Gießen (2620) and Wießbaden (2640) to send non-test submissions

    0.1.0-preview [2023-10-10] Preview Release

    • Initial pre-release of the API (changes still possible).
    • Management functions for all entities (Taxpayer, Establishment, Client, TSS) are provided.
    • Both fiskaly SIGN DE and non-fiskaly ('external') resources (TSS, Client) can be managed.
    • Submission statements can be created, validated, and transmitted to the ELSTER server.
    • API returns validation errors in XML format or the Submission data in XML and PDF format in case of successful validation.
    • All submissions will transmitted as test data at this stage.

Authentication

Authenticate API

To access our API, you need to have a valid JWT token. This endpoint creates the token with your api_key and api_secret. If you don't have an api_key, you can create one via the fiskaly dashboard. The api_secret will be generated for you after you create the api_key. The token must be sent with every following request in the Authorization header field using the Bearer authentication scheme. See details here. WARNING: even if you delete or otherwise deactivate your API credentials, any generated tokens will remain valid until they expire (currently up to 24 hours).

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

Key of an API Key

api_secret
required
string (ApiKeySecret)

Secret of an API Key (to be used only with POST requests)

Responses

Request samples

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

Response samples

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

Taxpayer

Retrieve taxpayer information

Returns the submitted information for a taxpayer

Authorizations:
JWT

Responses

Response samples

Content type
application/json
{
  • "general_information": {
    },
  • "metadata": {},
  • "tax_number": "1234012345678",
  • "tax_office_number": "5192",
  • "vat_number": "DE124356789",
  • "env": "TEST"
}

Create or update taxpayer

Creates or updates the information for a taxpayer

Authorizations:
JWT
Request Body schema: application/json
required
object (GeneralInformation)

General information about the company. AllgAngaben

object (Metadata) <= 20 properties

Arbitrary custom key-value data. 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.

tax_number
required
string (TaxNumber) = 13 characters ^[0-9]{4}0[0-9]{8}$

Tax number. Please check the note on tax number above. Steuernummer. Bitte die Anmerkung zur Steuernummer oben betrachten.

tax_office_number
string (TaxOfficeNumber) = 4 characters ^(10\d{2})|(11\d{2})|(21\d{2})|(22\d{2})|(23\...

Please provide also the tax office number if it is not contained in the tax number. Bitte Bundesfinanzamtsnummer separat angeben, wenn sie nicht in der Steuernummer vorkommt.

vat_number
string (VatNumber) = 11 characters ^DE[0-9]{9}$

VAT number. Umsatzsteuer-Identifikationsnummer

Responses

Request samples

Content type
application/json
{
  • "general_information": {
    },
  • "metadata": {},
  • "tax_number": "1234012345678",
  • "tax_office_number": "5192",
  • "vat_number": "DE124356789"
}

Response samples

Content type
application/json
{
  • "general_information": {
    },
  • "metadata": {},
  • "tax_number": "1234012345678",
  • "tax_office_number": "5192",
  • "vat_number": "DE124356789",
  • "env": "TEST"
}

Establishment

Retrieve establishments

Returns a list of establishments submitted by a taxpayer

Authorizations:
JWT
query Parameters
limit
integer (PaginationLimit) [ 1 .. 100 ]
Default: 10

Represents the pagination limit of the results set of a listing endpoint.

token
string (PaginationToken) <= 1024 characters ^(?:[A-Za-z0-9+\/]{4})*(?:[A-Za-z0-9+\/]{4}|[...

Represents the pagination token, which is used as an index pointer to the next page relative to the current page in Base64 encoding.

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "results": [
    ]
}

Delete establishment

Deletes information about a specific establishment

Authorizations:
JWT
path Parameters
establishment_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies an establishment.

Responses

Response samples

Content type
application/json
{
  • "code": "E_UNAUTHORIZED_ACCESS",
  • "error": "Unauthorized Access",
  • "message": "Not authorized to perform this operation.",
  • "status": 401,
  • "validation": {
    }
}

Retrieve establishment

Returns information about a specific establishment

Authorizations:
JWT
path Parameters
establishment_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies an establishment.

Responses

Response samples

Content type
application/json
{
  • "address": {
    },
  • "decommissioning_date": "01.12.2099",
  • "designation": "string",
  • "metadata": {},
  • "remarks": "string",
  • "env": "TEST",
  • "id": "01234567-89ab-49ab-b012-3456789abcde"
}

Create or update establishment

Updates information about a specific establishment

Authorizations:
JWT
path Parameters
establishment_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies an establishment.

Request Body schema: application/json
required
object

Address. Adresse

decommissioning_date
string^(0[1-9]|[1-2][0-9]|3[0-1])\.(0[1-9]|1[0-2])\...

Decommissioning of business premises. Außerbetriebnahme Betriebsstätte

designation
string [ 1 .. 200 ] characters

Designation of place of business. Bezeichnung Betriebsstätte

object (Metadata) <= 20 properties

Arbitrary custom key-value data. 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.

remarks
string [ 1 .. 1000 ] characters

Remarks. Bemerkungen

Responses

Request samples

Content type
application/json
{
  • "address": {
    },
  • "decommissioning_date": "01.12.2099",
  • "designation": "string",
  • "metadata": {},
  • "remarks": "string"
}

Response samples

Content type
application/json
{
  • "address": {
    },
  • "decommissioning_date": "01.12.2099",
  • "designation": "string",
  • "metadata": {},
  • "remarks": "string",
  • "env": "TEST",
  • "id": "01234567-89ab-49ab-b012-3456789abcde"
}

TSS

Retrieve list of external TSS instances

Retrieves list of stored information about the external TSS instances (i.e. a TSS instances from a manufacturer other than fiskaly).

Authorizations:
JWT
query Parameters
limit
integer (PaginationLimit) [ 1 .. 100 ]
Default: 10

Represents the pagination limit of the results set of a listing endpoint.

token
string (PaginationToken) <= 1024 characters ^(?:[A-Za-z0-9+\/]{4})*(?:[A-Za-z0-9+\/]{4}|[...

Represents the pagination token, which is used as an index pointer to the next page relative to the current page in Base64 encoding.

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "results": [
    ]
}

Deletes information about an external TSS

Deletes stored information about the external TSS (i.e. a TSS from a manufacturer other than fiskaly). The TSS can be deleted only if there are no active clients linked to it.

Authorizations:
JWT
path Parameters
tss_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies an external TSS.

Responses

Response samples

Content type
application/json
{
  • "code": "E_BAD_REQUEST",
  • "error": "Bad Request",
  • "message": "The request is invalid.",
  • "status": 400,
  • "validation": {
    }
}

Retrieve information about an external TSS

Retrieves stored information about the external TSS (i.e. a TSS from a manufacturer other than fiskaly).

Authorizations:
JWT
path Parameters
tss_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies an external TSS.

Responses

Response samples

Content type
application/json
{
  • "bsi_id": "stringstr",
  • "date_commissioning": "01.12.2099",
  • "metadata": {},
  • "serial_number": "stringstringstringstringstringstringstringstringstringstringstri",
  • "type": "1",
  • "env": "TEST",
  • "id": "01234567-89ab-49ab-b012-3456789abcde"
}

Create or update an external TSS

Store information about the external TSS (i.e. a TSS from a manufacturer other than fiskaly), that is relevant in the context of a submission according to "§146a (4) Abgabenordnung".

Authorizations:
JWT
path Parameters
tss_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies an external TSS.

Request Body schema: application/json
bsi_id
required
string = 9 characters ^\d{4}-\d{4}$

BSI Certificate ID (-), without the prefix BSI-K-TR-. BSI-Zertifizierungs-ID (-), ohne das Prefix BSI-K-TR-

date_commissioning
string^(0[1-9]|[1-2][0-9]|3[0-1])\.(0[1-9]|1[0-2])\...

Commissioning date of the TSS. Inbetriebnahme der technischen Sicherheitseinrichtung

object (Metadata) <= 20 properties

Arbitrary custom key-value data. 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.

serial_number
required
string = 64 characters ^[a-fA-F0-9]{64,64}$

The serial number in hexadecimal numbers. Seriennummer der technischen Sicherheitseinrichtung

type
required
string (Type of the TSS. Art / Bauform der technischen Sicherheitseinrichtung.)
Enum: "1" "2" "3"
  • 1 - SD-Karte
  • 2 - USB-Stick
  • 3 - Cloud

Responses

Request samples

Content type
application/json
{
  • "bsi_id": "stringstr",
  • "date_commissioning": "01.12.2099",
  • "metadata": {},
  • "serial_number": "stringstringstringstringstringstringstringstringstringstringstri",
  • "type": "1"
}

Response samples

Content type
application/json
{
  • "bsi_id": "stringstr",
  • "date_commissioning": "01.12.2099",
  • "metadata": {},
  • "serial_number": "stringstringstringstringstringstringstringstringstringstringstri",
  • "type": "1",
  • "env": "TEST",
  • "id": "01234567-89ab-49ab-b012-3456789abcde"
}

Client

Retrieve all clients

Returns a list of all clients (SIGN DE and external) assigned to the users's organization and environment.

Authorizations:
JWT
query Parameters
limit
integer (PaginationLimit) [ 1 .. 100 ]
Default: 10

Represents the pagination limit of the results set of a listing endpoint.

token
string (PaginationToken) <= 1024 characters ^(?:[A-Za-z0-9+\/]{4})*(?:[A-Za-z0-9+\/]{4}|[...

Represents the pagination token, which is used as an index pointer to the next page relative to the current page in Base64 encoding.

client_origin
string (ClientOrigin)
Enum: "sign-de" "external"

Filters clients by their origin.

  • sign-de: SIGN-DE clients.
  • external: External clients.

If omitted, all clients are returned.

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "results": [
    ]
}

Retrieve clients of an establishment

Returns a list of all clients (SIGN DE and external) assigned to an establishment.

Authorizations:
JWT
path Parameters
establishment_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies an establishment.

query Parameters
limit
integer (PaginationLimit) [ 1 .. 100 ]
Default: 10

Represents the pagination limit of the results set of a listing endpoint.

token
string (PaginationToken) <= 1024 characters ^(?:[A-Za-z0-9+\/]{4})*(?:[A-Za-z0-9+\/]{4}|[...

Represents the pagination token, which is used as an index pointer to the next page relative to the current page in Base64 encoding.

client_origin
string (ClientOrigin)
Enum: "sign-de" "external"

Filters clients by their origin.

  • sign-de: SIGN-DE clients.
  • external: External clients.

If omitted, all clients are returned.

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "results": [
    ]
}

Deletes information about an external client

Deletes external client entry. An external client is defined as one using a TSS from a manufacturer other than fiskaly.

Authorizations:
JWT
path Parameters
tss_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies an external TSS.

client_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies an external client (ERS).

Responses

Response samples

Content type
application/json
{
  • "code": "E_UNAUTHORIZED_ACCESS",
  • "error": "Unauthorized Access",
  • "message": "Not authorized to perform this operation.",
  • "status": 401,
  • "validation": {
    }
}

Retrieve stored information of an external client

Returns information about an external client (i.e. a client using a TSS from a manufacturer other than fiskaly) that is relevant in the context of a submission according to "§146a (4) Abgabenordnung".

Authorizations:
JWT
path Parameters
tss_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies an external TSS.

client_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies an external client (ERS).

Responses

Response samples

Content type
application/json
{
  • "date_acquisition": "01.12.2099",
  • "date_commissioning": "01.12.2099",
  • "date_decommissioning": "01.12.2099",
  • "date_tss_commissioning": "01.12.2099",
  • "decommissioning_reason": "string",
  • "establishment_id": "01234567-89ab-49ab-b012-3456789abcde",
  • "manufacturer": "string",
  • "metadata": {},
  • "model": "string",
  • "remarks": "string",
  • "serial_number": "string",
  • "software": "string",
  • "software_version": "string",
  • "type": "1",
  • "id": "01234567-89ab-49ab-b012-3456789abcde",
  • "tss_id": "01234567-89ab-49ab-b012-3456789abcde"
}

Create or update an external client

Information about an external client (i.e. a client using a TSS from a manufacturer other than fiskaly) that is relevant in the context of a submission according to "§146a (4) Abgabenordnung",

Authorizations:
JWT
path Parameters
tss_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies an external TSS.

client_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies an external client (ERS).

Request Body schema: application/json
date_acquisition
required
string^(0[1-9]|[1-2][0-9]|3[0-1])\.(0[1-9]|1[0-2])\...

Acquisition of the electronic recording system. Anschaffung des elektronischen Aufzeichnungssystems

date_commissioning
required
string^(0[1-9]|[1-2][0-9]|3[0-1])\.(0[1-9]|1[0-2])\...

Commissioning of the electronic recording system. Inbetriebnahme des elektronischen Aufzeichnungssystems

date_decommissioning
string^(0[1-9]|[1-2][0-9]|3[0-1])\.(0[1-9]|1[0-2])\...

Decommissioning of the electronic recording system. Außerbetriebnahme des elektronischen Aufzeichnungssystems

date_tss_commissioning
string^(0[1-9]|[1-2][0-9]|3[0-1])\.(0[1-9]|1[0-2])\...

Commissioning date of the TSS on the given electronic recording system. Inbetriebnahme der technischen Sicherheitseinrichtung auf dem jeweiligen elektronischen Aufzeichnungssystem

decommissioning_reason
string [ 1 .. 1000 ] characters

Reason for decommissioning. Grund der Außerbetriebnahme

establishment_id
string <uuid> (EstablishmentIdentifier) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...

Uniquely identifies an establishment. Eindeutige Identifizierung eines Betriebs.
Note: This field must be used to link the client to an establishment and include it in the submission.

manufacturer
required
string [ 1 .. 1000 ] characters

Manufacturer. Hersteller

object (Metadata) <= 20 properties

Arbitrary custom key-value data. 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.

model
required
string [ 1 .. 1000 ] characters

Model. Modell

remarks
string [ 1 .. 1000 ] characters

Remarks. Bemerkungen zum eAs (z. B. bei Art des eAs Taxameter oder Wegstreckenzähler das Kfz-Kennzeichen)

serial_number
required
string [ 1 .. 1000 ] characters

Serial number of the ERS. Seriennummer des elektronischen Aufzeichnungssystems/Software-App

software
required
string [ 1 .. 1000 ] characters

Software. Software

software_version
string [ 1 .. 1000 ] characters

Software version. Software-Version

type
required
string (Client types)
Enum: "1" "2" "3" "4" "5"
  • 1 - Computergestützte/PC-Kassensysteme
  • 2 - Tablet-/App-Kassen-Systeme
  • 3 - Elektronische Registrierkassen
  • 4 - Taxameter
  • 5 - Wegstreckenzähler

Responses

Request samples

Content type
application/json
{
  • "date_acquisition": "01.12.2099",
  • "date_commissioning": "01.12.2099",
  • "date_decommissioning": "01.12.2099",
  • "date_tss_commissioning": "01.12.2099",
  • "decommissioning_reason": "string",
  • "establishment_id": "01234567-89ab-49ab-b012-3456789abcde",
  • "manufacturer": "string",
  • "metadata": {},
  • "model": "string",
  • "remarks": "string",
  • "serial_number": "string",
  • "software": "string",
  • "software_version": "string",
  • "type": "1"
}

Response samples

Content type
application/json
{
  • "date_acquisition": "01.12.2099",
  • "date_commissioning": "01.12.2099",
  • "date_decommissioning": "01.12.2099",
  • "date_tss_commissioning": "01.12.2099",
  • "decommissioning_reason": "string",
  • "establishment_id": "01234567-89ab-49ab-b012-3456789abcde",
  • "manufacturer": "string",
  • "metadata": {},
  • "model": "string",
  • "remarks": "string",
  • "serial_number": "string",
  • "software": "string",
  • "software_version": "string",
  • "type": "1",
  • "id": "01234567-89ab-49ab-b012-3456789abcde",
  • "tss_id": "01234567-89ab-49ab-b012-3456789abcde"
}

Deletes additional data of a SIGN DE client

Deletes additional data related to a client.

Authorizations:
JWT
path Parameters
tss_id
required
string <uuid> (SignDEv2UniversallyUniqueIdentifier) ^[0-9a-fA-F]{8}-(?:[0-9a-fA-F]{4}-){3}[0-9a-f...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies a SignDEv2 TSS.

client_id
required
string <uuid> (SignDEv2UniversallyUniqueIdentifier) ^[0-9a-fA-F]{8}-(?:[0-9a-fA-F]{4}-){3}[0-9a-f...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies a SignDEv2 client (ERS).

Responses

Response samples

Content type
application/json
{
  • "code": "E_BAD_REQUEST",
  • "error": "Bad Request",
  • "message": "The request is invalid.",
  • "status": 400,
  • "validation": {
    }
}

Retrieve additional data of a SIGN DE client

Returns additional information about a specific SIGN DE client that is relevant in the context of a submission according to "§146a (4) Abgabenordnung".

Authorizations:
JWT
path Parameters
tss_id
required
string <uuid> (SignDEv2UniversallyUniqueIdentifier) ^[0-9a-fA-F]{8}-(?:[0-9a-fA-F]{4}-){3}[0-9a-f...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies a SignDEv2 TSS.

client_id
required
string <uuid> (SignDEv2UniversallyUniqueIdentifier) ^[0-9a-fA-F]{8}-(?:[0-9a-fA-F]{4}-){3}[0-9a-f...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies a SignDEv2 client (ERS).

Responses

Response samples

Content type
application/json
{
  • "date_acquisition": "01.12.2099",
  • "date_commissioning": "01.12.2099",
  • "date_decommissioning": "01.12.2099",
  • "decommissioning_reason": "string",
  • "establishment_id": "01234567-89ab-49ab-b012-3456789abcde",
  • "manufacturer": "string",
  • "metadata": {},
  • "model": "string",
  • "remarks": "string",
  • "software": "string",
  • "software_version": "string",
  • "type": "1"
}

Create or update additional data of a SIGN DE client

Additional information about a specific SIGN DE client that is relevant in the context of a submission according to "§146a (4) Abgabenordnung".

Authorizations:
JWT
path Parameters
tss_id
required
string <uuid> (SignDEv2UniversallyUniqueIdentifier) ^[0-9a-fA-F]{8}-(?:[0-9a-fA-F]{4}-){3}[0-9a-f...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies a SignDEv2 TSS.

client_id
required
string <uuid> (SignDEv2UniversallyUniqueIdentifier) ^[0-9a-fA-F]{8}-(?:[0-9a-fA-F]{4}-){3}[0-9a-f...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies a SignDEv2 client (ERS).

Request Body schema: application/json
date_acquisition
required
string^(0[1-9]|[1-2][0-9]|3[0-1])\.(0[1-9]|1[0-2])\...

Acquisition of the electronic recording system. Anschaffung des elektronischen Aufzeichnungssystems

date_commissioning
required
string^(0[1-9]|[1-2][0-9]|3[0-1])\.(0[1-9]|1[0-2])\...

Commissioning of the electronic recording system. Inbetriebnahme des elektronischen Aufzeichnungssystems

date_decommissioning
string^(0[1-9]|[1-2][0-9]|3[0-1])\.(0[1-9]|1[0-2])\...

Decommissioning of the electronic recording system. Außerbetriebnahme des elektronischen Aufzeichnungssystems

decommissioning_reason
string [ 1 .. 1000 ] characters

Reason for decommissioning. Grund der Außerbetriebnahme

establishment_id
string <uuid> (EstablishmentIdentifier) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...

Uniquely identifies an establishment. Eindeutige Identifizierung eines Betriebs.
Note: This field must be used to link the client to an establishment and include it in the submission.

manufacturer
required
string [ 1 .. 1000 ] characters

Manufacturer. Hersteller

object (Metadata) <= 20 properties

Arbitrary custom key-value data. 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.

model
required
string [ 1 .. 1000 ] characters

Model. Modell

remarks
string [ 1 .. 1000 ] characters

Remarks. Bemerkungen zum eAs (z. B. bei Art des eAs Taxameter oder Wegstreckenzähler das Kfz-Kennzeichen)

software
required
string [ 1 .. 1000 ] characters

Software. Software

software_version
string [ 1 .. 1000 ] characters

Software version. Software-Version

type
required
string (Client types)
Enum: "1" "2" "3" "4" "5"
  • 1 - Computergestützte/PC-Kassensysteme
  • 2 - Tablet-/App-Kassen-Systeme
  • 3 - Elektronische Registrierkassen
  • 4 - Taxameter
  • 5 - Wegstreckenzähler

Responses

Request samples

Content type
application/json
{
  • "date_acquisition": "01.12.2099",
  • "date_commissioning": "01.12.2099",
  • "date_decommissioning": "01.12.2099",
  • "decommissioning_reason": "string",
  • "establishment_id": "01234567-89ab-49ab-b012-3456789abcde",
  • "manufacturer": "string",
  • "metadata": {},
  • "model": "string",
  • "remarks": "string",
  • "software": "string",
  • "software_version": "string",
  • "type": "1"
}

Response samples

Content type
application/json
{
  • "date_acquisition": "01.12.2099",
  • "date_commissioning": "01.12.2099",
  • "date_decommissioning": "01.12.2099",
  • "decommissioning_reason": "string",
  • "establishment_id": "01234567-89ab-49ab-b012-3456789abcde",
  • "manufacturer": "string",
  • "metadata": {},
  • "model": "string",
  • "remarks": "string",
  • "software": "string",
  • "software_version": "string",
  • "type": "1"
}

Submission

Retrieve submissions

Returns a list of submissions created by a taxpayer. Only clients without a decommissioning date are counted for AnzahlAufzeichnungssysteme.

Authorizations:
JWT
query Parameters
establishment_id
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: establishment_id=01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies an establishment.

state
string (SubmissionState)
Enum: "CREATED" "VALIDATION_TRIGGERED" "INTERNAL_VALIDATION_FAILED" "EXTERNAL_VALIDATION_FAILED" "VALIDATION_SUCCEEDED" "XML_GENERATION_SUCCEEDED" "XML_GENERATION_FAILED" "READY_FOR_TRANSMISSION" "TRANSMISSION_PENDING" "TRANSMISSION_IN_PROGRESS" "TRANSMISSION_FAILED" "TRANSMISSION_SUCCEEDED" "TRANSMISSION_CANCELLED" "ERROR"

Defines the state of submission.

limit
integer (PaginationLimit) [ 1 .. 100 ]
Default: 10

Represents the pagination limit of the results set of a listing endpoint.

token
string (PaginationToken) <= 1024 characters ^(?:[A-Za-z0-9+\/]{4})*(?:[A-Za-z0-9+\/]{4}|[...

Represents the pagination token, which is used as an index pointer to the next page relative to the current page in Base64 encoding.

time_start
integer >= 0

Only return submissions with creation time not before the given start date.

time_end
integer >= 0

Only return submissions with creation time not after the given end date.

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "results": [
    ]
}

Delete submission

Deletes the submission. Not possible if a submission is being transmitted or has been already transmitted. Only clients without a decommissioning date are counted for AnzahlAufzeichnungssysteme.

Authorizations:
JWT
path Parameters
submission_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies a submission.

Responses

Response samples

Content type
application/json
{
  • "code": "E_UNAUTHORIZED_ACCESS",
  • "error": "Unauthorized Access",
  • "message": "Not authorized to perform this operation.",
  • "status": 401,
  • "validation": {
    }
}

Retrieve submission

Returns the information of a specific submission

Authorizations:
JWT
path Parameters
submission_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies a submission.

Responses

Response samples

Content type
application/json
Example

Example of external validation error

{
  • "env": "TEST",
  • "error_description": "[610301006] Fehler beim Parsen der Eingabedaten. Details stehen im Logfile (eric.log).",
  • "establishment_id": "1b2c8c8f-c5ae-4ab2-888a-a2f733df1343",
  • "id": "bf64861b-913c-447c-9163-10a8981da815",
  • "state": "EXTERNAL_VALIDATION_FAILED",
  • "time_created": "2024-06-25T13:00:40.834873Z",
  • "time_error": "2024-06-25T13:00:41.03935Z",
  • "time_generated": "2024-06-25T13:00:40.834873Z"
}

Create submission

Creates a submission. Only clients without a decommissioning date are counted for AnzahlAufzeichnungssysteme.

Authorizations:
JWT
path Parameters
submission_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies a submission.

Request Body schema: application/json
establishment_id
required
string <uuid> (EstablishmentIdentifier) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...

Uniquely identifies an establishment. Eindeutige Identifizierung eines Betriebs.

object (Metadata) <= 20 properties

Arbitrary custom key-value data. 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 of success request with required fields

{
  • "establishment_id": "1b2c8c8f-c5ae-4ab2-888a-a2f733df1343"
}

Response samples

Content type
application/json
{
  • "env": "TEST",
  • "error_description": "string",
  • "establishment_id": "01234567-89ab-49ab-b012-3456789abcde",
  • "id": "01234567-89ab-49ab-b012-3456789abcde",
  • "metadata": {},
  • "state": "CREATED",
  • "time_created": "2019-08-24T14:15:22Z",
  • "time_error": "2019-08-24T14:15:22Z",
  • "time_generated": "2019-08-24T14:15:22Z",
  • "time_transmitted": "2019-08-24T14:15:22Z"
}

Download XML file of submission

Returns the submitted information in the XML format required for its transmission to the fiscal authorities. If you need different XML format, you can specify it in the query parameter format.

Authorizations:
JWT
path Parameters
submission_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies a submission.

query Parameters
xml_header
boolean (XmlHeader)
Default: false

A flag to explicitly add the XML declaration to the output. If 'true', the header <?xml version="1.0" encoding="UTF-8" standalone="yes"?> is prepended to the response body. If 'false' (default), the XML document will be returned without this declaration.

Responses

Response samples

Content type
application/json
{
  • "code": "E_UNAUTHORIZED_ACCESS",
  • "error": "Unauthorized Access",
  • "message": "Not authorized to perform this operation.",
  • "status": 401,
  • "validation": {
    }
}

Cancel transmission

Cancels submission transmission. Not possible if a submission is actively being transmitted or has been already transmitted.

Authorizations:
JWT
path Parameters
submission_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies a submission.

Responses

Response samples

Content type
application/json
{
  • "establishment_id": "a85af7ba-b194-4034-997f-bbd31a462bf2",
  • "id": "a271225a-c926-4530-824d-20a3a7a1d59d",
  • "state": "TRANSMISSION_CANCELLED",
  • "time_created": "2025-01-01T10:00:00.0000000",
  • "time_generated": "2025-01-01T10:00:01.0000000"
}

Trigger transmission

Triggers transmission of a specific submission to the fiscal authorities. Only possible if the submission is in the state READY_FOR_TRANSMISSION. By sending "legal_consent": true in the request body, the integrator consents to the terms in the legal_consent description.

Authorizations:
JWT
path Parameters
submission_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies a submission.

Request Body schema: application/json
legal_consent
required
boolean

We hereby confirm to fiskaly Deutschland GmbH:

  1. We have entered into an agreement with our client, whose data records we transmit to the tax authorities via the SIGN DE service provided by fiskaly Deutschland GmbH. In accordance with §87d AO , we act as the client's authorized representative for the data transmission to the tax authority.
  2. Prior to the transmission of the data record via the SIGN DE service, we provided the data record to our client in an easily verifiable format for their review, approval, and verification that the data records are complete and accurate, which the client has confirmed.
  3. Before transmitting the data record, we verified the identification of our client as the principal (verification of identity and address). We have documented the relevant information and the client’s confirmation of the data records, in an appropriate format and can provide evidence at any time of the identity of the principal responsible for the data transmission, as well as the confirmation of the data records. The records of this information will be retained for five years following the end of the calendar year in which the last TV data transmission to the tax authority occurred.

Wir bestätigen fiskaly Deutschland GmbH:

  1. Wir haben mit unserem Kunden, dessen Datensatz wir über den Service SIGN DE der fiskaly Deutschland GmbH an die Finanzverwaltung übermitteln lassen, einen Vertrag und wir handeln im Sinne von §87d AO als dessen Auftraggeber für die Datenübermittlung an die Finanzbehörde.
  2. Wir haben unserem Auftraggeber vor der Übermittlung mit dem Service SIGN DE den Datensatzes in leicht nachprüfbarer Form zur Zustimmung und zur Überprüfung der Vollständigkeit und Richtigkeit zur Verfügung gestellt und der Auftraggeber die Richtigkeit und Vollständigkeit bestätigt.
  3. Wir haben uns vor Übermittlung des Datensatzes Gewissheit über die Person und die Anschrift unseres Kunden als Auftraggeber (Identifizierung) verschafft und die entsprechenden Angaben und die Bestätigung des Datensatzes in geeigneter Form festgehalten und können jederzeit Auskunft darüber geben wer Auftraggeber der Datenübermittlung war und die Bestätigung vorzulegen. Diese Aufzeichnungen bewahren wir fünf Jahre nach Ablauf des Jahres der letzten Datenübermittlung an die Finanzbehörde auf.

Responses

Request samples

Content type
application/json
{
  • "legal_consent": true
}

Response samples

Content type
application/json
{
  • "establishment_id": "a85af7ba-b194-4034-997f-bbd31a462bf2",
  • "id": "a271225a-c926-4530-824d-20a3a7a1d59d",
  • "state": "TRANSMISSION_PENDING",
  • "time_created": "2025-01-01T10:00:00.0000000",
  • "time_generated": "2025-01-01T10:00:01.0000000"
}

Download submission transmission PDF

When transmission is successful, this provides a file, generated by ERiC, containing submission in the PDF format.

Authorizations:
JWT
path Parameters
submission_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies a submission.

Responses

Response samples

Content type
application/json
{
  • "code": "E_UNAUTHORIZED_ACCESS",
  • "error": "Unauthorized Access",
  • "message": "Not authorized to perform this operation.",
  • "status": 401,
  • "validation": {
    }
}

Download ERiC/ELSTER transmission XML.

When the transmission via ERiC/ELSTER has failed, this provides a file that contains a set of errors in the XML format.

Authorizations:
JWT
path Parameters
submission_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies a submission.

Responses

Response samples

Content type
application/json
{
  • "code": "E_UNAUTHORIZED_ACCESS",
  • "error": "Unauthorized Access",
  • "message": "Not authorized to perform this operation.",
  • "status": 401,
  • "validation": {
    }
}

Download submission preview PDF

When validation is successful, this provides a preview of the submission, generated by ERiC, in the PDF format.

Authorizations:
JWT
path Parameters
submission_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies a submission.

Responses

Response samples

Content type
application/json
{
  • "code": "E_UNAUTHORIZED_ACCESS",
  • "error": "Unauthorized Access",
  • "message": "Not authorized to perform this operation.",
  • "status": 401,
  • "validation": {
    }
}

Download ERiC validation XML.

When validation has failed, this provides a file that contains a set of errors in the XML format.

Authorizations:
JWT
path Parameters
submission_id
required
string <uuid> (UniversallyUniqueIdentifierV4) ^[a-fA-F0-9]{8}-?[a-fA-F0-9]{4}-?4[a-fA-F0-9]...
Example: 01234567-89ab-49ab-b012-3456789abcde

Uniquely identifies a submission.

Responses

Response samples

Content type
application/json
{
  • "code": "E_UNAUTHORIZED_ACCESS",
  • "error": "Unauthorized Access",
  • "message": "Not authorized to perform this operation.",
  • "status": 401,
  • "validation": {
    }
}

Was this page helpful?