Per Clienti SIGN DE

⚠️ Stai visualizzando la documentazione per la versione API 2025-08-12. La versione più recente è 2026-05-04. Le modifiche principali includono una terminologia aggiornata (Asset → Organization, Entity → Taxpayer/Location).

Guida all’integrazione di SIGN IT per clienti SIGN DE

Questa guida spiega le differenze principali rispetto a SIGN DE e ti supporta nell’integrazione dell’API fiskaly SIGN IT. Descrive tutti i passaggi necessari per te e per i tuoi commercianti.

Approccio API Unificato

SIGN IT fa parte dell’approccio API Unificato di fiskaly. Ciò significa che integrando SIGN IT, sei già pronto per utilizzare SIGN FR (Francia) e SIGN ES (Spagna), nonché altri paesi futuri, con uno sforzo aggiuntivo minimo.

A differenza di SIGN DE, SIGN IT non richiede un’Management API separata. Tutti gli endpoint necessari per l’autenticazione, la creazione di asset, la configurazione e la gestione dei record fiscali sono inclusi direttamente nella SIGN IT, rendendo l’integrazione più rapida e semplice.

Ambienti: TEST e LIVE

In SIGN IT esistono due URL base separate per i diversi ambienti:

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

Questo è diverso da SIGN DE, dove esiste una sola URL base utilizzata per entrambi gli ambienti.
In SIGN DE, la chiave API stessa determina se vengono create risorse TEST o LIVE.
Un token creato con una chiave API LIVE crea risorse LIVE.
Un token creato con una chiave API TEST crea risorse TEST — anche se l’URL rimane la stessa.

In SIGN IT, l’ambiente viene selezionato tramite l’URL base.
È necessario chiamare ogni endpoint con l’URL base corretta (test.api.fiskaly.com o live.api.fiskaly.com), a seconda che si voglia interagire con l’ambiente TEST o LIVE.

Parametri di Intestazione

Nell’approccio API Unificato, sono state introdotte nuove intestazioni HTTP per semplificare i processi.
Forniscono flessibilità, garantiscono l’integrità dei dati e rendono le integrazioni più semplici e affidabili.

X-Api-Version

Per tutte le soluzioni API Unificato, ogni richiesta deve includere l’intestazione X-Api-Version.
Il valore corrisponde alla data di rilascio della versione. Ciò ti dà il pieno controllo su quando passare a una versione più recente per utilizzare nuove funzionalità.

Puoi testare le modifiche prima nell’ambiente TEST e migrare alla nuova versione solo una volta verificato tutto. Questo ti consente anche di mantenere alcuni clienti su una versione precedente se necessario, mentre integri nuovi clienti direttamente con quella più recente.

Vantaggio principale: nessun breaking change nella versione in esecuzione.

X-Idempotency-Key

Poiché gli ID delle risorse non devono più essere definiti da te ma vengono generati dall’API, l’X-Idempotency-Key garantisce che una chiamata API venga gestita in modo idempotente.

Ciò significa che richieste identiche ripetute con lo stesso X-Idempotency-Key producono lo stesso risultato e impediscono creazioni duplicate.

L’X-Idempotency-Key è obbligatorio per tutte le richieste POST e PATCH.

X-Scope-Identifier

L’intestazione X-Scope-Identifier sostituisce i parametri di percorso precedentemente utilizzati nella Management API per stabilire relazioni tra risorse.

Rende le integrazioni più pulite e flessibili, poiché l’intestazione definisce esplicitamente l’ambito (ad esempio, a quale Asset::UNIT appartiene una chiave API).

Mappatura della Terminologia: SIGN IT vs. SIGN DE

