Per i clienti SIGN DE

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

Questa guida spiega le principali differenze rispetto a SIGN DE e supporta una corretta integrazione dell’API fiskaly SIGN FR. Illustra tutti i passaggi necessari per voi e per i vostri commercianti.

Approccio API unificata

SIGN FR fa parte dell’approccio API unificata di fiskaly. Ciò significa che integrando SIGN FR, si è già preparati a utilizzare SIGN IT (Italia) e SIGN ES (Spagna), nonché altri paesi futuri, con uno sforzo aggiuntivo minimo.

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

Ambienti: TEST e LIVE

In SIGN FR, esistono 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 stessa API Key che determina se vengono creati risorse TEST o LIVE.
Un token creato con una API Key LIVE crea risorse LIVE.
Un token creato con una API Key TEST crea risorse TEST, anche se l’URL rimane lo stesso.

In SIGN FR, l’ambiente viene selezionato tramite l’URL base.
È necessario chiamare ogni endpoint con l’URL base corretto (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 unificata, sono state introdotte alcune 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 unificata, ogni richiesta deve includere l’intestazione X-Api-Version.
Il valore corrisponde alla data di rilascio della versione. Questo fornisce il pieno controllo su quando passare a una versione più recente per utilizzare nuove funzionalità.

È possibile testare prima le modifiche nell’ambiente TEST e migrare alla nuova versione solo una volta che tutto è stato verificato. Questo consente anche di mantenere alcuni clienti su una versione precedente durante l’onboarding di nuovi clienti direttamente con la versione più recente.

Vantaggio principale: nessun cambiamento incompatibile nella versione in esecuzione.

X-Idempotency-Key

Poiché gli ID delle risorse non devono più essere definiti dall’utente 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 impediscono 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 nella Management API per stabilire relazioni tra le risorse.

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

Mappatura della terminologia: SIGN FR vs. SIGN DE

SIGN FR	SIGN DE	Spiegazione
`Organization::ACCOUNT`	(nessun equivalente)	Struttura di livello superiore nel fiskaly HUB. Rappresenta l’intero Account cliente.
`Organization::GROUP`	`organization` (con `billing_options`)	Rappresenta l’organizzazione principale, sotto cui sono annidati i contribuenti
`Organization::UNIT`	`managed_organization`	Rappresenta un singolo commerciante o contribuente. Ogni `Organization::UNIT` è collegata a un `Taxpayer`.
`Taxpayer::COMPANY` or `Taxpayer::INDIVIDUAL`	In Germania parte di `managed_organization` (DSFINVK DE) o `taxpayer` (SUBMIT DE)	Definisce il contribuente per la `Organization::UNIT` collegata, necessario per adempiere agli obblighi fiscali.
`Location`	Confrontabile: `establishment` (SUBMIT DE)	Rappresenta le sedi fisiche (es. 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 API Key, utilizzato per autorizzare l’accesso.
`Record`	`transaction`	Rappresenta un’operazione eseguita al registratore di cassa. Per eventi speciali, può consistere solo in una `Record::INTENTION`. Per le transazioni, richiede sempre due chiamate: una `Record::INTENTION` e una `Record::TRANSACTION`.
`Record::INTENTION`	`Start-Transaction`	Segna l’inizio di un processo di acquisto o di un singolo altro evento che viene elaborato al 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, è necessario creare un’Organizzazione separata specificamente per la Francia nel fiskaly HUB e una API Key dedicata per l’integrazione francese.

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

POST: Crea token

Utilizzare 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 utilizzando la API Key dell’Organizzazione (principale) e poi usato per creare managed_organizations.
In SIGN FR, questo token è ora necessario per creare risorse Organization::UNIT.

POST: Crea organizzazione (UNIT)

Creare una Organization::UNIT (organizzazione di tipo Unit) che rappresenta il primo cliente. Questo equivale alla managed_organization creata tramite l’Management API usata per SIGN DE.

In questo passaggio, è necessario 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 una persona fisica. Questi dettagli vengono definiti nel passaggio Contribuente (COMPANY / INDIVIDUAL) di seguito.

POST: Crea subject (API Key)

Ciascuno dei clienti necessita della propria API Key per creare risorse all’interno del proprio specifico ambito Organization::UNIT.
Per questo motivo, deve essere creato un Subject::API_KEY (subject di tipo API Key).

Collegare la propria API Key alla Organization::UNIT utilizzando l’intestazione X-Scope-Identifier.

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

POST: Crea token (con ambito)

Questo token è delimitato alla Organization::UNIT. Utilizzarlo per tutte le operazioni specifiche del contribuente.

Con la API Key precedentemente creata per la Organization::UNIT, è necessario creare questo token con ambito.
Verrà utilizzato per tutte le operazioni che devono essere gestite all’interno di questa specifica Organization::UNIT.

POST: Crea contribuente (COMPANY / INDIVIDUAL)

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

Un Taxpayer di tipo COMPANY o INDIVIDUAL rappresenta il contribuente — sia un’entità giuridica (azienda) sia una persona fisica (titolare individuale).
Ogni contribuente deve essere creato prima che possano essere eseguite operazioni fiscali.

Poiché SIGN FR segue l’approccio API unificata, la struttura Taxpayer è progettata in modo standardizzato e divisa in due parti principali:

Informazioni generali (condivise tra tutti i paesi):
Comprende attributi comuni come il nome e l’indirizzo del contribuente.
Informazioni di fiscalizzazione (sezione specifica del paese):
Contiene attributi fiscali richiesti dalla normativa nazionale, come il numero di identificazione fiscale e le credenziali fiscali.
In Francia, questo include attributi fiscali come il numero SIREN e la data dell’esercizio fiscale richiesti dalla normativa nazionale.

PATCH: Aggiorna contribuente

Aggiornare lo stato da ACQUIRED a COMMISSIONED per attivare il contribuente.

A differenza di SIGN DE, i contribuenti in SIGN FR hanno un attributo di stato.
Quando viene creato un contribuente, il suo stato iniziale è ACQUIRED.
Prima che possa essere utilizzato, il contribuente deve essere aggiornato allo stato COMMISSIONED.

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

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

Oltre agli stati, ogni contribuente in SIGN FR ha un attributo di modalità che definisce il suo stato operativo.

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

Riepilogo:

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

POST: Crea sede

Definisce la sede fisica del negozio. Inizia anch’essa nello stato ACQUIRED.

Per ogni sede di un contribuente, deve essere creata una Location separata.
Nella soluzione SIGN FR, 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 Taxpayer::COMPANY o Taxpayer::INDIVIDUAL corrispondente.
Ogni contribuente deve avere almeno una Location associata.

PATCH: Aggiorna sede

Aggiornare 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 sistema

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, durante la creazione di un FISCAL_DEVICE, devono essere fornite informazioni aggiuntive sul sistema di registrazione elettronico stesso.
La maggior parte di questi dettagli è tipicamente definita dal fornitore POS.
In Germania, queste informazioni vengono solitamente aggiunte in seguito come parte del processo DSFinV-K DE o Submit DE — in SIGN FR, tuttavia, questo avviene in un unico passaggio durante la creazione del sistema.

PATCH: Aggiorna sistema

Aggiornare 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 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 Taxpayer, consentendo di sospendere temporaneamente le operazioni o indicare automaticamente prestazioni degradate a causa di problemi di configurazione.

Configurazione completata

Con il System messo in servizio con successo, la fase di configurazione iniziale è completa.
Tutte le strutture organizzative e fiscali — da Organization::UNIT a Taxpayer e System — sono ora attive e pronte per la produzione.

Da questo punto in poi, i seguenti passaggi descrivono le operazioni fiscali giornaliere svolte al POS.
Questo 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 giornaliere al POS

Una volta completata la configurazione e messe in servizio tutte le risorse, il processo di fiscalizzazione in SIGN FR continua con le operazioni giornaliere.
Queste operazioni rappresentano le attività commerciali giornaliere al POS — come l’emissione di ricevute, l’elaborazione dei resi o la gestione delle cancellazioni.

Mentre il concetto generale è 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, registrati nel diario 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 delle transazioni 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 FR, questa logica è 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 solo un singolo 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 sistema (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 attraverso 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 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), inclusi descrizione, quantità, aliquota IVA e importo.
Riferimenti a ricevute precedenti durante la creazione di record CORRECTION o CANCELLATION.
Ulteriori tipi di operazione sono supportati anche 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 richiesta 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à, 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 – 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 elaborazione.
Finished – Il record è stato elaborato, con successo o meno.

Transizioni

Transizione	Descrizione
POST → Accepted	Il record viene creato ed entra temporaneamente nello stato `Accepted` se la validazione ha successo, e procede immediatamente al passaggio successivo.
POST → Rejected	Il record non supera 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 dall’insuccesso.

Questo design basato sugli eventi consente di tracciare ogni operazione fiscale in modo indipendente — senza aggiornare la stessa risorsa — garantendo una traccia di verifica 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à di 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 solo come record di tipo INTENTION e non richiedono una controparte TRANSACTION.
Estendono la tracciabilità fiscale a tutte le attività POS rilevanti al di là delle transazioni di vendita.

Riepilogo

Nelle operazioni giornaliere, 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, registrata nel diario e archiviata individualmente, garantendo la completa tracciabilità e la conformità con la legge fiscale francese.

Was this page helpful?