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, organization creation, configuration and fiscal record handling are included directly in the SIGN FR — 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 Organization::Unit an API Key belongs to).

Terminology Mapping: SIGN FR vs. SIGN DE

SIGN FR	SIGN DE	Explanation
Organization::ACCOUNT	(no equivalent)	Top-level structure in the fiskaly HUB. Represents the entire customer account.
Organization::GROUP	organization (with billing_options)	Represents the main organization, under which taxpayers are nested
Organization::UNIT	managed_organization	Represents an individual merchant or taxpayer. Each Organization::UNIT links to a Taxpayer.
Taxpayer::COMPANY or Taxpayer::INDIVIDUAL	In Germany part of the managed_organization (DSFINVK DE) or taxpayer (SUBMIT DE)	Defines the taxpayer for the linked Organization::UNIT, required to fulfill fiscal obligations.
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. 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 Organization::UNIT resources.

POST: Create Organization (UNIT)

Create an Organization::UNIT (Organization 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 Organization::UNIT is required.
Unlike in SIGN DE, the taxpayer information belongs to the Taxpayer 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 Taxpayer (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 Organization::UNIT scope.
For this reason, a Subject::API_KEY (Subject of type API Key) has to be created.

Link your API Key to the Organization::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 Organization::UNIT to which the API Key belongs.

POST: Create Token (scoped)

This token is scoped to the Organization::UNIT. Use it for all taxpayer-specific operations.

With the previously created API Key for the Organization::UNIT, you have to create this scoped token.
It will be used for all operations that need to be handled within this specific Organization::UNIT.

POST: Create Taxpayer (COMPANY / INDIVIDUAL)

Defines the taxpayer representation for the corresponding Organization::UNIT.

A Taxpayer of type COMPANY or INDIVIDUAL represents the taxpayer — either a legal entity (company) or a natural person (sole trader).
Each taxpayer must be created before fiscal operations can be performed.

As SIGN FR follows the Unified API approach, the Taxpayer 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 Taxpayer

Update the state from ACQUIRED to COMMISSIONED to activate the Taxpayer.

In contrast to SIGN DE, Taxpayers in SIGN FR have a state attribute.
When a Taxpayer is created, its initial state is ACQUIRED.
Before it can be used, the Taxpayer 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 a Taxpayer 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 Taxpayer.

In addition to states, each Taxpayer in SIGN FR has a mode attribute that defines its operational status.

• When the Taxpayer is in state ACQUIRED or DECOMMISSIONED, its mode is always INACTIVE.
  In this mode, the resource cannot be used.

• When the Taxpayer is updated to state COMMISSIONED, the SIGN FR service automatically validates all required configurations.
  If successful, the mode switches to OPERATIVE.

• If there is an issue with the Taxpayer 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 to OPERATIVE.

• The mode SUSPENDED can be set manually for Taxpayers in state COMMISSIONED 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 Taxpayer to mode DEGRADED due to an issue that requires user action, the mode should first be changed to SUSPENDED while performing the necessary actions,
  and then updated back to OPERATIVE once the issue has been resolved.

---

Summary:

• INACTIVE: Default mode for ACQUIRED and DECOMMISSIONED
• OPERATIVE: Normal productive mode
• DEGRADED: Automatically set by the SIGN FR service due to an issue
• SUSPENDED: Manual maintenance mode

POST: Create Location

Defines the physical business location. Also starts in ACQUIRED state.

For each location of a taxpayer, a separate Location should be created.
In the SIGN FR solution, this does not require a separate Organization::UNIT.
All locations of a taxpayer are represented within the same Organization::UNIT and are linked to the corresponding Taxpayer::COMPANY or Taxpayer::INDIVIDUAL.
Each taxpayer should have at least one associated Location.

PATCH: Update Location

Update the state of the Location to COMMISSIONED.

As with Taxpayer::COMPANY or Taxpayer::INDIVIDUAL, the 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 a 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 a Taxpayer.
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 Taxpayer, 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 Organization::UNIT to Taxpayer 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 or CANCELLATION 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.