SIGN IT	SIGN DE	Spiegazione
`Asset::TENANT`	(nessun equivalente)	Struttura di livello superiore nel fiskaly HUB. Rappresenta l’intero account cliente. Non può essere annidato in altri asset.
`Asset::GROUP` (opzionale)	`organisation` (con `billing_options`)	Livello intermedio opzionale utilizzato per organizzare più contribuenti in cluster logici.
`Asset::UNIT`	`managed_organization`	Rappresenta un singolo commerciante o contribuente. Ogni `Asset::UNIT` è collegato a un contribuente tramite una `Entity`.
`Entity::COMPANY` o `Entity::INDIVIDUAL`	In Germania parte della `managed_organization` (DSFINVK DE) o `taxpayer` (SUBMIT DE)	Definisce il contribuente per l’`Asset::UNIT` collegato, necessario per adempiere agli obblighi fiscali.
`Entity::LOCATION`	Comparabile: `establishment` (SUBMIT DE)	Rappresenta le sedi fisiche (ad esempio negozi) gestite dal contribuente.
`System::FISCAL_DEVICE`	`client`	Rappresenta il POS / registratore di cassa utilizzato per la fiscalizzazione.
`Subject::API_KEY`	`API key`	Oggetto di autenticazione della chiave API, utilizzato per autorizzare l’accesso.
`Record`	`transaction`	Rappresenta un’operazione eseguita sul registratore di cassa. Richiede sempre due chiamate: un `Record::INTENTION` e un `Record::TRANSACTION`.
`Record::INTENTION`	`Start-Transaction`	Segna l’inizio di un processo di acquisto, o un altro evento singolo elaborato sul registratore di cassa.
`Record::TRANSACTION`	`Finish-Transaction`	Segna il completamento (fine) di un processo di acquisto.

SIGN IT Passo per Passo

Prima Organizzazione

Per iniziare, devi creare un’organizzazione separata specificamente per l’Italia nel fiskaly HUB e una chiave API dedicata per l’integrazione italiana.

Da questo punto in poi, tutti i passaggi di integrazione vengono gestiti direttamente tramite la SIGN IT. A differenza di SIGN DE, non è più necessario utilizzare la Management per creare o gestire strutture organizzative. Tutte le funzionalità necessarie fanno parte della stessa SIGN IT.

POST: Creare Token

Utilizzare questo token per autenticare la creazione della struttura organizzativa per l’Italia.
Funziona allo stesso modo del token in SIGN DE (Management API), che veniva creato utilizzando la chiave API dell’organizzazione (principale) e poi usato per creare managed_organizations.
In SIGN IT, questo token è ora necessario per creare risorse Asset::UNIT.

POST: Creare Asset (UNIT)

Creare un Asset::UNIT (Asset di tipo Unit) che rappresenta il primo cliente. Questo equivale alla managed_organization creata tramite la Management utilizzata per SIGN DE.

In questo passaggio è richiesto solo il nome dell’Asset::UNIT.
A differenza di SIGN DE, le informazioni sul contribuente appartengono alla risorsa Entity, che può essere di tipo COMPANY o INDIVIDUAL, a seconda che il contribuente sia una persona giuridica o fisica. Questi dettagli vengono definiti nel passaggio Entity (COMPANY / INDIVIDUAL) sottostante.

POST: Creare Subject (Chiave API)

Ciascuno dei tuoi clienti richiede la propria chiave API per creare risorse nel proprio specifico ambito Asset::UNIT.
Per questo motivo, è necessario creare un Subject::API_KEY (Subject di tipo chiave API).

Collegare la chiave API all’Asset::UNIT utilizzando l’intestazione X-Scope-Identifier.

A differenza di SIGN DE, le informazioni su quale Unit appartiene la chiave API non vengono più fornite tramite il parametro di percorso, ma tramite il parametro di intestazione X-Scope-Identifier.
Questa intestazione deve contenere l’ID dell’Asset::UNIT a cui appartiene la chiave API.

POST: Creare Token (con ambito)

Questo token è limitato all’Asset::UNIT. Usarlo per tutte le operazioni specifiche del contribuente.

Con la chiave API precedentemente creata per l’Asset::UNIT, è necessario creare questo token con ambito.
Verrà utilizzato per tutte le operazioni che devono essere gestite all’interno di questo specifico Asset::UNIT.

