Per i Clienti di SIGN DE

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

Guida all’Integrazione SIGN IT per i Clienti di SIGN DE

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

Approccio API Unificata

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

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

Ambienti: TEST e LIVE

In SIGN IT, ci sono 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 c’è solo un URL base utilizzato per entrambi gli ambienti.
In SIGN DE, la stessa chiave API 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 lo stesso.

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

Parametri di Intestazione

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

X-Api-Version

Per tutte le soluzioni API Unificata, ogni richiesta deve includere l’intestazione X-Api-Version.
Il valore corrisponde alla data di rilascio della versione. Questo ti dà 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 che tutto è stato verificato. Questo ti consente anche di mantenere alcuni clienti su una versione precedente se necessario, mentre i nuovi clienti vengono direttamente onboardati con la più recente.

Vantaggio principale: nessun ulteriore cambiamento dirompente nella tua versione attiva.

X-Idempotency-Key

Poiché gli ID delle risorse non devono più essere definiti da te ma vengono generati dall’API, il 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 prevengono creazioni duplicate.

Il 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 nell’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 usato 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 di `managed_organization` (DSFINVK DE) o `taxpayer` (SUBMIT DE)	Definisce il contribuente per l’`Asset::UNIT` collegato, necessario per adempiere agli obblighi fiscali.
`Entity::LOCATION`	Paragonabile: `establishment` (SUBMIT DE)	Rappresenta la/le sede/i fisica/e (ad es. negozi) gestita/e dal contribuente.
`System::FISCAL_DEVICE`	`client`	Rappresenta il POS / sistema 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 singolo altro evento che viene elaborato sul registratore di cassa.
`Record::TRANSACTION`	`Finish-Transaction`	Segna il completamento di un processo di acquisto.

SIGN IT Passo dopo 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 SIGN IT. A differenza di SIGN DE, non è più necessario utilizzare Management per creare o gestire strutture organizzative. Tutte le funzionalità necessarie fanno parte di SIGN IT stesso.

POST: Creare Token

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

POST: Creare Asset (UNIT)

Crea un Asset::UNIT (Asset di tipo Unit) che rappresenta il tuo primo cliente. Questo equivale alla managed_organization creata tramite Management 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. Definirai questi dettagli nel passaggio Entity (COMPANY / INDIVIDUAL) di seguito.

POST: Creare Subject (Chiave API)

Ciascuno dei tuoi clienti richiede la propria Chiave API per creare risorse all’interno del proprio specifico ambito Asset::UNIT.
Per questo motivo, deve essere creato un Subject::API_KEY (Subject di tipo Chiave API).

Collega la tua Chiave API all’Asset::UNIT usando 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. Usalo per tutte le operazioni specifiche del contribuente.

Con la Chiave API creata in precedenza per l’Asset::UNIT, devi 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 un’entità giuridica (azienda) che 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 Unificata, la struttura di Entity è progettata in modo standardizzato e divisa in due parti principali:

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

PATCH: Aggiornare Entity

Aggiorna lo stato da ACQUIRED a COMMISSIONED per attivare l’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 che possa essere utilizzata, la Entity deve essere aggiornata allo stato COMMISSIONED.

Questo passaggio è irreversibile. Da questo punto in poi, 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 dovrebbe 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 definisce il suo stato operativo.

Quando la Entity è nello stato ACQUIRED o DECOMMISSIONED, il suo modo è sempre INACTIVE.
In questo modo, 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, il modo passa a OPERATIVE.
Se c’è un problema con la Entity o una delle sue risorse dipendenti, il modo cambia automaticamente a DEGRADED (non ancora implementato) fino a quando il problema non viene risolto.
Una volta risolto il problema, il servizio SIGN IT riporterà il modo a OPERATIVE.
Il modo SUSPENDED può essere impostato manualmente per le Entity nello stato COMMISSIONED usando l’endpoint updateEntity.
Questo è utile per sospendere temporaneamente le operazioni fiscali, ad esempio quando si aggiornano le credenziali o si esegue manutenzione. Se il servizio SIGN IT imposta la Entity in modo DEGRADED (non ancora implementato) a causa di un problema che richiede l’intervento dell’utente, il modo deve prima essere cambiato a SUSPENDED mentre si eseguono le azioni necessarie, e poi riportato a OPERATIVE una volta risolto il problema.

Riepilogo:

