The Unified API

The fiskaly Unified API is a single integration architecture that covers multiple countries. Integrate it once for France or Italy, and adding the next country means changing the payload schema — not rewriting your integration.

This page documents how the Unified API works, what its resource model looks like, and how it differs from the Specialized APIs (SIGN DE, SIGN AT, SIGN ES).

Two API architectures

fiskaly provides two API architectures. Both are fully supported and actively maintained:

	Unified API	Specialized APIs
Countries	France (SIGN FR), Italy (SIGN IT), Sweden (coming)	Germany (SIGN DE), Austria (SIGN AT), Spain (SIGN ES)
Base URLs	`test.api.fiskaly.com` / `live.api.fiskaly.com`	Product-specific (e.g. `kassensichv.fiskaly.com`)
Org management	Built into the product API	Separate Management API (`management.fiskaly.com`)
Resource IDs	Server-generated (use `X-Idempotency-Key`)	Client-generated UUIDs
Version control	`X-Api-Version` header (date-based, no breaking changes)	No version header (breaking changes possible)
Resource scoping	`X-Scope-Identifier` header	Path parameters
Terminology	Organization, Taxpayer, Location, System, Record	TSS, client, transaction (varies per product)
Adding a country	Change payload schema inside the same resource model	Integrate a separate API with different endpoints

📘Neither architecture is legacy

The Specialized APIs are purpose-built for their country’s specific regulations. SIGN DE is fiskaly’s most mature product with 10,000+ integrations and BSI certification valid until 2033. The Unified API is the architecture fiskaly built for efficient multi-country expansion.

Which architecture should you use?

Scenario	Recommendation
You only need Germany	SIGN DE (Specialized API)
You only need Austria	SIGN AT (Specialized API)
You only need Spain	SIGN ES (Specialized API)
You only need France or Italy	Unified API
You need France + Italy (or + Sweden)	Unified API — integrate once, add countries via payload schema
You need Germany + France	Both — SIGN DE (Specialized) + SIGN FR (Unified). Same auth pattern, different resource models.
You are starting fresh and planning 3+ countries	Start with the Unified API for FR/IT, add Specialized APIs for DE/AT/ES as needed

Unified API base URLs

The Unified API uses separate base URLs for each environment:

TEST: https://test.api.fiskaly.com
LIVE: https://live.api.fiskaly.com

This is different from the Specialized APIs (e.g., SIGN DE), where a single base URL is used and the API key determines the environment.

Unified API headers

Every Unified API request includes these headers:

`X-Api-Version`

Required on every request. The value is the release date of the API version you are targeting (e.g., 2026-02-03).

X-Api-Version: 2026-02-03

This gives you full control over when to adopt a new version. You can:

Test a new version in TEST before migrating LIVE
Run different customers on different versions simultaneously
Guarantee no breaking changes within a pinned version

`X-Idempotency-Key`

Required on all POST and PATCH requests. Since resource IDs are server-generated (not client-provided like in SIGN DE), this header ensures that retried requests do not create duplicate resources.

X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Use a fresh UUIDv4 or UUIDv3 for each distinct operation. Use a new key when retrying a failed request.

`X-Scope-Identifier`

Used to establish resource relationships. Replaces the path parameters used in the Management API and Specialized APIs.

X-Scope-Identifier: organization-unit-id

For example, when creating an API key for a specific Organization::UNIT, the X-Scope-Identifier header contains the Unit’s ID instead of encoding it in the URL path.

Resource model

The Unified API uses a standardized resource hierarchy across all countries:

Organization::ACCOUNT       ← Your company (top-level, managed in HUB)
  │
  └── Organization::GROUP   ← Logical cluster (region, brand, franchise)
        │
        └── Organization::UNIT   ← Individual merchant / taxpayer
              │
              ├── Subject::API_KEY   ← API credentials for this unit
              │
              ├── Taxpayer (COMPANY or INDIVIDUAL)
              │     │
              │     ├── General info (name, address — shared across countries)
              │     │
              │     └── Fiscalization info (country-specific: SIREN for FR,
              │         Codice Fiscale for IT, etc.)
              │
              ├── Location   ← Physical business location (shop, store)
              │
              └── System::FISCAL_DEVICE   ← POS terminal / cash register

Resource states

Every major resource (Taxpayer, Location, System) follows the same state machine:

ACQUIRED ──→ COMMISSIONED ──→ DECOMMISSIONED
(created)      (active)         (retired)

ACQUIRED — resource is created but not yet active. Mode: INACTIVE.
COMMISSIONED — resource is active and ready for production. Mode: OPERATIVE. This transition is irreversible and starts billing.
DECOMMISSIONED — resource is permanently retired. Mode: INACTIVE. Also irreversible.

Operational modes within the COMMISSIONED state:

Mode	Meaning	Set by
`OPERATIVE`	Normal operation	Automatic (on commission or after issue resolved)
`DEGRADED`	Issue detected	Automatic (by the service)
`SUSPENDED`	Maintenance pause	Manual (by you, via API)

Records (the transaction model)

In the Unified API, transactions are called Records and use a two-step model:

Record::INTENTION — marks the start of a fiscal operation (equivalent to Start-Transaction in SIGN DE)
Record::TRANSACTION — completes the fiscal operation with full payload (equivalent to Finish-Transaction in SIGN DE)

Additional operation types supported via Record::INTENTION only (no TRANSACTION counterpart needed):

EVENT — system events (training mode, test operations, restarts)
DUPLICATE — duplicate of an existing fiscal document
EXPORT — fiscal data export generation

📘Not all operations are available in every country

