Step-by-Step Integration

To begin the integration process, please refer to the detailed step-by-step instructions provided here.

The accompanying diagram illustrates the workflow and highlights the essential steps necessary to successfully complete your integration.

For the integration, you will need to utilize our Dashboard, Management API, and SIGN AT API. The diagram and images will be added in a later update.

Step 1: Registration

Begin by registering on the Dashboard. Creating an account is the first step, after which you can proceed with setting up the organizational structure for your business within our system.

Step 2: Creating your first organization

Continue with creating your first organization using the Dashboard. This organization will represent the POS provider or retailer with its own POS system. It is necessary to include the billing address at this stage. This address will only be used for fiskaly’s billing purposes.

Step 3: Managed organizations

After establishing your first organization, you will proceed to create managed organizations. Each managed organization represents a merchant, enabling you to manage them separately. If you are considering automating your process, we recommend using the createOrganization endpoint of the Management API.

Step 4: API key generation

The next step is to generate an API key within each managed organization. This can be done via the Dashboard or the createApiKey endpoint of the Management API. This API key and secret pair is required for generating an access token, which is used for all subsequent API calls.

Note that API keys generated in the TEST environment will create TEST resources, while those from the LIVE environment will create LIVE resources. For further details, refer to our article on TEST and LIVE environments.

Starting from the next step, you will be utilizing our SIGN AT API. You may download our Postman collection, which could facilitate your integration moving forward with the next steps.

Step 5: Authenticate FON

After authenticating with the previously generated API key and secret pair via authenticate, it is necessary to call the authenticateFon endpoint once per taxpayer.

In order to enable the synchronization with FinanzOnline, the taxpayer first needs to create the “Cash Register Webservice User” directly in FinanzOnline and provide you with the credentials of this user.

📘Note

The credentials do not correspond to the general FinanzOnline credentials. They correspond to the credentials of the dedicated Cash Register Webservice User created by the taxpayer.

Step 6: Create SCU

Now, continue with creating an SCU via the createSignatureCreationUnit endpoint. Please note that per managed organization, only one SCU needs to be created. Once created, the state of an SCU will be CREATED.

Step 7: Create Cash Register(s)

Continue with creating at least one Cash Register via the createCashRegister endpoint. The number of cash registers should correspond to the number of cash registers used in a particular shop or store. Creating a Cash Register renders the state CREATED.

Step 8: Update SCU to INITIALIZED

For signing receipts, both the SCU and Cash Register(s) need to be updated to INITIALIZED. Call the updateSignatureCreationUnit endpoint and transition it to state INITIALIZED. This state transition automatically registers the SCU in the FinanzOnline portal.

Step 9: Update Cash Register(s)

In contrast to updating the SCU, Cash Register(s) need to be updated twice via updateCashRegister:

• First, change the Cash Register state to REGISTERED. This state transition automatically registers the Cash Register in the FinanzOnline portal.
• Then, in a second call, change the state to INITIALIZED. This state transition triggers the creation and validation of the initial receipt in the FinanzOnline portal.

Both SCU and Cash Register are now ready to sign receipts.

Step 10: Sign Receipts

With all previous steps completed, you are now ready to sign receipts via the signReceipt endpoint.

SIGN AT ensures that all receipts are RKSV compliant. The response contains all information required for augmenting the final receipt handed out to the customer:

• qr_code_data, which contains the data for the RKSV QR code to be displayed in graphical form
• Information to display in textual form: receipt_number, time_signature, and cash_register_serial_number
• All raw gross amounts