Step-by-Step Integration Process

B2B E-Invoicing

Issue legally compliant electronic invoices via the PEPPOL network for B2B transactions.

Multi-Country Support

Belgium, Germany, Italy, France, and Poland with country-specific compliance built in.

Unified API

Single integration for e-invoicing across all supported countries with consistent endpoints.

Prerequisites

Before starting, ensure you have:

• Access to fiskaly HUB (TEST environment)
• Basic understanding of REST APIs and authentication flows
• Your business registration details for taxpayer setup

📘Note

If you have already integrated SIGN IT or SIGN FR, the initial setup steps in this guide will likely be familiar and may already be completed. In that case, you can jump straight to Step 10 to review the additional steps required.

Integration Workflow

📘Important

Steps marked in yellow must be completed directly on HUB, while the remaining steps must be handled via the API. Performing each action in the right context is an important step toward a successful integration.

Step-by-Step Setup

1. Step 1: Register on HUB

   Begin by registering on fiskaly HUB.

   
2. Step 2: Create Account & Organization GROUP

   Creating a fiskaly Account is the first step, after which you can proceed with setting up the first organizational structure for your business and generating your API Key.

   The Account represents the PoS provider or a retailer that operates its own PoS system. It is the top-level organization in the structure.

   After creating your fiskaly Account, you will be taken to the Organization Selector where you can create your Group. A Group is an intermediate level within an Account that helps you organize multiple Units into logical clusters.

3. Step 3: Create API Key

   The next step is to generate an API Key for your Organization via HUB within your Group. This API Key and Secret pair is required to create your first Organization of type UNIT (Step 5).

   💡TEST vs. LIVE environments

   API Keys generated in the TEST environment (https://test.api.fiskaly.com) will create TEST resources, while those from the LIVE environment (https://live.api.fiskaly.com) will create LIVE resources.

1. Step 4: MANAGEMENT - Create Token

   Begin using the E-INVOICE API through the createToken endpoint. You will need to create a token to authenticate for the next steps.

2. Step 5: MANAGEMENT - Create an Organization UNIT

   Continue by creating an Organization of type UNIT through the createOrganization endpoint. A UNIT represents a single legal entity (merchant). You will need to create one UNIT for each taxpayer representation you manage.

   When creating your first Organization of type UNIT, ensure it is associated with your Group created via HUB. To do this, use the token generated from the API keys created for your Group. This reflects the hierarchical structure where the UNIT is nested under your GROUP, which in turn sits within your ACCOUNT.

3. Step 6: MANAGEMENT - Create Subject (API Key)

   Create a Subject of type API_KEY through the createSubject endpoint. The connection between the Organization UNIT and the API Key is established via the X-Scope-Identifier(using the id of the newly created Organization).

4. Step 7: MANAGEMENT - Create new Token

   Next, create a token that will be used to create resources within the corresponding Organization UNIT.

5. Step 8: OPERATION - Create Taxpayer

   You are now ready to create the Taxpayers required for e-invoicing. To do so, use the createTaxpayer endpoint. You will need to set the Taxpayer of type COMPANY.

   Depending on the country, the required fiscalization setup and required taxpayer data may differ, so please refer to the dedicated country guides:

   • Belgium
   • Germany
   • Italy (coming soon)
   • France (coming soon)
   • Poland (coming soon)

   Once you create a Taxpayer of type COMPANY, its state will be set to ACQUIRED. In order to be fully functional, the state has to be updated to COMMISSIONED using the updateTaxpayer endpoint.

   When calling the createTaxpayer endpoint a Location of type HEAD_OFFICE is automatically created. You can confirm this via the listLocations endpoint.

6. Step 9: OPERATION - Create Location

   New customers integrating e-invoicing only may skip this step.

   For receipt fiscalization, you need to create a Location of type BRANCH via the createLocation endpoint for each business location.

   When you create a Location of type BRANCH, its state is initially set to ACQUIRED. In order to proceed, you need to change the state to COMMISSIONED using the updateLocation endpoint.

7. Step 10: OPERATION - Create System

   The createSystem endpoint is used to create an abstraction of a system used for fiscal operations.

   Depending on your setup, the following applies:

   • New customers using only e-invoicing: create a single E_INVOICE_SERVICE System (only one per Taxpayer) and link it to the HEAD_OFFICELocation that was automatically created for you in step 8.

   • New customers using receipt fiscalization and e-invoicing: create FISCAL_DEVICE Systems for receipts and one additional E_INVOICE_SERVICE System (one per Taxpayer). Link the E_INVOICE_SERVICE System to the Location of type HEAD_OFFICE, and link the FISCAL_DEVICE System(s) to a Location type BRANCH.

   • Existing customers with commissioned fiscal devices adding e-invoicing: create one additional E_INVOICE_SERVICE System and link it to the Location of type HEAD_OFFICE. When a Taxpayer is created, a Location of type HEAD_OFFICE is automatically generated with the same ID. This can be verified by listing your Locations.

   When creating a System, its initial state is set to ACQUIRED. To proceed with the e-invoicing integration process, request commissioning of the E_INVOICE_SERVICE System using updateSystem.

   ⚠️Important

   After a successful commissioning request, the System is in state COMMISSIONED and initially in mode DEGRADED until Step 11 is fully completed.

8. Step 11: OPERATION - Upload Proof of Ownership

   Upload the Proof of Ownership PDF via the createRecord endpoint, using a Record of type INTENTION and operation of type UPLOAD. The submitted document is reviewed and verified, which can take up to 72 hours. Once verification is complete, the System automatically transitions from mode DEGRADED to mode OPERATIVE.

   More details on the required document content are provided in the Proof of Ownership section.

9. Step 12: OPERATION - Create Record

   💡Note

   Creating a Record in the E-INVOICE API will always require two subsequent calls: - Part A) INTENTION - at the start of the e-invoicing process - Part B) TRANSACTION - once the e-invoice data is complete

   PART A) Intention

   For each e-invoicing operation, first call the createRecord endpoint to register the intention to issue an electronic invoice.

   A Record of type INTENTION will contain the following information:

   • Association with the E_INVOICE_SERVICE System that will be used to issue the e-invoice
   • Operation of type TRANSACTION, indicating that the System intends to perform an e-invoicing operation.

   Part B) Transaction

   Next, call the createRecord endpoint again to create a Record of type TRANSACTION and operation type INVOICE. This transaction is associated with the internal identifier of an already created Record of type INTENTION and it contains the electronic invoice data.

   📘Important

   For E-INVOICE, the recipient is required to be a BUSINESS type and the invoicing block is required to be populated, otherwise the e-invoice cannot be transmitted. The delivery method and required fields within the invoicing block vary by country — please refer to the dedicated country guides below.

   • Belgium
   • Germany
   • Italy (coming soon)
   • France (coming soon)
   • Poland (coming soon)

   Once the Transaction is successfully processed, the electronic invoice is created and handled according to the applicable e-invoicing requirements. Country-specific behavior and any additional data requirements are described in the dedicated guides.

   ⚠️Important

   All Records created in the LIVE environment are legally valid, therefore, they must always represent real and valid business transactions.

Next Steps

Belgium Guide

Country-specific requirements for Belgian e-invoicing.

Germany Guide

Country-specific requirements for German e-invoicing.

Proof of Ownership

Learn about the document verification process.

API Reference

Complete E-INVOICE API documentation.