POST: Creare Entity (COMPANY / INDIVIDUAL)

Definisce la rappresentazione del contribuente per il corrispondente Asset::UNIT.

Una Entity di tipo COMPANY o INDIVIDUAL rappresenta il contribuente — sia esso una persona giuridica (azienda) o una persona fisica (lavoratore autonomo).
Ogni contribuente deve essere creato come Entity prima che possano essere eseguite operazioni fiscali.

Poiché SIGN IT segue l’approccio API Unificato, la struttura Entity è progettata in modo standardizzato e divisa in due parti principali:

Informazioni generali (condivise tra tutti i paesi):
Include attributi comuni come nome e indirizzo del contribuente.
Informazioni di fiscalizzazione (sezione specifica per paese):
Contiene attributi fiscali richiesti dalle normative nazionali, come il numero di identificazione fiscale e le credenziali fiscali.
In Italia, questo include attributi fiscali come il codice fiscale (Codice Fiscale) e il numero di partita IVA (Partita IVA) richiesti dalle normative nazionali.

PATCH: Aggiornare Entity

Aggiornare lo stato da ACQUIRED a COMMISSIONED per attivare la Entity.

A differenza di SIGN DE, le Entity in SIGN IT hanno un attributo state.
Quando viene creata una Entity, il suo stato iniziale è ACQUIRED.
Prima di poter essere utilizzata, la Entity deve essere aggiornata allo stato COMMISSIONED.

Questo passaggio è irreversibile. Da questo punto, la risorsa diventa fatturabile secondo il modello di fatturazione applicabile.

Se una Entity non è più in uso, può essere aggiornata allo stato DECOMMISSIONED.
Anche questo passaggio è irreversibile e deve essere eseguito solo quando si è certi che il cliente non utilizzerà più questa Entity.

Oltre agli stati, ogni Entity in SIGN IT ha un attributo mode che ne definisce lo stato operativo.

Quando la Entity è nello stato ACQUIRED o DECOMMISSIONED, la sua modalità è sempre INACTIVE.
In questa modalità, la risorsa non può essere utilizzata.
Quando la Entity viene aggiornata allo stato COMMISSIONED, il servizio SIGN IT convalida automaticamente tutte le configurazioni richieste.
In caso di successo, la modalità passa a OPERATIVE.
Se si verifica un problema con la Entity o una delle sue risorse dipendenti, la modalità cambia automaticamente in DEGRADED (non ancora implementato) finché il problema non viene risolto.
Una volta risolto il problema, il servizio SIGN IT riporterà la modalità a OPERATIVE.
La modalità SUSPENDED può essere impostata manualmente per le Entity nello stato COMMISSIONED tramite l’endpoint updateEntity.
Questo è utile per sospendere temporaneamente le operazioni fiscali, ad esempio durante l’aggiornamento delle credenziali o la manutenzione. Se il servizio SIGN IT imposta la Entity in modalità DEGRADED (non ancora implementato) a causa di un problema che richiede l’intervento dell’utente, la modalità deve essere prima modificata in SUSPENDED mentre si eseguono le azioni necessarie, e poi aggiornata a OPERATIVE una volta risolto il problema.

Riepilogo:

INACTIVE: Modalità predefinita per ACQUIRED e DECOMMISSIONED
OPERATIVE: Modalità produttiva normale
DEGRADED (non ancora implementato): Impostata automaticamente dal servizio SIGN IT a causa di un problema
SUSPENDED: Modalità di manutenzione manuale

POST: Creare Entity (LOCATION)

Definisce la sede fisica dell’attività. Inizia anch’essa nello stato ACQUIRED.

