Integrazione passo dopo passo

⚠️ 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).

Per avviare il processo di integrazione, fare riferimento alle istruzioni dettagliate passo dopo passo fornite qui.

Il diagramma allegato illustra il flusso di lavoro e mette in evidenza i passaggi essenziali necessari per completare con successo l’integrazione, per la quale sarà necessario utilizzare la nostra SIGN FR.

Passo 1: Registrazione

Iniziare registrandosi sull’HUB.

La creazione di un account fiskaly è il primo passo, dopodiché è possibile procedere con la configurazione della prima struttura organizzativa per la propria attività e la generazione della propria Chiave API.

📘Tutorial video

Guarda il nostro video per una spiegazione passo dopo passo su come configurare il tuo account e la tua prima organizzazione.

Passo 2: Creazione della prima organizzazione

Procedere con la creazione della prima organizzazione tramite HUB. Questa organizzazione rappresenterà il fornitore del sistema di cassa o il rivenditore con il proprio sistema di cassa.

Passo 3: Generazione della Chiave API

Il passo successivo è generare una Chiave API per la propria organizzazione tramite l’HUB. Questa coppia di Chiave API e Segreto è necessaria per creare il primo Asset di tipo UNIT (Passo 5).

Si noti che le Chiavi API generate nell’ambiente TEST creeranno risorse TEST, mentre quelle dell’ambiente LIVE creeranno risorse LIVE. Per ulteriori dettagli, fare riferimento al nostro articolo sugli ambienti TEST e LIVE.

A partire dal passo successivo, si utilizzerà la nostra API SIGN FR.

Passo 4: GESTIONE - Creazione di un Token

Iniziare a utilizzare l’API SIGN FR tramite l’endpoint createToken. Sarà necessario creare un token per autenticarsi nei passi successivi.

Passo 5: GESTIONE - Creazione di un Asset (Struttura organizzativa)

Procedere con la creazione di un Asset di tipo UNIT tramite l’endpoint createAsset. Sarà necessario creare un Asset UNIT per ciascuna delle rappresentazioni dei propri contribuenti.

Quando si crea il primo Asset di tipo UNIT, assicurarsi che sia associato all’UUID della prima organizzazione creata tramite l’HUB. A tale scopo, utilizzare il token generato dalle chiavi API create nella prima organizzazione. Questo riflette la struttura gerarchica in cui la UNIT è annidata sotto la prima organizzazione.

Passo 6: GESTIONE - Creazione di un Subject

Creare un Subject di tipo API_KEY tramite l’endpoint createSubject. La connessione tra l’Asset UNIT e la Chiave API viene stabilita tramite il X-Scope-Identifier (usando l’id dell’Asset appena creato).

Passo 7: GESTIONE - Creazione di un nuovo Token

Successivamente, creare un token che verrà utilizzato per creare risorse all’interno dell’Asset UNIT corrispondente.

Passo 8: OPERAZIONE - Creazione di un’Entity (Rappresentazione del contribuente)

Ora si è pronti per iniziare a creare le parti operative necessarie per la fiscalizzazione in Francia. A tal fine, utilizzare l’endpoint createEntity per creare la rappresentazione di un Contribuente come segue:

• Sarà necessario impostare il Contribuente come Entity di tipo Company (azienda) o Individual (autonomo/ditta individuale). In entrambi i casi, devono essere forniti name e address.
• All’interno delle informazioni di fiscalization francese, devono essere forniti i seguenti dati del contribuente:
  • tax_id_number: Numero di identificazione dell’azienda francese (numero SIREN) rilasciato dall’INSEE,
  • credentials: Credenziali di fiscalizzazione francese.

Una volta creata un’Entity, di tipo Company o Individual, il suo state sarà impostato su ACQUIRED. Per essere completamente funzionale, lo stato deve essere aggiornato a COMMISSIONED utilizzando l’endpoint updateEntity.

Passo 9: OPERAZIONE - Creazione di un’Entity Ubicazione

Per ogni sede operativa, è necessario creare un’Entity di tipo Location tramite l’endpoint createEntity.

