For external customers
This guide provides an overview of the steps needed to submit required data to the tax authorities according to the legal requirements (§146a (4) AO - German Fiscal Code). It is meant for customers who have not implemented the fiskaly SIGN DE API.
This API was created in cooperation with the tax administration of the State of Hessen.
The guide consists of two parts: Basic Setup and Main Part - SIGN DE x Submission Endpoints.
Part 1: Basic Setup
Creating an account
In order to use the fiskaly services, you will need to create an account via the fiskaly Dashboard. Once an account is created, you are prompted to create your first main organization.
Creating the first organization
The first (main) organization, representing the POS vendor, has to be created via the fiskaly Dashboard. Once it was created, you can proceed with adding managed organizations representing the individual taxpayer’s locations. It is possible to add an additional level to the structure, you can find a guide here.
Take a look at our video for a step-by-step explanation on how to set up your account and first organization.
Main and managed organizations: Differences
A main organization (organization) represents a POS provider or a retailer
with its own POS system, while a managed organization (managed_
organization) represents a merchant’s location or a retailer’s store location.
Examples:
- If the main organization is a POS provider, the managed organizations represent each customer’s (taxpayer) location.
- If the main organization is a retailer with its own POS system, the managed organizations represent each store.
Creating the first API Key
After creating an account and your first organization via the Dashboard, you need to generate an API Key in the Dashboard (Settings -> API Keys -> CREATE API KEY).
API Key and Secret are required in order to generate an access token via the authenticate endpoint. This token is used for all API calls.
POST: Create organization
Use this endpoint to create a managed organization. Use the ID of the
main organization for the managed_by_organization_id field in your
request body. We strongly recommend setting up a separate managed
organization for every location. This way, a structure can be created,
where a managed organization corresponds to an Establishment.
Part 2: SIGN DE x Submission Endpoints
POST: Authenticate API
In order to access the SIGN DE x Submission API, you need a valid JWT token.
This endpoint creates the token with your api_key and api_secret. If you do
not have an api_key, you can create one via the Management API Endpoint
createApiKey or 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 schema.
PUT: Create or update taxpayer
The Taxpayer represents either a natural person or a legal entity such as a company. General information about the taxpayer needs to be provided here. It is created only once and can be updated without triggering a new Submission.
Within each (managed_)organization, only one Taxpayer can and should be created.
PUT: Create or update establishment
The Establishment represents each physical business location (Betriebsstätte) and must be created even if the Establishment data is the same as the data of the Taxpayer.
For customers who have created a separate managed_organization for each
location, the managed_organization always corresponds to one specific
Establishment. This is the recommended approach.
In case a managed_organization represents more than one location of the same
Taxpayer, a separate Establishment must be created for each of these locations.
Each Taxpayer can own multiple Establishments, but each Establishment can belong to only one Taxpayer and have a single address.
The creation and updates of TSS and Clients assigned to an Establishment always require a new Submission of the relevant Establishment as a whole. Other Establishments do not require a new Submission in that case.
PUT: Create or update an external TSS (i.e. a TSS from a manufacturer other than fiskaly)
A TSS stands for a Technical Security System. It’s a set of components used to secure, store, and manage fiscal data.
External TSSs need to be added via this endpoint.
This endpoint is not mandatory for customers who implemented the fiskaly SIGN DE API and do not use external TSSs.
PUT: Create or update an external client (i.e. using a TSS from a manufacturer other than fiskaly)
A Client represents a POS device in use. Clients connected to external TSS instances are added via this endpoint.
The decommissioning of a Client has to be reported only once, via setting the corresponding parameters and triggering a new Submission for the relevant Establishment. After that, the Client can be unassigned from the Establishment and/or reassigned to another Establishment as a commissioned Client, again followed by a new Submission for the relevant Establishment.
This endpoint is not mandatory for customers who implemented the fiskaly SIGN DE API and do not use external TSSs.
PUT: Create submission
A Submission is the set of information about a specific Establishment with all its Clients. It is not automatically sent to the tax authorities - an additional request must be made via the TriggerTsransmission endpoint.
The Submission can be retrieved in PDF format via the endpoint GetSubmissionSuccessfulFile and XML format via the GetSubmissionFile endpoint.
API Integrators must ensure that the actual taxpayers have checked if the generated Submission data is correct before it is sent to the tax authorities.
PUT: Trigger transmission
Transmission is the process in which the data from the Submission is transferred to the ELSTER (ELektronische STeuer ERklärung) server. Only one Transmission can be triggered per Submission.
Once triggered, a Transmission may be canceled, as long as it is being serviced in the SIGN DE x Submission API, and has not yet been transmitted to ELSTER. As the Transmission usually takes place within a few seconds, the window for a successful cancellation is short. After a successful cancellation, a Transmission for the specific Submission may be triggered again.
Use this endpoint to trigger a Transmission of a specific Submission to the tax
authorities. Please note that this is only possible if the Submission is in the
state VALIDATION_SUCCEEDED, which indicates that the data contained in the
Submission has been checked for syntactic validity and completeness. However,
this is not a confirmation of factual accuracy.
The Taxpayer is required by law to check the Submission data for correctness before triggering the Transmission. The act of triggering the Submission indicates the Taxpayer’s consent and assumption of responsibility for the accuracy of the data transmitted. In the case where erroneous data were included in a transmitted Submission, this can be rectified by simply creating and transmitting a new Submission with the correct data.