Per ogni sede di un contribuente, è necessario creare una Entity separata di tipo LOCATION.
Nella soluzione SIGN IT, questo non richiede un Asset::UNIT separato.
Tutte le sedi di un contribuente sono rappresentate all’interno dello stesso Asset::UNIT e sono collegate alla corrispondente Entity::COMPANY o Entity::INDIVIDUAL.
Ogni contribuente (Entity::COMPANY o Entity::INDIVIDUAL) dovrebbe avere almeno una Entity::LOCATION associata.

PATCH: Aggiornare Entity (LOCATION)

Aggiornare lo stato della Entity::LOCATION a COMMISSIONED.

Come per Entity::COMPANY o Entity::INDIVIDUAL, anche la Entity::LOCATION deve essere aggiornata allo stato COMMISSIONED prima di poter essere utilizzata.
Solo dopo questo passaggio la sede diventa attiva e può essere utilizzata.

POST: Creare System

Un System di tipo FISCAL_DEVICE rappresenta un POS o un registratore di cassa.
Corrisponde al client in SIGN DE.
Ogni System è collegato a una Entity::LOCATION.

A differenza di SIGN DE, durante la creazione di un FISCAL_DEVICE, è necessario fornire informazioni aggiuntive sul sistema di registrazione elettronico stesso.
La maggior parte di questi dettagli è solitamente definita dal fornitore del POS.
In Germania, queste informazioni vengono generalmente aggiunte in seguito come parte del processo DSFinV-K DE o Submit DE — in SIGN IT, tuttavia, questo avviene in un unico passaggio durante la creazione del sistema.

PATCH: Aggiornare System

Aggiornare il System dallo stato ACQUIRED a COMMISSIONED per attivarlo.

La risorsa System segue la stessa logica di stato e modalità di una Entity.
Una volta impostato su COMMISSIONED, il sistema diventa attivo e la fatturazione si applica automaticamente (quando utilizzato nell’ambiente LIVE).
Se non è più in uso, può essere impostato su DECOMMISSIONED, che — come in SIGN IT in generale — è irreversibile.

L’attributo mode riflette la condizione operativa del sistema (ad esempio OPERATIVE, SUSPENDED o DEGRADED). DEGRADED non è ancora implementato. Queste modalità si comportano allo stesso modo descritto per Entity, consentendo di sospendere temporaneamente le operazioni o di indicare automaticamente prestazioni degradate a causa di problemi di configurazione.

Configurazione Completata

Con il System messo in funzione con successo, la fase di configurazione iniziale è completata.
Tutte le strutture organizzative e fiscali — dall’Asset::UNIT alla Entity fino al System — sono ora attive e pronte per la produzione.

Da questo punto in poi, i passaggi seguenti descrivono le operazioni fiscali quotidiane eseguite al POS.
Ciò include la creazione e l’elaborazione di record fiscali che rappresentano vendite, resi e altri eventi — equivalenti alle transazioni in SIGN DE, ma con dati fiscali estesi come richiesto in Italia.

Operazioni Quotidiane al POS

Una volta completata la configurazione e tutte le risorse messe in funzione, il processo di fiscalizzazione in SIGN IT continua con le operazioni quotidiane.
Queste operazioni rappresentano le attività commerciali quotidiane al POS — come l’emissione di ricevute, l’elaborazione di resi o la gestione di annullamenti.

Sebbene il concetto generale sia simile a SIGN DE, SIGN IT introduce un modello di Record unificato e più ricco di dati.
Ogni transazione è rappresentata come uno o più Record, che vengono firmati digitalmente, registrati nel journal e archiviati per garantire la piena conformità fiscale.

Le seguenti sezioni descrivono come creare, elaborare e gestire questi Record nell’ambiente fiscale italiano.

POST: Creare Record

In SIGN IT, ogni transazione fiscale è rappresentata come uno o più Record.
Questo modello sostituisce il processo di aggiornamento delle transazioni in due passaggi di SIGN DE (ACTIVE → FINISHED) con due risorse indipendenti: un Record di tipo INTENTION e un altro di tipo TRANSACTION.

Parte A) INTENTION

