L'API Unificata

L’API Unificata di fiskaly è una singola architettura di integrazione che copre più paesi. Integrarla una volta per la Francia o l’Italia, e aggiungere il paese successivo significa cambiare lo schema del payload — non riscrivere l’integrazione.

Questa pagina documenta come funziona l’API Unificata, com’è il suo modello di risorse e come differisce dalle API Specializzate (SIGN DE, SIGN AT, SIGN ES).

Due architetture API

fiskaly fornisce due architetture API. Entrambe sono completamente supportate e mantenute attivamente:

	API Unificata	API Specializzate
Paesi	Francia (SIGN FR), Italia (SIGN IT), Svezia (in arrivo)	Germania (SIGN DE), Austria (SIGN AT), Spagna (SIGN ES)
URL di base	test.api.fiskaly.com / live.api.fiskaly.com	Specifici per prodotto (es. kassensichv.fiskaly.com)
Gestione org	Integrata nell’API del prodotto	Management API separata (management.fiskaly.com)
ID delle risorse	Generati dal server (usa X-Idempotency-Key)	UUID generati dal client
Controllo versione	Header X-Api-Version (basato su data, nessun breaking change)	Nessun header di versione (possibili breaking change)
Scope delle risorse	Header X-Scope-Identifier	Parametri di percorso
Terminologia	Organization, Taxpayer, Location, System, Record	TSS, client, transaction (varia per prodotto)
Aggiungere un paese	Cambiare lo schema payload nello stesso modello di risorse	Integrare un’API separata con endpoint diversi

📘Nessuna architettura è legacy

Le API Specializzate sono costruite appositamente per le normative specifiche del loro paese. SIGN DE è il prodotto più maturo di fiskaly con oltre 10.000 integrazioni e certificazione BSI valida fino al 2033. L’API Unificata è l’architettura che fiskaly ha costruito per un’espansione multi-paese efficiente.

Quale architettura dovresti usare?

Scenario	Raccomandazione
Hai bisogno solo della Germania	SIGN DE (API Specializzata)
Hai bisogno solo dell’Austria	SIGN AT (API Specializzata)
Hai bisogno solo della Spagna	SIGN ES (API Specializzata)
Hai bisogno solo della Francia o dell’Italia	API Unificata
Hai bisogno di Francia + Italia (o + Svezia)	API Unificata — integra una volta, aggiungi paesi tramite schema payload
Hai bisogno di Germania + Francia	Entrambe — SIGN DE (Specializzata) + SIGN FR (Unificata). Stesso schema auth, modelli di risorse diversi.
Stai iniziando da zero e pianifichi 3+ paesi	Inizia con l’API Unificata per FR/IT, aggiungi API Specializzate per DE/AT/ES secondo necessità

URL di base dell’API Unificata

L’API Unificata usa URL di base separati per ogni ambiente:

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

Questo è diverso dalle API Specializzate (es. SIGN DE), dove viene usato un singolo URL di base e la chiave API determina l’ambiente.

Header dell’API Unificata

Ogni richiesta all’API Unificata include questi header:

X-Api-Version

Obbligatorio in ogni richiesta. Il valore è la data di rilascio della versione API che stai usando (es. 2026-02-03).

X-Api-Version: 2026-02-03

Questo ti dà pieno controllo su quando adottare una nuova versione. Puoi:

• Testare una nuova versione in TEST prima di migrare LIVE
• Eseguire clienti diversi su versioni diverse simultaneamente
• Garantire nessun breaking change all’interno di una versione bloccata

X-Idempotency-Key

Obbligatorio in tutte le richieste POST e PATCH. Poiché gli ID delle risorse sono generati dal server (non forniti dal client come in SIGN DE), questo header garantisce che le richieste ripetute non creino risorse duplicate.

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

Usa un UUIDv4 o UUIDv3 fresco per ogni operazione distinta. Usa una nuova chiave quando riprovi una richiesta fallita.

X-Scope-Identifier

Usato per stabilire relazioni tra risorse. Sostituisce i parametri di percorso usati nelle Management API e nelle API Specializzate.

X-Scope-Identifier: organization-unit-id

Ad esempio, quando si crea una chiave API per una specifica Organization::UNIT, l’header X-Scope-Identifier contiene l’ID dell’Unità invece di codificarlo nel percorso URL.

Modello di risorse

L’API Unificata usa una gerarchia di risorse standardizzata in tutti i paesi:

