SIGN FR Integration Guide for SIGN DE Customers
This guide explains the key differences from SIGN DE and supports you in successfully integrating the fiskaly SIGN FR API. It outlines all necessary steps for you and your merchants.
Unified API approach
SIGN FR is part of fiskaly’s Unified API approach. This means that by integrating SIGN FR, you are already prepared to use SIGN IT, our Italian solution, as well as upcoming countries that will follow soon, with minimal additional effort.
Unlike SIGN DE, SIGN FR does not require a separate Management API. All necessary endpoints for authentication, asset creation, configuration and fiscal record handling are included directly in the SIGN FR API — making the integration faster and simpler.
Environments: TEST and LIVE
In SIGN FR, there are two separate base URLs for the different environments:
- TEST environment:
https://test.api.fiskaly.com
- LIVE environment:
https://live.api.fiskaly.com
This is different from SIGN DE, where there is only one base URL used for both environments.
In SIGN DE, the API Key itself determines whether TEST or LIVE resources are created.
A token created with a LIVE API Key creates LIVE resources.
A token created with a TEST API Key creates TEST resources — even though the URL stays the same.
In SIGN FR, the environment is selected via the base URL.
You must call every endpoint with the correct base URL (test.api.fiskaly.com
or live.api.fiskaly.com
), depending on whether you want to interact with the TEST or LIVE environment.
Header Parameters
In the Unified API approach, some new HTTP headers were introduced to simplify your processes.
They provide flexibility, ensure data integrity, and make integrations simpler and more reliable.
X-Api-Version
For all Unified API solutions, every request has to include the X-Api-Version
header.
The value corresponds to the release date of the version. This gives you full control over when to switch to a newer version in order to use new features.
You can test changes first in the TEST environment and only migrate to the new version once everything has been verified. This also allows you to run some customers on an older version if needed while onboarding new customers directly with the latest one.
Main advantage: no more breaking changes in your running version.
X-Idempotency-Key
Since resource IDs do not need to be longer defined by you but are generated by the API, the X-Idempotency-Key
guarantees that an API call is handled idempotently.
This means that repeated identical requests with the same X-Idempotency-Key
produce the same result and prevent duplicate creations.
The X-Idempotency-Key
is required for all POST and PATCH requests.
X-Scope-Identifier
The X-Scope-Identifier
header replaces the path parameters previously used in the Management API to establish relations between resources.
It makes integrations cleaner and more flexible, as the header explicitly defines the scope (for example, which Asset::Unit
an API Key belongs to).
Terminology Mapping: SIGN FR vs. SIGN DE
SIGN FR | SIGN DE | Explanation |
---|---|---|
Asset::Tenant | (no equivalent) | Top-level structure in the fiskaly HUB. Represents the entire customer account. Cannot be nested within other assets. |
Asset::Group (optional) | organisation (with billing_options ) | Optional intermediate layer used to organize multiple taxpayers into logical clusters. |
Asset::Unit | managed_organization | Represents an individual merchant or taxpayer. Each Asset::Unit links to a taxpayer via an Entity . |
Entity::COMPANY or Entity::INDIVIDUAL | In Germany part of the managed_organization (DSFINVK DE) or taxpayer (SUBMIT DE) | Defines the taxpayer for the linked Asset::Unit , required to fulfill fiscal obligations. |
Entity::LOCATION | Comparable: establishment (SUBMIT DE) | Represents physical location(s) (e.g. shops) operated by the taxpayer. |
System::FISCAL_DEVICE | client | Represents the POS / cash register used for fiscalization. |
Subject::API_KEY | API key | API key authentication object, used to authorize access. |
Record | transaction | Represents an operation performed on the cash register. For special events, it may consist only of a Record::INTENTION . For transactions, it always requires two calls: one Record::INTENTION and one Record::TRANSACTION . |
Record::INTENTION | Start-Transaction | Marks the start of a purchase process, or a single other event that is processed on the cash register. |
Record::TRANSACTION | Finish-Transaction | Marks the completion (finish) of a purchase process. |
SIGN FR Step-by-Step
First Organization
To begin, you have to create a separate organization specifically for France in the fiskaly Dashboard and a dedicated API Key for the French integration.
From this point on, all integration steps are handled directly via the SIGN FR API. In contrast to SIGN DE, you no longer need to use the Management API to create or manage organizational structures. All required functionality is part of the SIGN FR API itself.
POST: Create Token
Use this token to authenticate the creation of the organizational structure for France.
It works the same way as the token in SIGN DE (Management API), which was created using the API Key of the (main) organization and then used to create managed_organizations
.
In SIGN FR, this token is now required to create Asset::Unit
resources.
POST: Create Asset (UNIT)
Create an Asset::UNIT (Asset of type Unit) representing your first customer. This is equivalent to managed_organization
created via the Management API used for SIGN DE.
At this step, only the name of the Asset::Unit
is required.
Unlike in SIGN DE, the taxpayer information belongs to the Entity
resource, which can be of type COMPANY
or INDIVIDUAL
, depending on whether the taxpayer is a legal or a natural person. You will define these details in the Entity (COMPANY / INDIVIDUAL) step below.
POST: Create Subject (API Key)
Each of your customers requires their own API Key in order to create resources within their specific Asset::Unit
scope.
For this reason, a Subject::API_KEY
(Subject of type API Key) has to be created.
Link your API Key to the Asset::Unit
using the X-Scope-Identifier
header.
In contrast to SIGN DE, the information about which Unit the API Key belongs to is no longer provided via the path parameter, but instead through the header parameter X-Scope-Identifier
.
This header has to contain the ID of the Asset::UNIT
to which the API Key belongs.
POST: Create Token (scoped)
This token is scoped to the Asset::Unit
. Use it for all taxpayer-specific operations.
With the previously created API Key for the Asset::Unit
, you have to create this scoped token.
It will be used for all operations that need to be handled within this specific Asset::Unit
.
POST: Create Entity (COMPANY / INDIVIDUAL)
Defines the taxpayer representation for the corresponding Asset::Unit
.
An Entity
of type COMPANY
or INDIVIDUAL
represents the taxpayer — either a legal entity (company) or a natural person (sole trader).
Each taxpayer must be created as an Entity before fiscal operations can be performed.
As SIGN FR follows the Unified API approach, the Entity
structure is designed in a standardized way and divided into two main parts:
-
General information (shared across all countries):
This includes common attributes such as the taxpayer’s name and address. -
Fiscalization information (country-specific section):
This contains fiscal attributes required by national regulations, such as the taxpayer identification number and fiscal credentials.
In France, this includes fiscal attributes such as the SIREN number and the fiscal year date that are required by national regulations.
PATCH: Update Entity
Update the state from ACQUIRED
to COMMISSIONED
to activate the Entity.
In contrast to SIGN DE, Entities in SIGN FR have a state attribute.
When an Entity is created, its initial state is ACQUIRED
.
Before it can be used, the Entity must be updated to the state COMMISSIONED
.
This step is irreversible. From this point on, the resource becomes billable according to the applicable billing model.
If an Entity is no longer in use, it can be updated to the state DECOMMISSIONED
.
This step is also irreversible and should only be performed once it is certain that the customer will no longer use this Entity.
In addition to states, each Entity in SIGN FR has a mode attribute that defines its operational status.
-
When the Entity is in state
ACQUIRED
orDECOMMISSIONED
, its mode is alwaysINACTIVE
.
In this mode, the resource cannot be used. -
When the Entity is updated to state
COMMISSIONED
, the SIGN FR service automatically validates all required configurations.
If successful, the mode switches toOPERATIVE
. -
If there is an issue with the Entity or one of its dependent resources, the mode automatically changes to
DEGRADED
until the problem is resolved.
Once the issue has been fixed, the SIGN FR service will return the mode toOPERATIVE
. -
The mode
SUSPENDED
can be set manually for Entities in stateCOMMISSIONED
using the update endpoint.
This is useful for temporarily pausing fiscal operations, for example, when updating credentials or performing maintenance. If the SIGN FR service sets the Entity to modeDEGRADED
due to an issue that requires user action, the mode should first be changed toSUSPENDED
while performing the necessary actions,
and then updated back toOPERATIVE
once the issue has been resolved.
Summary:
INACTIVE
: Default mode forACQUIRED
andDECOMMISSIONED
OPERATIVE
: Normal productive modeDEGRADED
: Automatically set by the SIGN FR service due to an issueSUSPENDED
: Manual maintenance mode
POST: Create Entity (LOCATION)
Defines the physical business location. Also starts in ACQUIRED
state.
For each location of a taxpayer, a separate Entity
of type LOCATION
should be created.
In the SIGN FR solution, this does not require a separate Asset::Unit
.
All locations of a taxpayer are represented within the same Asset::Unit
and are linked to the corresponding Entity::COMPANY
or Entity::INDIVIDUAL
.
Each taxpayer (Entity::COMPANY
or Entity::INDIVIDUAL
) should have at least one associated Entity::LOCATION
.
PATCH: Update Entity
Update the state of the Entity::LOCATION
to COMMISSIONED
.
As with Entity::COMPANY
or Entity::INDIVIDUAL
, the Entity::LOCATION
also has to be updated to the state COMMISSIONED
before it can be used.
Only after this step the location becomes active and can be used.
POST: Create System
A System
of type FISCAL_DEVICE
represents a POS or cash register.
It corresponds to the client in SIGN DE.
Each System
is linked to an Entity::LOCATION
.
In contrast to SIGN DE, when creating a FISCAL_DEVICE
, additional information about the electronic keeping system itself has to be provided.
Most of these details are typically defined by the POS provider.
In Germany, this information is usually added later as part of the DSFinV-K DE or Submit DE process — in SIGN FR, however, this is done in a single step during the system creation.
PATCH: Update System
Update the System
from state ACQUIRED
to COMMISSIONED
to activate it.
The System
resource follows the same state and mode logic as an Entity
.
Once set to COMMISSIONED
, the system becomes active and billing applies automatically (when used in the LIVE environment).
If it is no longer in use, it can be set to DECOMMISSIONED
, which — as in SIGN FR generally — is irreversible.
The mode
attribute reflects the operational condition of the system (for example, OPERATIVE
, SUSPENDED
, or DEGRADED
).
These modes behave the same way as described for Entity
, allowing you to temporarily suspend operations or automatically indicate degraded performance due to configuration issues.
✅ Setup Completed
With the System
successfully commissioned, the initial setup phase is complete.
All organizational and fiscal structures — from Asset::Unit
to Entity
and System
— are now active and ready for production.
From this point onward, the following steps describe the daily fiscal operations carried out at the POS.
This includes creating and processing fiscal records that represent sales, returns, and other events — equivalent to transactions in SIGN DE, but with extended fiscal data as required in France.
Daily Operations at the POS
Once the setup is completed and all resources are commissioned, the fiscalization process in SIGN FR continues with daily operations.
These operations represent the daily business activities at the POS — such as issuing receipts, processing returns, or handling cancellations.
While the overall concept is similar to SIGN DE, SIGN FR introduces a unified and more data-rich Record model.
Each transaction is represented as one or more Records, which are digitally signed, journaled, and archived to ensure full fiscal compliance.
The following sections describe how to create, process, and manage these Records in the French fiscal environment.
POST: Create Record
In SIGN FR, each fiscal transaction is represented as one or more Records.
This model replaces the two-step transaction update process from SIGN DE (ACTIVE
→ FINISHED
) with two independent resources: one Record of type INTENTION
and another Record of type TRANSACTION
.
Part A) INTENTION
In SIGN DE, a transaction begins with a Start-Transaction event that marks the start of a fiscal process and is later updated to a finished state.
In SIGN FR, this logic is replaced by a dedicated resource: a Record of type INTENTION
.
A Record of type INTENTION
marks the start of a fiscal operation or directly performs operations that only require a single step, such as EVENT
, EXPORT
, or DUPLICATE
.
In France, supported intention operations are TRANSACTION
, EVENT
, EXPORT
, and DUPLICATE
.
It contains contextual information that defines the intent of the operation, including:
- The System (
System::FISCAL_DEVICE
) performing the operation. - The operation type, corresponding to one of the supported intention operations listed above.
Part B) TRANSACTION
In SIGN DE, a transaction is finalized through a Finish-Transaction update of the transaction resource that completes the fiscal process.
In SIGN FR, this step is represented by a separate resource: a Record of type TRANSACTION
.
A Record of type TRANSACTION
completes the fiscal operation and references the previously created Record of type INTENTION
.
It contains all fiscal and transactional data required for the operation.
Compared to SIGN DE, the data scope and structure are broader and are more closely aligned with the information contained in a transaction within a cash point closing (Kassenabschluss) in DSFinV-K DE.
It includes:
- Document information such as document number, date, and total gross and net amounts.
- Details for each sale line (goods or services), including description, quantity, VAT rate, and amount.
- References to prior receipts when creating
CORRECTION
orCANCELLATION
records. - Additional operation types are also supported within
Record::TRANSACTION
, depending on the business process and fiscal context.
This Record type provides the complete fiscal representation of the transaction as required by French regulation.
Record States and Modes
Each Record in SIGN FR (whether INTENTION
, TRANSACTION
, or other types) follows its own state and mode, reflecting its lifecycle within the fiscalization process.
States
- Accepted – The Record has been received, validated, and is ready for processing.
- Rejected – Validation failed; details are available in the log messages.
- Completed – The Record has been successfully processed.
- Failed – The Record could not be processed due to a failure with an external component.
Modes
- Processing – The Record is currently being processed.
- Finished – The Record has been processed, successfully or unsuccessfully.
Transitions
Transition | Description |
---|---|
POST → Accepted | The Record is created and temporarily enters the Accepted state if validation succeeds, and immediately proceeds to the next step. |
POST → Rejected | The Record fails validation and transitions automatically to Rejected , providing error logs. |
Accepted → Completed | Automatically set when processing finishes successfully. |
Accepted → Failed | Set when processing fails due to an external component. |
Processing → Finished | Indicates that processing has been completed, regardless of success or failure. |
This event-based design allows each fiscal operation to be tracked independently — without updating the same resource — ensuring a transparent, immutable audit trail for every transaction.
Additional Operations (Non-Transactional)
Beyond the standard INTENTION → TRANSACTION
flow, SIGN FR also supports non-transactional fiscal operations:
EVENT
– Used to log system or configuration events (for example, training mode, test operations, or system restarts).DUPLICATE
– Creates a duplicate of an existing fiscal document.EXPORT
– Generates a fiscal data export.
These operations are represented as Records of type INTENTION
only and do not require a TRANSACTION
counterpart.
They extend fiscal traceability to all relevant POS activities beyond sales transactions.
Summary
In daily operations, SIGN FR replaces the simple “Start → Finish” transaction flow of SIGN DE with a multi-resource, event-driven Record model.
Each operation — whether a sale, correction, export, or other fiscal event — is individually signed, journaled, and archived, ensuring complete traceability and compliance with French fiscal law.