Per i clienti di SIGN DE

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

Guida all’integrazione di SIGN FR per i clienti di SIGN DE

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

Approccio API unificato

SIGN FR fa parte dell’approccio API unificato di fiskaly. Ciò significa che integrando SIGN FR, sei già pronto a utilizzare SIGN IT (Italia) e SIGN ES (Spagna), così come altri paesi futuri, con il minimo sforzo aggiuntivo.

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

Ambienti: TEST e LIVE

In SIGN FR, ci sono due URL di 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 di base 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 FR, l’ambiente viene selezionato tramite l’URL di base.
È necessario chiamare ogni endpoint con l’URL di base corretto (test.api.fiskaly.com o live.api.fiskaly.com), a seconda che si voglia interagire con l’ambiente TEST o LIVE.

Parametri header

Nell’approccio API unificato, sono stati introdotti alcuni nuovi header 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 unificate, ogni richiesta deve includere l’header 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 dopo che tutto è stato verificato. Ciò ti consente anche di mantenere alcuni clienti su una versione precedente se necessario, mentre inserisci nuovi clienti direttamente con la versione più recente.

Vantaggio principale: niente 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, 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 prevengono creazioni duplicate.

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

X-Scope-Identifier

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

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

Mappatura della terminologia: SIGN FR vs. SIGN DE