France supports TRANSACTION, EVENT, DUPLICATE, and EXPORT intentions. Italy currently supports TRANSACTION only. Check the country-specific documentation for the full list.

Terminology mapping (Unified API vs SIGN DE)

If you are coming from a SIGN DE integration, this table maps the concepts:

Unified API	SIGN DE	Explanation
`Organization::ACCOUNT`	(no equivalent)	Top-level structure in HUB
`Organization::GROUP`	`organization`	Main organization under which taxpayers are nested
`Organization::UNIT`	`managed_organization`	Individual merchant. Links to a Taxpayer.
`Taxpayer` (COMPANY/INDIVIDUAL)	Part of `managed_organization` or `taxpayer` (SUBMIT DE)	The fiscal entity
`Location`	`establishment` (SUBMIT DE)	Physical business location
`System::FISCAL_DEVICE`	`client`	POS terminal / cash register
`Subject::API_KEY`	`API key`	Authentication credentials
`Record`	`transaction`	A fiscal operation
`Record::INTENTION`	Start-Transaction	Marks the start of a purchase
`Record::TRANSACTION`	Finish-Transaction	Completes the purchase with full fiscal data

What changes per country

The Unified API’s value proposition is that most of the integration is shared. Here is what stays the same and what differs:

Shared across all Unified API countries	Country-specific
Authentication (`POST /tokens`)	Taxpayer `fiscalization` section (e.g., SIREN for FR; Tax ID, VAT ID and credentials for IT)
Organization hierarchy (ACCOUNT > GROUP > UNIT)	Record payload schema (receipt structure, VAT handling, document types)
Headers (X-Api-Version, X-Idempotency-Key, X-Scope-Identifier)	Supported intention operations (FR has EVENT/DUPLICATE/EXPORT; IT has TRANSACTION only)
Resource lifecycle (ACQUIRED > COMMISSIONED > DECOMMISSIONED)	Regulatory requirements (NF525 certification for FR, receipt lottery for IT)
State and mode management (OPERATIVE, DEGRADED, SUSPENDED)	Connection loss handling (different protocols per country)
Base URLs (test.api.fiskaly.com / live.api.fiskaly.com)	—

Typical effort to add a second Unified API country: ~1 week for a team already integrated with the first country. You adapt the Taxpayer’s fiscalization section and the Record payload schema — everything else is reusable.

Integration walkthrough

Here is the complete setup flow for a Unified API country (using SIGN FR as the example). The flow is the same for SIGN IT.

Create Token
POST /tokens with your API key and secret (same as all fiskaly products). This token is used to create the organizational structure.
Create Organization::UNIT
POST /organizations with X-Idempotency-Key. Only the name is required at this point. This represents your customer (merchant).
Create Subject::API_KEY
POST /subjects with X-Scope-Identifier set to the Organization::UNIT ID. Each customer needs their own API key.
Create scoped Token
POST /tokens using the customer’s API key. This scoped token is used for all taxpayer-specific operations.
Create Taxpayer
POST /taxpayers with general info (name, address) and the country-specific fiscalization section (e.g., SIREN number for France, Tax ID, VAT ID and credentials for IT).
Commission Taxpayer
PATCH /taxpayers/{id} — update state from ACQUIRED to COMMISSIONED. This is irreversible and activates billing.
Create and commission Location
POST /locations then PATCH /locations/{id} to commission. Represents a physical business location.
Create and commission System
POST /systems then PATCH /systems/{id} to commission. Represents a POS terminal. In SIGN FR, you also provide electronic keeping system details at this step.
Create Record::INTENTION
POST /records with operation type (e.g., TRANSACTION) and the System ID. This starts the fiscal operation.
Create Record::TRANSACTION
POST /records referencing the INTENTION record. Contains the full fiscal payload (items, amounts, VAT, payment methods). The response includes the cryptographic signature.

No separate Management API

Unlike the Specialized APIs (SIGN DE, SIGN AT, SIGN ES), the Unified API does not require the Management API (management.fiskaly.com). All organization management, API key creation, and configuration is handled directly within the product API.

This means fewer API surfaces to integrate, fewer credentials to manage, and a simpler overall architecture.

Countries on the Unified API

France (SIGN FR)

NF525 certification, period closures, offline replay, archives

Italy (SIGN IT)

Cloud-based APIs for fiscal receipt transmission to the Italian tax authority (AdE).

Sweden (SIGN SE)

InfraSec TCS — currently being integrated into the Unified API

Countries on Specialized APIs

Germany (SIGN DE)

BSI-certified Cloud-TSS, KassenSichV, DSFinV-K, SUBMIT DE

Austria (SIGN AT)

RKSV compliance, SCU-based signing, FinanzOnline registration

Spain (SIGN ES)

TicketBAI + Verifactu + SII from one API, XML invoice signing

Next steps

SIGN FR for SIGN DE customers

Detailed migration guide with step-by-step API calls

SIGN IT for SIGN DE customers

Detailed migration guide with step-by-step API calls

Integration Planning

Effort estimates, timelines, and compliance checklists

Was this page helpful?

The Unified API

Two API architectures

Which architecture should you use?

Unified API base URLs

Unified API headers

X-Api-Version

X-Idempotency-Key

X-Scope-Identifier

Resource model

Resource states

Records (the transaction model)

Terminology mapping (Unified API vs SIGN DE)

What changes per country

Integration walkthrough

Create Token

Create Organization::UNIT

Create Subject::API_KEY

Create scoped Token

Create Taxpayer

Commission Taxpayer

Create and commission Location

Create and commission System

Create Record::INTENTION

Create Record::TRANSACTION