Per i clienti SIGN DE

⚠️ Stai visualizzando la documentazione per la versione API 2026-02-03. La versione più recente è 2026-05-04. La nuova versione API non apporta modifiche all’integrazione italiana. Tuttavia, aggiunge il supporto SIGN PT, consentendo ai team che pianificano di espandersi in Portogallo di riutilizzare la stessa integrazione già in uso per l’Italia.

Guida all’integrazione SIGN IT per i clienti SIGN DE

Questa guida spiega 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 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à preparato per utilizzare SIGN FR (Francia), nonché altri paesi futuri, con un minimo sforzo aggiuntivo.

A differenza di SIGN DE, SIGN IT non richiede un’Management API separata. Tutti gli endpoint necessari per l’autenticazione, la creazione dell’organizzazione, la configurazione e la 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 separati 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’è un solo URL base utilizzato 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 lo stesso.

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

Parametri Header

Nell’approccio API Unificato, sono stati introdotti alcuni nuovi header 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 dell’API Unificata, ogni richiesta deve includere l’header X-Api-Version.
Il valore corrisponde alla data di rilascio della versione. Questo ti dà il pieno controllo su quando passare a una versione più recente al fine di 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 acquisisci nuovi clienti direttamente con l’ultima versione.

Principale vantaggio: non più 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, la X-Idempotency-Key garantisce che una chiamata API venga gestita in modo idempotente.

Ciò significa che richieste identiche ripetute con la stessa X-Idempotency-Key producono lo stesso risultato e prevengono la creazione di duplicati.

La X-Idempotency-Key è obbligatoria per tutte le richieste POST e PATCH.

X-Scope-Identifier

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

Rende le integrazioni più pulite e flessibili, poiché l’header definisce esplicitamente lo scope (ad esempio, a quale Organization::UNIT appartiene una Chiave API).

Mappatura della terminologia: SIGN IT vs. SIGN DE

SIGN IT	SIGN DE	Spiegazione
`Organization::ACCOUNT`	(nessun equivalente)	Struttura di livello superiore in fiskaly HUB. Rappresenta l’intero account cliente.
`Organization::GROUP`	`organization` (con `billing_options`)	Rappresenta l’organizzazione principale, sotto la quale sono annidate le istanze contribuenti.
`Organization::UNIT`	`managed_organization`	Rappresenta un singolo commerciante o contribuente. Ogni `Organization::UNIT` è collegata a un `Taxpayer`.
`Taxpayer::COMPANY` o `Taxpayer::INDIVIDUAL`	In Germania parte della `managed_organization` (DSFINVK DE) o `taxpayer` (SUBMIT DE)	Definisce il contribuente per la corrispondente `Organization::UNIT`, necessario per adempiere agli obblighi fiscali.
`Location`	Comparabile: `establishment` (SUBMIT DE)	Rappresenta la/le sede/i fisica/e (ad es. negozi) gestita/e dal contribuente.
`System::FISCAL_DEVICE`	`client`	Rappresenta il POS / registratore di cassa utilizzato per la fiscalizzazione.
`Subject::API_KEY`	`API key`	Oggetto di autenticazione chiave API, utilizzato per autorizzare l’accesso.
`Record`	`transaction`	Rappresenta un’operazione effettuata sul registratore di cassa. Richiede sempre due chiamate: una `Record::INTENTION` e una `Record::TRANSACTION`.
`Record::INTENTION`	`Start-Transaction`	Segna l’inizio di un processo di acquisto, o un altro singolo evento elaborato sul registratore di cassa.
`Record::TRANSACTION`	`Finish-Transaction`	Segna il completamento (fine) di un processo di acquisto.

SIGN IT Passo dopo passo

Prima organizzazione

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

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

POST: Crea Token

Utilizza 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 utilizzato per creare managed_organizations.
In SIGN IT, questo token è ora necessario per creare risorse Organization::UNIT.

POST: Crea Organizzazione (UNIT)

