Core Concepts

Before integrating any fiskaly product, it helps to understand the platform’s building blocks. These concepts apply across all countries and products.

Organizations

fiskaly uses a hierarchical organization model to represent your business structure:

🏢

Account

Your top-level entity. Created when you register on the HUB. Represents the POS provider or retailer.

📂

Group

An intermediate level that lets you cluster multiple units. Useful for organizing by region or brand.

🏪

Unit

Represents a single merchant or legal entity. Each unit has its own taxpayer data and fiscal resources.

In newer APIs (SIGN PT, SIGN IT, SIGN FR, E-Invoice), these are called GROUP and UNIT organization types. In SIGN DE, managed organizations serve the same purpose.

Environments

Every fiskaly account has two isolated environments:

Environment	Purpose	Data
TEST	Integration development and testing	Simulated — no connection to tax authorities
LIVE	Production operations	Real — transactions are reported to tax authorities

⚠️LIVE is permanent

Records created in the LIVE environment are legally binding and transmitted to tax authorities. Always develop and test in the TEST environment first.

API keys generated in TEST create TEST resources; keys generated in LIVE create LIVE resources. The two environments are completely separate — there is no data sharing between them.

Authentication

All fiskaly APIs use JWT-based authentication:

POST /auth  (or POST /tokens)
  { "api_key": "...", "api_secret": "..." }
    → { "access_token": "...", "refresh_token": "..." }

Token	Lifetime	Usage
access_token	24 hours	Include as Authorization: Bearer <token> in all API requests
refresh_token	48 hours	Use to obtain a new access token without re-authenticating

💡Cache your tokens

Do not re-authenticate on every request. Cache the access token and only refresh when you receive a 401 response. Re-authenticating on every call adds unnecessary latency to your checkout process.

Scoped Authentication (SIGN PT, SIGN IT, SIGN FR, E-Invoice)

Newer APIs use additional headers to scope requests to a specific organization:

Header	Purpose
Authorization: Bearer <token>	Authentication
X-Api-Version: 2026-02-03	API version selection
X-Scope-Identifier: <org_id>	Scope requests to a specific organization unit
X-Idempotency-Key: <uuid>	Ensure write operations are idempotent

Resource Model

While the exact resources vary by country, most fiskaly products follow a common pattern:

Account / Group
  └── Unit (Organization)
        └── Taxpayer
              └── Location (Branch / Head Office)
                    └── System (Fiscal Device / POS)
                          └── Record / Transaction

Resource Lifecycle

Most resources follow a state machine:

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

• ACQUIRED: Resource is created but not yet active
• COMMISSIONED: Resource is active and can process transactions
• DECOMMISSIONED: Resource is retired and no longer accepts new operations

In SIGN DE, the equivalent states are CREATED → INITIALIZED → DISABLED.

Country-Specific Resources

Concept	Germany (SIGN DE)	Austria (SIGN AT)	Spain (SIGN ES)	Italy (SIGN IT)	Portugal (SIGN PT)	France (SIGN FR)	Sweden (SIGN SE)
Signing unit	TSS	SCU	Signer	System	System	System	System
POS terminal	Client	Cash Register	Client	System	System	System	System
Fiscal record	Transaction	Receipt	Invoice	Record	Record	Record	Record
Tax authority	BSI / BZSt	FinanzOnline	AEAT / Basque DFAs	AdE (Agenzia delle Entrate)	AT (Autoridade Tributária e Aduaneira)	DGFiP	Skatteverket

Base URLs

Each product has its own API endpoint. See the Base URLs & Environments reference for a complete list.

Product	Test Environment	Live Environment
SIGN DE	kassensichv-middleware.fiskaly.com/api/v2	kassensichv.fiskaly.com/api/v2
SIGN AT	rksv.fiskaly.com/api/v1	rksv.fiskaly.com/api/v1
SIGN ES	test.es.sign.fiskaly.com/api/v1	live.es.sign.fiskaly.com/api/v1
SIGN IT	test.api.fiskaly.com	live.api.fiskaly.com
SIGN FR	test.api.fiskaly.com	live.api.fiskaly.com
SIGN PT	test.api.fiskaly.com	live.api.fiskaly.com
SIGN SE	test.api.fiskaly.com	live.api.fiskaly.com

What’s Next?

Quick Start

Make your first API call in under 5 minutes

Authentication Reference

Detailed auth guide with token refresh flows

Error Codes

Understand and troubleshoot API errors