Processo di integrazione passo dopo passo

Fatturazione elettronica B2B

Emetti e ricevi fatture elettroniche B2B legalmente conformi sulle reti supportate.

Supporto multi-paese

Belgio, Germania e Italia con conformità specifica per ciascun paese integrata.

Unified API

Un'unica integrazione per la fatturazione elettronica in tutti i paesi supportati con endpoint coerenti.

Prerequisiti

Prima di iniziare, assicurati di avere:

• Accesso all’HUB di fiskaly (ambiente TEST)
• Una conoscenza di base delle API REST e dei flussi di autenticazione
• I dati di registrazione della tua azienda per la configurazione del Taxpayer

📘Note

Se hai già integrato SIGN IT o SIGN FR, i passaggi iniziali di configurazione di questa guida ti risulteranno probabilmente familiari e potrebbero essere già stati completati. In tal caso, puoi passare direttamente allo Step 10 per esaminare i passaggi aggiuntivi richiesti.

Flusso di integrazione

📘Importante

I passaggi contrassegnati in giallo devono essere completati direttamente su HUB, mentre i restanti passaggi devono essere gestiti tramite l’API. Eseguire ciascuna azione nel contesto corretto è un passaggio importante verso un’integrazione riuscita.

* Step required for BE 🇧🇪 and DE 🇩🇪
* Not required for IT 🇮🇹

Configurazione passo dopo passo

1. Step 1: Registrazione su HUB

   Inizia registrandoti sull’HUB di fiskaly.

   
2. Step 2: Crea Account e GROUP organizzativo

   La creazione di un Account fiskaly è il primo passo, dopodiché puoi procedere con la configurazione della prima struttura organizzativa per la tua azienda e con la generazione della tua API Key.

   L’Account rappresenta il fornitore PoS o un rivenditore che gestisce il proprio sistema PoS. È l’organizzazione di livello più alto nella struttura.

   Dopo aver creato il tuo Account fiskaly, verrai indirizzato all’Organization Selector, dove potrai creare il tuo Group. Un Group è un livello intermedio all’interno di un Account che ti aiuta a organizzare più Units in cluster logici.

