Cross-Product Resource Mapping
This reference shows how key concepts map across fiskaly’s API architectures. Use it when migrating between products or integrating multiple countries.
Resource Mapping Table
Section titled “Resource Mapping Table”| Concept | SIGN DE (Specialized) | Unified API (FR/IT) | Management API |
|---|---|---|---|
| Top-level entity | Organization (via HUB) | Organization GROUP | Organization |
| Business unit | Managed Organization | Organization UNIT | Managed Organization |
| Signing device | TSS (Technical Security System) | System FISCAL_DEVICE | — |
| POS terminal | Client | — (implicit via System) | — |
| Transaction | Transaction (PUT with state) | Record (Intention → Transaction) | — |
| Tax entity | — (via SUBMIT DE) | Taxpayer (COMPANY / INDIVIDUAL) | — |
| Location | — (via DSFinV-K) | Location BRANCH | — |
| Credentials | API Key + Secret (HUB) | Subject API_KEY (API) | API Key (HUB) |
| Auth endpoint | POST /api/v2/auth | POST /api/v1/auth/token | POST /api/v0/auth |
| Resource IDs | Client-generated UUID | Server-generated | Client-generated UUID |
| Idempotency | PUT with UUID in URL | X-Idempotency-Key header | PUT with UUID in URL |
Lifecycle States
Section titled “Lifecycle States”Resources in each architecture follow different state machines:
SIGN DE — TSS States
Section titled “SIGN DE — TSS States”UNINITIALIZED → INITIALIZED → DISABLED- Must set Admin PIN and authenticate before initialization
- Cannot be re-enabled once disabled
Unified API — Resource States
Section titled “Unified API — Resource States”ACQUIRED → COMMISSIONED → DECOMMISSIONEDApplies to: Taxpayer, Location, System
- Resources are created in
ACQUIREDstate - Must be updated to
COMMISSIONEDbefore operational use DECOMMISSIONEDis terminal
SIGN DE — Transaction States
Section titled “SIGN DE — Transaction States”ACTIVE (revision 1) → FINISHED (revision 2)Unified API — Record Flow
Section titled “Unified API — Record Flow”INTENTION → TRANSACTION- Two separate API calls required
- Transaction references the Intention by ID
Setup Sequence Comparison
Section titled “Setup Sequence Comparison”SIGN DE (Germany)
Section titled “SIGN DE (Germany)”- Create Organization (HUB)
- Generate API Key (HUB)
- Authenticate (
POST /auth) - Create TSS (
PUT /tss/{id}) - Initialize TSS (Admin PIN → Auth → State change)
- Create Client (
PUT /tss/{id}/client/{id}) - Create Transaction (
PUT /tss/{id}/tx/{id})
Unified API (France/Italy)
Section titled “Unified API (France/Italy)”- Register on HUB
- Create Organization
GROUP(HUB) - Generate API Key (HUB)
- Create Token (
POST /auth/token) - Create Organization
UNIT - Create Subject
API_KEY - Create Token (for UNIT)
- Create Taxpayer → Commission
- Create Location → Commission
- Create System → Commission
- Create Record (Intention → Transaction)
📘More steps, more structure
The Unified API has more setup steps because it includes organization management (GROUP/UNIT hierarchy), taxpayer data, and location tracking directly in the product API — features that SIGN DE handles through separate products (Management API, SUBMIT DE, DSFinV-K).
Key Differences
Section titled “Key Differences”| Aspect | Specialized APIs | Unified API |
|---|---|---|
| Base URLs | Per-product (e.g., kassensichv.fiskaly.com) | Shared (test.api.fiskaly.com) |
| Org management | Via Management API + HUB | Built into product API |
| Resource creation | PUT with client-generated UUID | POST with server-generated ID |
| Versioning | URL path (/api/v2) | Header (X-Api-Version: 2026-02-03) |
| Scoping | Implicit (via auth token) | Explicit (X-Scope-Identifier header) |
| Transaction model | Single resource with state changes | Two-step: Intention then Transaction |
Related Resources
Section titled “Related Resources”Was this page helpful?