Organization::ACCOUNT       ← La tua azienda (livello superiore, gestita nell'HUB)
  │
  └── Organization::GROUP   ← Cluster logico (regione, brand, franchising)
        │
        └── Organization::UNIT   ← Singolo commerciante / contribuente
              │
              ├── Subject::API_KEY   ← Credenziali API per questa unità
              │
              ├── Taxpayer (COMPANY o INDIVIDUAL)
              │     │
              │     ├── Informazioni generali (nome, indirizzo — condivisi tra paesi)
              │     │
              │     └── Informazioni fiscalizzazione (specifiche per paese: SIREN per FR,
              │         Codice Fiscale per IT, ecc.)
              │
              ├── Location   ← Sede fisica dell'attività (negozio, punto vendita)
              │
              └── System::FISCAL_DEVICE   ← Terminale POS / registratore di cassa

Stati delle risorse

Ogni risorsa principale (Taxpayer, Location, System) segue la stessa macchina a stati:

ACQUIRED ──→ COMMISSIONED ──→ DECOMMISSIONED
(creata)       (attiva)          (dismessa)

• ACQUIRED — la risorsa è creata ma non ancora attiva. Modalità: INACTIVE.
• COMMISSIONED — la risorsa è attiva e pronta per la produzione. Modalità: OPERATIVE. Questa transizione è irreversibile e avvia la fatturazione.
• DECOMMISSIONED — la risorsa è permanentemente dismessa. Modalità: INACTIVE. Anche irreversibile.

Modalità operative all’interno dello stato COMMISSIONED:

Modalità	Significato	Impostata da
OPERATIVE	Operazione normale	Automatica (alla commissione o dopo la risoluzione del problema)
DEGRADED	Problema rilevato	Automatica (dal servizio)
SUSPENDED	Pausa di manutenzione	Manuale (da te, tramite API)

Record (il modello di transazione)

Nell’API Unificata, le transazioni sono chiamate Record e usano un modello a due passi:

1. Record::INTENTION — segna l’inizio di un’operazione fiscale (equivalente a Start-Transaction in SIGN DE)
2. Record::TRANSACTION — completa l’operazione fiscale con payload completo (equivalente a Finish-Transaction in SIGN DE)

Tipi di operazioni aggiuntivi supportati solo tramite Record::INTENTION (nessuna controparte TRANSACTION necessaria):

• EVENT — eventi di sistema (modalità formazione, operazioni di test, riavvii)
• DUPLICATE — duplicato di un documento fiscale esistente
• EXPORT — generazione di esportazione dati fiscali

📘Non tutte le operazioni sono disponibili in ogni paese

La Francia supporta le intenzioni TRANSACTION, EVENT, DUPLICATE ed EXPORT. L’Italia supporta attualmente solo TRANSACTION. Consulta la documentazione specifica del paese per l’elenco completo.

Mappatura della terminologia (API Unificata vs SIGN DE)

Se vieni da un’integrazione SIGN DE, questa tabella mappa i concetti:

API Unificata	SIGN DE	Spiegazione
Organization::ACCOUNT	(nessun equivalente)	Struttura di livello superiore nell’HUB
Organization::GROUP	organization	Organizzazione principale sotto cui sono annidate le entità contribuente
Organization::UNIT	managed_organization	Singolo commerciante. Collegato a un Taxpayer.
Taxpayer (COMPANY/INDIVIDUAL)	Parte di managed_organization o taxpayer (SUBMIT DE)	L’entità fiscale
Location	establishment (SUBMIT DE)	Sede fisica dell’attività
System::FISCAL_DEVICE	client	Terminale POS / registratore di cassa
Subject::API_KEY	API key	Credenziali di autenticazione
Record	transaction	Un’operazione fiscale
Record::INTENTION	Start-Transaction	Segna l’inizio di un acquisto
Record::TRANSACTION	Finish-Transaction	Completa l’acquisto con i dati fiscali completi

Cosa cambia per paese

La proposta di valore dell’API Unificata è che la maggior parte dell’integrazione è condivisa. Ecco cosa rimane uguale e cosa differisce:

Condiviso in tutti i paesi dell’API Unificata	Specifico per paese
Autenticazione (POST /tokens)	Sezione fiscalization del Taxpayer (es. SIREN per FR; Codice Fiscale, P.IVA e credenziali per IT)
Gerarchia organizzativa (ACCOUNT > GROUP > UNIT)	Schema payload del Record (struttura ricevuta, gestione IVA, tipi di documento)
Header (X-Api-Version, X-Idempotency-Key, X-Scope-Identifier)	Operazioni di intention supportate (FR ha EVENT/DUPLICATE/EXPORT; IT ha solo TRANSACTION)
Ciclo di vita delle risorse (ACQUIRED > COMMISSIONED > DECOMMISSIONED)	Requisiti normativi (certificazione NF525 per FR, lotteria degli scontrini per IT)
Gestione stato e modalità (OPERATIVE, DEGRADED, SUSPENDED)	Gestione delle perdite di connessione (protocolli diversi per paese)
URL di base (test.api.fiskaly.com / live.api.fiskaly.com)	—

Sforzo tipico per aggiungere un secondo paese dell’API Unificata: ~1 settimana per un team già integrato con il primo paese. Si adatta la sezione fiscalizzazione del Taxpayer e lo schema payload del Record — tutto il resto è riutilizzabile.

Procedura di integrazione

Ecco il flusso di configurazione completo per un paese dell’API Unificata (usando SIGN FR come esempio). Il flusso è identico per SIGN IT.

1. Creare il Token

   POST /tokens con la tua chiave e il tuo segreto API (come per tutti i prodotti fiskaly). Questo token viene usato per creare la struttura organizzativa.

2. Creare Organization::UNIT

   POST /organizations con X-Idempotency-Key. Solo il nome è richiesto in questo punto. Rappresenta il tuo cliente (commerciante).

3. Creare Subject::API_KEY

   POST /subjects con X-Scope-Identifier impostato all’ID Organization::UNIT. Ogni cliente ha bisogno della propria chiave API.

4. Creare un Token con scope

   POST /tokens usando la chiave API del cliente. Questo token con scope viene usato per tutte le operazioni specifiche del contribuente.

5. Creare il Taxpayer

   POST /taxpayers con informazioni generali (nome, indirizzo) e la sezione fiscalization specifica per paese (es. numero SIREN per la Francia, Codice Fiscale, P.IVA e credenziali per IT).

6. Commissionare il Taxpayer

   PATCH /taxpayers/{id} — aggiorna lo stato da ACQUIRED a COMMISSIONED. Questo è irreversibile e attiva la fatturazione.

7. Creare e commissionare la Location

   POST /locations poi PATCH /locations/{id} per commissionare. Rappresenta una sede fisica dell’attività.

8. Creare e commissionare il System

   POST /systems poi PATCH /systems/{id} per commissionare. Rappresenta un terminale POS. In SIGN FR, fornisci anche i dettagli del sistema di conservazione elettronica in questo passaggio.

9. Creare Record::INTENTION

   POST /records con tipo di operazione (es. TRANSACTION) e l’ID del System. Questo avvia l’operazione fiscale.

10. Creare Record::TRANSACTION

    POST /records facendo riferimento al record INTENTION. Contiene il payload fiscale completo (articoli, importi, IVA, metodi di pagamento). La risposta include la firma crittografica.

Nessuna Management API separata

A differenza delle API Specializzate (SIGN DE, SIGN AT, SIGN ES), l’API Unificata non richiede la Management API (management.fiskaly.com). Tutta la gestione delle organizzazioni, la creazione di chiavi API e la configurazione vengono gestite direttamente nell’API del prodotto.

Questo significa meno superfici API da integrare, meno credenziali da gestire e un’architettura complessivamente più semplice.

Paesi sull’API Unificata

Francia (SIGN FR)

Certificazione NF525, chiusure di periodo, replay offline, archivi

Italia (SIGN IT)

API cloud per la trasmissione di scontrini fiscali all'autorità fiscale italiana (AdE).

Svezia (SIGN SE)

InfraSec TCS — attualmente in fase di integrazione nell'API Unificata

Paesi sulle API Specializzate

Germania (SIGN DE)

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

Austria (SIGN AT)

Conformità RKSV, firma basata su SCU, registrazione FinanzOnline

Spagna (SIGN ES)

TicketBAI + Verifactu + SII da un'unica API, firma fatture XML

Prossimi passi

SIGN FR per clienti SIGN DE

Guida di migrazione dettagliata con chiamate API passo per passo

SIGN IT per clienti SIGN DE

Guida di migrazione dettagliata con chiamate API passo per passo

Pianificazione dell'integrazione

Stime dello sforzo, timeline e checklist di conformità