3. Step 3: Crea l'API Key

   Il passaggio successivo consiste nel generare un’API Key per la tua Organization tramite l’HUB all’interno del tuo Group. Questa coppia di API Key e Secret è necessaria per creare la tua prima Organization di tipo UNIT (Step 5).

   💡Ambienti TEST e LIVE

   Le API Key generate nell’ambiente TEST (https://test.api.fiskaly.com) creeranno risorse TEST, mentre quelle dell’ambiente LIVE (https://live.api.fiskaly.com) creeranno risorse LIVE.

1. Step 4: MANAGEMENT - Crea un Token

   Inizia a utilizzare l’API E-INVOICE tramite l’endpoint createToken. Dovrai creare un token per autenticarti nei passaggi successivi.

2. Step 5: MANAGEMENT - Crea un'Organization UNIT

   Prosegui creando un’Organization di tipo UNIT tramite l’endpoint createOrganization. Una UNIT rappresenta una singola entità giuridica (esercente). Dovrai creare una UNIT per ogni rappresentazione di Taxpayer che gestisci.

   Quando crei la tua prima Organization di tipo UNIT, assicurati che sia associata al tuo Group creato tramite l’HUB. A tal fine, utilizza il token generato dalle API Key create per il tuo Group. Questo riflette la struttura gerarchica in cui la UNIT è annidata sotto il tuo GROUP, che a sua volta si trova all’interno del tuo ACCOUNT.

3. Step 6: MANAGEMENT - Crea un Subject (API Key)

   Crea un Subject di tipo API_KEY tramite l’endpoint createSubject. Il collegamento tra l’Organization UNIT e l’API Key viene stabilito tramite l’X-Scope-Identifier (utilizzando l’id della Organization appena creata).

4. Step 7: MANAGEMENT - Crea un nuovo Token

   Successivamente, crea un token che verrà utilizzato per creare risorse all’interno della corrispondente Organization UNIT.

5. Step 8: OPERATION - Crea un Taxpayer

   Ora sei pronto a creare i Taxpayer necessari per la fatturazione elettronica. A tal fine, utilizza l’endpoint createTaxpayer. Dovrai impostare il Taxpayer di tipo COMPANY.

   A seconda del paese, la configurazione di fiscalizzazione richiesta e i dati del Taxpayer necessari possono variare, quindi fai riferimento alle guide dedicate per ciascun paese:

   • Belgio
   • Germania
   • Italia
   • Francia (disponibile a breve)
   • Polonia (disponibile a breve)

   Una volta creato un Taxpayer di tipo COMPANY, il suo state verrà impostato su ACQUIRED. Per essere pienamente operativo, lo stato deve essere aggiornato a COMMISSIONED utilizzando l’endpoint updateTaxpayer.

   Quando chiami l’endpoint createTaxpayer, viene creata automaticamente una Location di tipo HEAD_OFFICE. Puoi confermarlo tramite l’endpoint listLocations.

6. Step 9: OPERATION - Crea una Location

   I nuovi clienti che integrano solo la fatturazione elettronica possono saltare questo passaggio.

   Per la fiscalizzazione degli scontrini, devi creare una Location di tipo BRANCH tramite l’endpoint createLocation per ciascuna sede aziendale.

   Quando crei una Location di tipo BRANCH, il suo state è inizialmente impostato su ACQUIRED. Per procedere, devi cambiare lo stato in COMMISSIONED utilizzando l’endpoint updateLocation.

7. Step 10: OPERATION - Crea un System

   L’endpoint createSystem viene utilizzato per creare un’astrazione di un sistema utilizzato per le operazioni fiscali.

   A seconda della tua configurazione, si applica quanto segue:

   • Nuovi clienti che utilizzano solo la fatturazione elettronica: crea un unico System E_INVOICE_SERVICE (uno solo per Taxpayer) e collegalo alla Location HEAD_OFFICE creata automaticamente per te nello step 8.

   • Nuovi clienti che utilizzano la fiscalizzazione degli scontrini e la fatturazione elettronica: crea Systems FISCAL_DEVICE per gli scontrini e un ulteriore System E_INVOICE_SERVICE (uno per Taxpayer). Collega il System E_INVOICE_SERVICE alla Location di tipo HEAD_OFFICE e collega il/i System FISCAL_DEVICE a una Location di tipo BRANCH.

   • Clienti esistenti con dispositivi fiscali già commissionati che aggiungono la fatturazione elettronica: crea un ulteriore System E_INVOICE_SERVICE e collegalo alla Location di tipo HEAD_OFFICE. Quando viene creato un Taxpayer, viene generata automaticamente una Location di tipo HEAD_OFFICE con lo stesso ID. Questo può essere verificato elencando le tue Locations.

   Quando crei un System, il suo stato iniziale è impostato su ACQUIRED. Per procedere con il processo di integrazione della fatturazione elettronica, richiedi il commissioning del System E_INVOICE_SERVICE utilizzando updateSystem.

   ⚠️Importante

   Dopo una richiesta di commissioning riuscita, il System è nello stato COMMISSIONED e inizialmente in modalità DEGRADED finché lo Step 11 non è completamente concluso.

   📘Italia 🇮🇹

   Per i Taxpayer italiani, il System E_INVOICE_SERVICE passa direttamente a state=COMMISSIONED, mode=OPERATIVE dopo il commissioning — nessun caricamento di Proof of Ownership, quindi lo Step 11 non si applica, e può inviare fatture immediatamente. Se il Taxpayer dovrà anche ricevere, completa la registrazione una tantum presso l’AdE — in qualsiasi momento, prima o dopo il commissioning — consulta la guida Italia. Quindi procedi allo Step 12.

8. Step 11: OPERATION - Carica la Proof of Ownership

   Questo passaggio è richiesto per le integrazioni E-INVOICE BE 🇧🇪 ed E-INVOICE DE 🇩🇪.

   Carica il PDF della Proof of Ownership tramite l’endpoint createRecord, utilizzando un Record di tipo INTENTION e un’operazione di tipo UPLOAD. Il documento inviato viene esaminato e verificato, operazione che può richiedere fino a 72 ore. Una volta completata la verifica, il System passa automaticamente dalla modalità DEGRADED alla modalità OPERATIVE.

   Maggiori dettagli sul contenuto del documento richiesto sono forniti nella sezione Proof of Ownership.

   📘Salta questo passaggio per l'Italia 🇮🇹

   Questo passaggio non si applica alle integrazioni E-INVOICE IT. Procedi direttamente allo Step 12.

9. Step 12: OPERATION - Crea un Record

   ⚠️Importante

   Tutti i Record creati nell’ambiente LIVE sono legalmente validi, pertanto devono sempre rappresentare transazioni commerciali reali e valide.

   La creazione di un Record nell’API E-INVOICE richiede sempre due chiamate successive:

   • Parte A) INTENTION — all’inizio del processo di fatturazione elettronica
   • Parte B) TRANSACTION — una volta che i dati della fattura elettronica sono completi

   📘Utilizzi anche la fiscalizzazione degli scontrini?

   Se il Taxpayer utilizza anche la fiscalizzazione degli scontrini (ad esempio, SIGN IT), crea i Record INTENTION e TRANSACTION sul tuo System FISCAL_DEVICE (uno qualsiasi sullo stesso Taxpayer) — quando è in uso un FISCAL_DEVICE, ha la precedenza. Il System E_INVOICE_SERVICE continua comunque a creare e trasmettere la fattura elettronica a partire da quei dati.

   PARTE A) Intention

   Per ogni operazione di fatturazione elettronica, chiama prima l’endpoint createRecord per registrare l’intenzione di emettere una fattura elettronica.

   Un Record di tipo INTENTION conterrà le seguenti informazioni:

   • Associazione con il System E_INVOICE_SERVICE che verrà utilizzato per emettere la fattura elettronica
   • Operazione di tipo TRANSACTION, che indica che il System intende eseguire un’operazione di fatturazione elettronica.

   Parte B) Transaction

   Successivamente, chiama nuovamente l’endpoint createRecord per creare un Record di tipo TRANSACTION associato all’identificatore interno di un Record di tipo INTENTION già creato. Il tipo di operazione determina il documento emesso.

   Sono supportati i seguenti tipi di operazione:

   • INVOICE: emette una fattura elettronica standard.
   • CORRECTION: emette una nota di credito. Consulta la guida alla Nota di credito per flussi di lavoro e regole dettagliate.

   Una volta elaborata correttamente la Transaction, la fattura elettronica viene creata e gestita secondo i requisiti di fatturazione elettronica applicabili.

   📘Importante

   Per E-INVOICE, il destinatario deve essere di tipo BUSINESS e il blocco invoicing deve essere compilato, altrimenti la fattura elettronica non può essere trasmessa. Il metodo di consegna e i campi obbligatori all’interno del blocco invoicing variano a seconda del paese — fai riferimento alle guide dedicate per ciascun paese qui sotto.

   L’Italia è l’eccezione: sono supportati anche destinatari CONSUMER per le fatture B2C, con un diverso insieme di campi obbligatori. Consulta Invio di fatture elettroniche B2C.

   • Belgio
   • Germania
   • Italia
   • Francia (disponibile a breve)
   • Polonia (disponibile a breve)

Prossimi passi

Guida Belgio

Requisiti specifici per la fatturazione elettronica belga.

Guida Germania

Requisiti specifici per la fatturazione elettronica tedesca.

Proof of Ownership

Scopri il processo di verifica dei documenti.

Riferimento API

Documentazione completa dell'API E-INVOICE.