Quando si crea un’Entity di tipo Location, il suo state viene inizialmente impostato su ACQUIRED. Per procedere, è necessario modificare lo stato in COMMISSIONED utilizzando l’endpoint updateEntity.

Passo 10: OPERAZIONE - Creazione di un System (Rappresentazione del sistema di cassa)

L’endpoint createSystem consente di creare un’astrazione di ogni dispositivo utilizzato per emettere ricevute. Ciò significa che ogni registratore di cassa o punto vendita deve essere fornito come nuovo System in SIGN FR. A tale scopo, deve essere selezionato il tipo di System FISCAL_DEVICE.

• Un System sarà collegato a un’Entity già creata (che sia di tipo Company o Individual, oppure una Location specifica se diversa dall’indirizzo legale).
• Per ogni dispositivo, sarà necessario fornire informazioni sul prodotto come MPN, marca e la data di inizio utilizzo, insieme al nome del software e alla versione installata sul dispositivo. Queste informazioni garantiscono il corretto tracciamento del dispositivo che esegue le transazioni fiscali.

Quando si crea un System, il suo stato iniziale è impostato su ACQUIRED. Per creare Record, il suo state deve essere aggiornato a COMMISSIONED utilizzando l’endpoint updateSystem.

Passo 11: OPERAZIONE - Creazione di un Record

💡Tip

La creazione di un Record in SIGN FR richiederà nella maggior parte dei casi due chiamate successive:

• Parte A) INTENTION - all’inizio del processo di vendita - Parte B) TRANSACTION - direttamente dopo il processo di pagamento

Operazione di transazione

PARTE A) Intention

Per ogni operazione commerciale di tipo RECEIPT effettuata nel registratore di cassa o nel sistema di cassa, l’endpoint createRecord dell’API SIGN FR verrà utilizzato in due chiamate: la prima per registrare l’intenzione di avviare una transazione, e la seconda per fornire i dati della transazione.

Un Record di tipo Intention conterrà le seguenti informazioni:

• Associazione con un System che eseguirà la transazione.
• Operazione di tipo Transaction: Ciò significa che l’operazione che il System intende eseguire è la registrazione di una transazione.

Parte B) Transaction

Il passo finale per emettere una ricevuta conforme in Francia è effettuare un’altra chiamata all’endpoint createRecord, indicando un Record di tipo Transaction.

Qualsiasi documento Transaction sarà associato all’identificatore interno di un Record di tipo Intention già creato, e può contenere dettagli per scopi formativi (documenti emessi in modalità formazione o test).

La Transaction può essere utilizzata per eseguire una delle seguenti operazioni in Francia:

• RECEIPT: Questa operazione contiene tutte le informazioni richieste per la creazione di un documento commerciale di vendita in Francia:
  • Informazioni sul documento come numero, codice attività (se applicabile), data della transazione e importi totali del documento (IVA inclusa ed esclusa)
  • Informazioni su ogni voce o articolo venduto nell’operazione:
    • Identificazione di una Vendita
    • Descrizione
    • Indicazione se si tratta di un bene o servizio
• CORRECTION: Questo tipo di operazione viene utilizzato per rappresentare qualsiasi processo di reso effettuato. Contiene gli stessi dati di un’operazione di tipo RECEIPT, e in aggiunta:
  • id di riferimento a una ricevuta già creata (documento di transazione originale)
• CANCELLATION: Questa operazione viene utilizzata per annullare un’intera transazione. A tale scopo, è necessario fornire l’id di un record precedentemente creato.

Operazioni aggiuntive

Oltre al flusso standard Intention → Transaction, SIGN FR supporta le seguenti operazioni:

• DUPLICATE
• EXPORT
• EVENT

Queste operazioni vengono create come Record di tipo Intention (con operazione DUPLICATE, EXPORT o EVENT) e non richiedono una successiva chiamata Transaction. Consentono che le attività aggiuntive del sistema di cassa vengano firmate, giornalizzate e archiviate oltre il flusso di transazioni standard.

---

In tutti i casi, una volta che il record viene correttamente creato, i dati verranno firmati, giornalizzati e archiviati per soddisfare i tre principali obblighi fiscali in Francia.