SIGN FR	SIGN DE	Spiegazione
`Asset::Tenant`	(nessun equivalente)	Struttura di livello superiore nel fiskaly HUB. Rappresenta l’intero account del cliente. Non può essere annidata all’interno di altri asset.
`Asset::Group` (opzionale)	`organization` (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 un’`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 (es. negozi) gestite dal contribuente.
`System::FISCAL_DEVICE`	`client`	Rappresenta il sistema di cassa / 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. Per eventi speciali, può consistere solo in un `Record::INTENTION`. Per le transazioni, 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 elaborato sul registratore di cassa.
`Record::TRANSACTION`	`Finish-Transaction`	Segna il completamento (fine) di un processo di acquisto.

SIGN FR passo dopo passo

Prima organizzazione

Per iniziare, devi creare un’organizzazione separata specificamente per la Francia nel fiskaly HUB e una Chiave API dedicata per l’integrazione francese.

Da questo momento in poi, tutti i passaggi di integrazione vengono gestiti direttamente tramite l’API SIGN FR. A differenza di SIGN DE, non è più necessario utilizzare l’Management API per creare o gestire strutture organizzative. Tutta la funzionalità richiesta fa parte dell’API SIGN FR stessa.

POST: Crea Token

Utilizza questo token per autenticare la creazione della struttura organizzativa per la Francia.
Funziona allo stesso modo del token in SIGN DE (Management API), che veniva creato usando la Chiave API dell’organizzazione (principale) e poi utilizzato per creare managed_organizations.
In SIGN FR, questo token è ora necessario per creare risorse Asset::Unit.

POST: Crea Asset (UNIT)

Crea un Asset::UNIT (Asset di tipo Unit) che rappresenta il tuo primo cliente. Equivale alla managed_organization creata tramite l’Management API usata 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: Crea Subject (Chiave API)

Ciascuno dei tuoi clienti richiede la propria Chiave API per creare risorse nell’ambito specifico 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’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 di percorso, ma tramite il parametro header X-Scope-Identifier.
Questo header deve contenere l’ID dell’Asset::UNIT a cui appartiene la Chiave API.

POST: Crea Token (con ambito)

Questo token ha l’ambito dell’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: Crea Entity (COMPANY / INDIVIDUAL)

Definisce la rappresentazione del contribuente per l’Asset::Unit corrispondente.

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

Poiché SIGN FR 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 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 e le credenziali fiscali.
In Francia, ciò include attributi fiscali come il numero SIREN e la data dell’esercizio fiscale richiesti dalle normative nazionali.

PATCH: Aggiorna Entity

Aggiorna lo stato da ACQUIRED a COMMISSIONED per attivare l’Entity.

A differenza di SIGN DE, le Entity in SIGN FR hanno un attributo stato.
Quando un’Entity viene creata, il suo stato iniziale è ACQUIRED.
Prima che possa essere utilizzata, l’Entity deve essere aggiornata allo stato COMMISSIONED.

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

Se un’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 FR ha un attributo modalità che definisce il suo stato operativo.

Quando l’Entity è in stato ACQUIRED o DECOMMISSIONED, la sua modalità è sempre INACTIVE.
In questa modalità, la risorsa non può essere utilizzata.
Quando l’Entity viene aggiornata allo stato COMMISSIONED, il servizio SIGN FR valida automaticamente tutte le configurazioni richieste.
Se ha successo, la modalità passa a OPERATIVE.
Se c’è un problema con l’Entity o una delle sue risorse dipendenti, la modalità cambia automaticamente in DEGRADED fino a quando il problema non viene risolto.
Una volta risolto il problema, il servizio SIGN FR riporterà la modalità a OPERATIVE.
La modalità SUSPENDED può essere impostata manualmente per le Entity in stato COMMISSIONED usando l’endpoint di aggiornamento.
Ciò è utile per sospendere temporaneamente le operazioni fiscali, ad esempio, quando si aggiornano le credenziali o si esegue la manutenzione.
Se il servizio SIGN FR imposta l’Entity sulla modalità DEGRADED a causa di un problema che richiede l’azione dell’utente, la modalità dovrebbe prima essere cambiata in SUSPENDED mentre si eseguono le azioni necessarie,
e poi aggiornata nuovamente a OPERATIVE una volta risolto il problema.

Riepilogo:

INACTIVE: Modalità predefinita per ACQUIRED e DECOMMISSIONED
OPERATIVE: Modalità produttiva normale
DEGRADED: Impostata automaticamente dal servizio SIGN FR a causa di un problema
SUSPENDED: Modalità di manutenzione manuale

POST: Crea Entity (LOCATION)

Definisce la sede fisica dell’attività. Inizia anche in stato ACQUIRED.

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

PATCH: Aggiorna Entity

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: Crea System

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

A differenza di SIGN DE, quando si crea un FISCAL_DEVICE, devono essere fornite informazioni aggiuntive sul sistema di conservazione elettronico stesso.
La maggior parte di questi dettagli sono tipicamente definiti dal fornitore del sistema di cassa.
In Germania, queste informazioni vengono solitamente aggiunte in seguito come parte del processo DSFinV-K DE o Submit DE — in SIGN FR, tuttavia, 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’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 FR in generale — è irreversibile.

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

Configurazione completata

Con il System commissariato con successo, la fase di configurazione iniziale è completa.
Tutte le strutture organizzative e fiscali — da Asset::Unit a Entity e System — sono ora attive e pronte per la produzione.

Da questo momento in poi, i seguenti passaggi descrivono le operazioni fiscali quotidiane svolte presso il sistema di cassa.
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 Francia.

Operazioni quotidiane presso il sistema di cassa

Una volta completata la configurazione e commissionate tutte le risorse, il processo di fiscalizzazione in SIGN FR continua con le operazioni quotidiane.
Queste operazioni rappresentano le attività commerciali quotidiane presso il sistema di cassa — come l’emissione di ricevute, l’elaborazione di resi o la gestione di cancellazioni.

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

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

POST: Crea Record

In SIGN FR, ogni transazione fiscale è rappresentata come 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 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 completato.
In SIGN FR, 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 o esegue direttamente operazioni che richiedono un solo passaggio, come EVENT, EXPORT o DUPLICATE.
In Francia, le operazioni di intention supportate sono TRANSACTION, EVENT, EXPORT e DUPLICATE.

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

Il System (System::FISCAL_DEVICE) che esegue l’operazione.
Il tipo di operazione, corrispondente a una delle operazioni di intention supportate elencate sopra.

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 FR, 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 richiesti 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 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 (beni o servizi), inclusa descrizione, quantità, aliquota IVA e importo.
Riferimenti a ricevute precedenti durante la creazione di record CORRECTION o CANCELLATION.
Anche tipi di operazione aggiuntivi sono supportati all’interno di Record::TRANSACTION, a seconda del processo aziendale e del contesto fiscale.

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

Stati e modalità dei Record

Ogni Record in SIGN FR (che sia INTENTION, TRANSACTION o altri tipi) segue il proprio stato e modalità, 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 – La validazione è fallita; 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 con un componente esterno.

Modalità

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

Transizioni

Transizione	Descrizione
POST → Accepted	Il Record viene creato e entra temporaneamente nello stato `Accepted` se la validazione ha successo, e procede immediatamente al passo successivo.
POST → Rejected	Il Record fallisce la validazione 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 pista di audit trasparente e immutabile per ogni transazione.

Operazioni aggiuntive (non transazionali)

Oltre al flusso standard INTENTION → TRANSACTION, SIGN FR supporta anche operazioni fiscali non transazionali:

EVENT – Utilizzato per registrare eventi di sistema o di configurazione (ad esempio, modalità formazione, operazioni di test o riavvii del sistema).
DUPLICATE – Crea un duplicato di un documento fiscale esistente.
EXPORT – Genera un’esportazione di dati fiscali.

Queste operazioni sono rappresentate come Record di tipo INTENTION esclusivamente e non richiedono un TRANSACTION corrispondente.
Estendono la tracciabilità fiscale a tutte le attività rilevanti del sistema di cassa oltre le transazioni di vendita.

Riepilogo

Nelle operazioni quotidiane, SIGN FR sostituisce il semplice flusso di transazioni “Inizio → Fine” di SIGN DE con un modello di Record multi-risorsa e guidato dagli eventi.
Ogni operazione — che si tratti di una vendita, correzione, esportazione o altro evento fiscale — viene firmata, giornalizzata e archiviata individualmente, garantendo la tracciabilità completa e la conformità con la legislazione fiscale francese.

Was this page helpful?