For SIGN DE 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 implemented the fiskaly SIGN DE API.
This API was created in cooperation with the tax administration of the State of Hessen.
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 additional data of a SIGN DE client
A Client represents a POS device in use. In order to create Submissions, additional information about Clients that already exist in fiskaly SIGN DE must be added.
A Client can only be assigned to one Establishment. For each Establishment, the taxpayer must create a separate Submission with all the Clients linked with this Establishment.
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.
Additional data is required only for fiskaly SIGN DE clients. Additional data for fiskaly SIGN DE TSS instances is not needed.
Optional PUT: Create or update an external TSS (i.e. a TSS from a manufacturer other than fiskaly)
If an Establishment uses external TSSs in addition to fiskaly SIGN DE TSSs, the 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.
Optional PUT: Create or update an external client (i.e. using a TSS from a manufacturer other than fiskaly)
If non-fiskaly TSSs are used, the Clients connected to them are added via this endpoint.
External Clients require corresponding external TSSs to exist, and they need to be assigned to those TSSs.
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 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.