In SIGN DE, una transazione inizia con un evento Start-Transaction che segna l’inizio di un processo fiscale e viene successivamente aggiornata a uno stato completato.
In SIGN IT, questa logica è sostituita da una risorsa dedicata: un Record di tipo INTENTION.

Un Record di tipo INTENTION segna l’inizio di un’operazione fiscale.
In Italia, l’operazione di intenzione supportata è TRANSACTION.

Contiene informazioni contestuali che definiscono l’intenzione dell’operazione, tra cui:

Il System (System::FISCAL_DEVICE) che esegue l’operazione.
Il tipo di operazione, corrispondente alla TRANSACTION.

Parte B) TRANSACTION

In SIGN DE, una transazione viene finalizzata tramite un aggiornamento Finish-Transaction della risorsa transazione che completa il processo fiscale.
In SIGN IT, questo passaggio è rappresentato da una risorsa separata: un Record di tipo TRANSACTION.

Un Record di tipo TRANSACTION completa l’operazione fiscale e fa riferimento al Record di tipo INTENTION precedentemente creato.
Contiene tutti i dati fiscali e transazionali necessari per l’operazione.
Rispetto a SIGN DE, l’ambito e la struttura dei dati sono più ampi e più strettamente allineati alle informazioni contenute in una transazione all’interno di una chiusura di cassa (Kassenabschluss) in DSFinV-K DE.

Include:

Informazioni sul documento come numero del documento, data e importi lordi e netti totali.
Dettagli per ogni riga di vendita (beni o servizi), inclusa descrizione, quantità, aliquota IVA e importo.
Riferimenti a ricevute precedenti durante la creazione di record di CORRECTION o CANCELLATION.

Questo tipo di Record fornisce la rappresentazione fiscale completa della transazione come richiesto dalla normativa italiana.

Stati e Modalità di Registrazione

Ogni Record in SIGN IT (che si tratti di INTENTION, TRANSACTION o altri tipi) segue il proprio state e mode, che riflette il suo ciclo di vita all’interno del processo di fiscalizzazione.

Stati

Accepted – Il Record è stato ricevuto, validato ed è pronto per l’elaborazione.
Rejected – Il Record è stato ricevuto ma non ha superato i controlli di validazione interni. I dettagli sono disponibili nei messaggi di registro.
Completed – Il Record è stato elaborato con successo.
Failed – Il Record non ha potuto essere elaborato a causa di un errore di trasmissione esterno. I dettagli sono disponibili nei messaggi di registro.

Modalità

Processing – Il Record è attualmente in fase di elaborazione.
Finished – Il Record è stato elaborato, con esito positivo o negativo.

Transizioni

Transizione	Descrizione
POST → Accepted	Il Record viene creato ed entra temporaneamente nello stato `Accepted` se la validazione ha esito positivo, procedendo immediatamente al passaggio successivo.
POST → Rejected	Il Record non supera la validazione interna e transisce automaticamente a `Rejected`, fornendo registri degli errori.
Accepted → Completed	Impostato automaticamente quando l’elaborazione si conclude con successo.
Accepted → Failed	Impostato quando l’elaborazione fallisce a causa di un componente esterno.
Processing → Finished	Indica che l’elaborazione è stata completata, indipendentemente dal successo o dall’insuccesso.

Questo design basato su eventi consente di tracciare ogni operazione fiscale in modo indipendente — senza aggiornare la stessa risorsa — garantendo una traccia di audit trasparente e immutabile per ogni transazione.

Riepilogo

Nelle operazioni quotidiane, SIGN IT sostituisce il semplice flusso di transazioni “Inizio → Fine” di SIGN DE con un modello di Record multi-risorsa e basato su eventi.
Ogni operazione — sia essa una vendita (RECEIPT), un reso (CORRECTION) o una cancellazione (CANCELLATION) — viene firmata, registrata e archiviata individualmente, garantendo la completa tracciabilità e la conformità alla legislazione fiscale italiana.

Was this page helpful?