INACTIVE: Modo predefinito per ACQUIRED e DECOMMISSIONED
OPERATIVE: Modo produttivo normale
DEGRADED (non ancora implementato): Impostato automaticamente dal servizio SIGN IT a causa di un problema
SUSPENDED: Modo 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, deve essere creata 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) deve avere almeno una Entity::LOCATION associata.

PATCH: Aggiornare Entity (LOCATION)

Aggiorna lo stato dell’Entity::LOCATION a COMMISSIONED.

Come per Entity::COMPANY o Entity::INDIVIDUAL, anche l’Entity::LOCATION deve essere aggiornata allo stato COMMISSIONED prima che possa 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 registratore di cassa.
Corrisponde al client in SIGN DE.
Ogni System è collegato a una Entity::LOCATION.

A differenza di SIGN DE, quando si crea un FISCAL_DEVICE, devono essere fornite informazioni aggiuntive sul sistema di registrazione elettronica stesso.
La maggior parte di questi dettagli è tipicamente definita dal fornitore del POS.
In Germania, queste informazioni vengono solitamente aggiunte successivamente come parte del processo DSFinV-K DE o Submit DE — in SIGN IT, tuttavia, ciò avviene in un unico passaggio durante la creazione del sistema.

PATCH: Aggiornare System

Aggiorna il System dallo stato ACQUIRED a COMMISSIONED per attivarlo.

La risorsa System segue la stessa logica di stato e modo di una Entity.
Una volta impostato a COMMISSIONED, il sistema diventa attivo e la fatturazione si applica automaticamente (quando utilizzato nell’ambiente LIVE).
Se non è più in uso, può essere impostato a DECOMMISSIONED, il 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. Questi modi si comportano allo stesso modo descritto per Entity, consentendoti di sospendere temporaneamente le operazioni o di indicare automaticamente prestazioni degradate a causa di problemi di configurazione.

Configurazione Completata

Con il System commissionato con successo, la fase di configurazione iniziale è completa.
Tutte le strutture organizzative e fiscali — dall’Asset::UNIT all’Entity e al System — sono ora attive e pronte per la produzione.

Da questo punto in poi, i passaggi seguenti descrivono le operazioni fiscali quotidiane effettuate 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 commissionate tutte le risorse, 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 da uno o più Record, che sono firmati digitalmente, registrati nel giornale e archiviati per garantire la piena conformità fiscale.

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

POST: Creare Record

In SIGN IT, ogni transazione fiscale è rappresentata da uno o più Record.
Questo modello sostituisce il processo di aggiornamento della transazione in due fasi 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 aggiornato a uno stato completato.
In SIGN IT, questa logica viene 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, incluse:

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 attraverso 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 creato in precedenza.
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 sono più strettamente allineati con le informazioni contenute in una transazione all’interno di un chiusura di cassa (Kassenabschluss) in DSFinV-K DE.

Include:

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

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

Stati e Modi dei Record

Ogni Record in SIGN IT (che sia INTENTION, TRANSACTION o altri tipi) segue il proprio stato e modo, riflettendo 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 le nostre verifiche di validazione interne. I dettagli sono disponibili nei messaggi di log.
Completed – Il Record è stato elaborato con successo.
Failed – Il Record non è stato elaborato a causa di un errore di trasmissione esterno. I dettagli sono disponibili nei messaggi di log.

Modi

Processing – Il Record è attualmente in 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 successo, procedendo immediatamente al passaggio successivo.
POST → Rejected	Il Record non supera la validazione interna e passa automaticamente a `Rejected`, fornendo log degli errori.
Accepted → Completed	Impostato automaticamente quando l’elaborazione termina con successo.
Accepted → Failed	Impostato quando l’elaborazione fallisce a causa di un componente esterno.
Processing → Finished	Indica che l’elaborazione è stata completata, indipendentemente dall’esito positivo o negativo.

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

Riepilogo

Nelle operazioni quotidiane, SIGN IT sostituisce il semplice flusso di transazione “Inizio → Fine” di SIGN DE con un modello di Record multi-risorsa e guidato dagli eventi.
Ogni operazione — che si tratti di una vendita (RECEIPT), reso (CORRECTION) o annullamento (CANCELLATION) — viene firmata, registrata e archiviata individualmente, garantendo la completa tracciabilità e conformità con la legge fiscale italiana.

Was this page helpful?