Crea una Organization::UNIT (Organizzazione di tipo Unit) che rappresenta il tuo primo cliente. Questo equivale alla managed_organization creata tramite il Management utilizzato per SIGN DE.

In questo passaggio è richiesto solo il nome della Organization::UNIT.
A differenza di SIGN DE, le informazioni sul contribuente appartengono alla risorsa Taxpayer, che può essere di tipo COMPANY o INDIVIDUAL, a seconda che il contribuente sia una persona giuridica o fisica. Definirai questi dettagli nel passaggio Taxpayer (COMPANY / INDIVIDUAL) qui di seguito.

POST: Crea Subject (Chiave API)

Ognuno dei tuoi clienti richiede la propria Chiave API per creare risorse all’interno dello scope specifico della propria Organization::UNIT.
Per questo motivo, deve essere creato un Subject::API_KEY (Subject di tipo Chiave API).

Collega la tua Chiave API alla Organization::UNIT utilizzando l’header X-Scope-Identifier.

A differenza di SIGN DE, le informazioni su quale Unit appartiene la Chiave API non vengono più fornite tramite il parametro path, ma invece tramite il parametro header X-Scope-Identifier.
Questo header deve contenere l’ID della Organization::UNIT a cui appartiene la Chiave API.

POST: Crea Token (con scope)

Questo token ha scope per la Organization::UNIT. Utilizzalo per tutte le operazioni specifiche del contribuente.

Con la Chiave API precedentemente creata per la Organization::UNIT, devi creare questo token con scope.
Sarà utilizzato per tutte le operazioni che devono essere gestite all’interno di questa specifica Organization::UNIT.

POST: Crea Taxpayer (COMPANY / INDIVIDUAL)

Definisce la rappresentazione del contribuente per la corrispondente Organization::UNIT.

Un Taxpayer di tipo COMPANY o INDIVIDUAL rappresenta rispettivamente una persona giuridica (azienda) o una persona fisica (lavoratore autonomo).
Ogni contribuente deve essere creato prima che le operazioni fiscali possano essere eseguite.

Poiché SIGN IT segue l’approccio API Unificato, la struttura Taxpayer è 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 per paese):
Contiene gli 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 e la partita IVA richiesti dalla normativa nazionale.

PATCH: Aggiorna Taxpayer

Aggiorna lo stato da ACQUIRED a COMMISSIONED per attivare il Taxpayer.

A differenza di SIGN DE, i Taxpayer in SIGN IT hanno un attributo state.
Quando un Taxpayer viene creato, il suo stato iniziale è ACQUIRED.
Prima di poter essere utilizzato, il Taxpayer deve essere aggiornato allo stato COMMISSIONED.

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

Se un Taxpayer non è più in uso, può essere aggiornato allo stato DECOMMISSIONED.
Anche questo passaggio è irreversibile e dovrebbe essere eseguito solo una volta che si è certi che il cliente non utilizzerà più questo Taxpayer.

Oltre agli stati, ogni Taxpayer in SIGN IT ha un attributo mode che definisce il suo stato operativo.

Quando il Taxpayer è nello stato ACQUIRED o DECOMMISSIONED, la sua modalità è sempre INACTIVE.
In questa modalità, la risorsa non può essere utilizzata.
Quando il Taxpayer viene aggiornato allo stato COMMISSIONED, il servizio SIGN IT valida automaticamente tutte le configurazioni richieste.
Se ha successo, la modalità passa a OPERATIVE.
Se si verifica un problema con il Taxpayer o una delle sue risorse dipendenti, la modalità cambia automaticamente a DEGRADED (non ancora implementato) fino alla risoluzione del problema.
Una volta risolto il problema, il servizio SIGN IT riporterà la modalità a OPERATIVE.
La modalità SUSPENDED può essere impostata manualmente per i Taxpayer nello stato COMMISSIONED utilizzando l’endpoint updateTaxpayer.
Questo è utile per sospendere temporaneamente le operazioni fiscali, ad esempio durante l’aggiornamento delle credenziali o la manutenzione. Se il servizio SIGN IT imposta il Taxpayer alla modalità DEGRADED (non ancora implementato) a causa di un problema che richiede l’intervento dell’utente, la modalità dovrebbe essere prima cambiata a SUSPENDED durante l’esecuzione delle azioni necessarie, e poi aggiornata di nuovo a OPERATIVE una volta risolto il problema.

