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.