Mappatura delle risorse tra prodotti

Questo riferimento mostra come i concetti chiave si mappano tra le architetture API di fiskaly. Usalo quando migri tra prodotti o integri più paesi.

Tabella di mappatura delle risorse

Concetto	SIGN DE (Specializzata)	API Unificata (FR/IT)	Management API
Entità di livello superiore	Organizzazione (tramite HUB)	Organizzazione GROUP	Organizzazione
Unità aziendale	Organizzazione gestita	Organizzazione UNIT	Organizzazione gestita
Dispositivo di firma	TSS (Technical Security System)	System FISCAL_DEVICE	—
Terminale POS	Client	— (implicito tramite System)	—
Transazione	Transaction (PUT con stato)	Record (Intention → Transaction)	—
Entità fiscale	— (tramite SUBMIT DE)	Taxpayer (COMPANY / INDIVIDUAL)	—
Sede	— (tramite DSFinV-K)	Location BRANCH	—
Credenziali	Chiave API + Segreto (HUB)	Subject API_KEY (API)	Chiave API (HUB)
Endpoint auth	POST /api/v2/auth	POST /api/v1/auth/token	POST /api/v0/auth
ID delle risorse	UUID generato dal client	Generato dal server	UUID generato dal client
Idempotenza	PUT con UUID nell’URL	Header X-Idempotency-Key	PUT con UUID nell’URL

Stati del ciclo di vita

Le risorse in ciascuna architettura seguono macchine a stati diverse:

SIGN DE — Stati del TSS

UNINITIALIZED → INITIALIZED → DISABLED

• È necessario impostare il PIN Admin e autenticarsi prima dell’inizializzazione
• Non può essere riabilitato una volta disabilitato

API Unificata — Stati delle risorse

ACQUIRED → COMMISSIONED → DECOMMISSIONED

Si applica a: Taxpayer, Location, System

• Le risorse vengono create in stato ACQUIRED
• Devono essere aggiornate a COMMISSIONED prima dell’uso operativo
• DECOMMISSIONED è terminale

SIGN DE — Stati della transazione

ACTIVE (revisione 1) → FINISHED (revisione 2)

API Unificata — Flusso dei Record

INTENTION → TRANSACTION

• Sono richieste due chiamate API separate
• La Transaction fa riferimento all’Intention tramite ID

Confronto della sequenza di configurazione

SIGN DE (Germania)

1. Crea Organizzazione (HUB)
2. Genera Chiave API (HUB)
3. Autenticati (POST /auth)
4. Crea TSS (PUT /tss/{id})
5. Inizializza TSS (PIN Admin → Auth → Cambio stato)
6. Crea Client (PUT /tss/{id}/client/{id})
7. Crea Transaction (PUT /tss/{id}/tx/{id})

API Unificata (Francia/Italia)

1. Registrati sull’HUB
2. Crea Organizzazione GROUP (HUB)
3. Genera Chiave API (HUB)
4. Crea Token (POST /auth/token)
5. Crea Organizzazione UNIT
6. Crea Subject API_KEY
7. Crea Token (per UNIT)
8. Crea Taxpayer → Commissiona
9. Crea Location → Commissiona
10. Crea System → Commissiona
11. Crea Record (Intention → Transaction)

📘Più passi, più struttura

L’API Unificata ha più passi di configurazione perché include la gestione delle organizzazioni (gerarchia GROUP/UNIT), i dati del contribuente e il tracciamento delle sedi direttamente nell’API del prodotto — funzionalità che SIGN DE gestisce tramite prodotti separati (Management API, SUBMIT DE, DSFinV-K).

Differenze chiave

Aspetto	API Specializzate	API Unificata
URL di base	Per prodotto (es. kassensichv.fiskaly.com)	Condiviso (test.api.fiskaly.com)
Gestione org	Tramite Management API + HUB	Integrata nell’API del prodotto
Creazione risorse	PUT con UUID generato dal client	POST con ID generato dal server
Versioning	Percorso URL (/api/v2)	Header (X-Api-Version: 2026-02-03)
Scope	Implicito (tramite token auth)	Esplicito (header X-Scope-Identifier)
Modello transazione	Singola risorsa con cambi di stato	Due passi: Intention poi Transaction

Risorse correlate

Panoramica API Unificata

Confronto completo delle due architetture API

Configurazione SIGN DE

Guida passo per passo per la fiscalizzazione tedesca

Configurazione SIGN FR

Guida passo per passo per la fiscalizzazione francese