Riepilogo:

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

POST: Crea Location

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

Per ogni sede di un contribuente, dovrebbe essere creata una Location separata.
Nella soluzione SIGN IT, questo non richiede una Organization::UNIT separata.
Tutte le sedi di un contribuente sono rappresentate all’interno della stessa Organization::UNIT e sono collegate al corrispondente Taxpayer::COMPANY o Taxpayer::INDIVIDUAL.
Ogni contribuente dovrebbe avere almeno una Location associata.

PATCH: Aggiorna Location

Aggiorna lo stato della Location a COMMISSIONED.

Come per Taxpayer::COMPANY o Taxpayer::INDIVIDUAL, anche la 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: Crea 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 Location.

A differenza di SIGN DE, quando si crea un FISCAL_DEVICE, è necessario fornire informazioni aggiuntive sul sistema di tenuta elettronica stesso.
La maggior parte di questi dettagli sono tipicamente definiti dal fornitore POS.
In Germania, queste informazioni vengono solitamente aggiunte in seguito come parte del processo DSFinV-K DE o Submit DE — in SIGN IT, invece, questo viene fatto in un unico passaggio durante la creazione del sistema.

PATCH: Aggiorna System

Aggiorna il System dallo stato ACQUIRED a COMMISSIONED per attivarlo.

La risorsa System segue la stessa logica di stato e modalità di un Taxpayer.
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 le condizioni operative del sistema (ad esempio, OPERATIVE, SUSPENDED o DEGRADED). DEGRADED non è ancora implementato. Queste modalità si comportano allo stesso modo descritto per Taxpayer, consentendo di sospendere temporaneamente le operazioni o indicare automaticamente prestazioni degradate a causa di problemi di configurazione.

Configurazione completata

Con il System commissioni con successo, la fase di configurazione iniziale è completa.
Tutte le strutture organizzative e fiscali — dalla Organization::UNIT al Taxpayer e al System — sono ora attive e pronte per la produzione.

Da questo momento in poi, i passaggi seguenti descrivono le operazioni fiscali quotidiane effettuate al POS.
Questo include la creazione e l’elaborazione dei 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à aziendali quotidiane al POS — come l’emissione di ricevute, l’elaborazione dei resi o la gestione delle cancellazioni.

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, firmati digitalmente, registrati e archiviati per garantire la piena conformità fiscale.

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

POST: Crea Record

In SIGN IT, ogni transazione fiscale è rappresentata come uno o più Record.
Questo modello sostituisce il processo di aggiornamento delle transazioni in due fasi di SIGN DE (ACTIVE → FINISHED) con due risorse indipendenti: un Record di tipo INTENTION e un altro Record 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 terminato.
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 intention supportata è TRANSACTION.

Contiene informazioni contestuali che definiscono l’intento dell’operazione, inclusi:

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 con le 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 totali lordi e netti.
Dettagli per ogni riga di vendita (merci o servizi), inclusi descrizione, quantità, aliquota IVA e importo.
Riferimenti a ricevute precedenti quando si creano record CORRECTION o CANCELLATION.

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

Stati e modalità dei Record

Ogni Record in SIGN IT (che sia INTENTION, TRANSACTION o altri tipi) segue il proprio state e mode, che riflettono 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 nostri controlli di validazione interni. I dettagli sono disponibili nei messaggi di log.
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 log.

Modalità

Processing — Il Record è attualmente in fase di elaborazione.
Finished — Il Record è stato elaborato, con successo o senza.

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 dal successo o dal fallimento.

Questo design basato sugli 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 “Avvio → 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 cancellazione (CANCELLATION) — viene firmata, registrata e archiviata individualmente, garantendo la completa tracciabilità e la conformità alla legge fiscale italiana.

Was this page helpful?