Processo di integrazione passo dopo passo

Fatturazione elettronica B2B

Emettete fatture elettroniche legalmente conformi tramite la rete PEPPOL per le transazioni B2B.

Supporto multipaese

Belgio, Germania, Italia, Francia e Polonia con conformità normativa specifica per paese integrata.

API unificata

Singola integrazione per la fatturazione elettronica in tutti i paesi supportati con endpoint coerenti.

Prerequisiti

Prima di iniziare, assicuratevi di avere:

• Accesso al HUB di fiskaly (ambiente TEST)
• Conoscenza di base delle API REST e dei flussi di autenticazione
• I dati di registrazione della vostra azienda per la configurazione del contribuente

📘Note

Se avete già integrato SIGN IT o SIGN FR, i passaggi iniziali di configurazione in questa guida saranno probabilmente familiari e potrebbero essere già completati. In tal caso, potete passare direttamente al Passo 10 per esaminare i passaggi aggiuntivi necessari.

Flusso di lavoro di integrazione

📘Importante

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

Configurazione passo dopo passo

1. Passo 1: Registrarsi nel HUB

   Iniziate registrandovi nel HUB di fiskaly.

   
2. Passo 2: Creare account e GRUPPO organizzativo

   La creazione di un account fiskaly è il primo passo, dopodiché è possibile procedere con la configurazione della prima struttura organizzativa della vostra azienda e la generazione della chiave API.

   L’Account rappresenta il fornitore del sistema di cassa o un rivenditore che gestisce il proprio sistema di cassa. È l’organizzazione di livello superiore nella struttura.

   Dopo aver creato il vostro account fiskaly, verrete indirizzati al Selettore dell’organizzazione dove potrete creare il vostro Gruppo. Un Gruppo è un livello intermedio all’interno di un Account che aiuta a organizzare più Unità in cluster logici.

3. Passo 3: Creare la chiave API

   Il passo successivo è generare una chiave API per la vostra Organizzazione tramite il HUB all’interno del vostro Gruppo. Questa coppia di Chiave API e Segreto è necessaria per creare la vostra prima Organizzazione di tipo UNIT (Passo 5).

   💡Ambienti TEST vs. LIVE

   Le chiavi API 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. Passo 4: MANAGEMENT — Creare token

   Iniziate a utilizzare l’API E-INVOICE tramite l’endpoint createToken. Dovrete creare un token per autenticarvi per i passaggi successivi.

2. Passo 5: MANAGEMENT — Creare un'UNITÀ organizzativa

   Continuate creando un’Organizzazione di tipo UNIT tramite l’endpoint createOrganization. Una UNIT rappresenta una singola entità legale (commerciante). Dovrete creare una UNIT per ogni rappresentazione di contribuente che gestite.

   Quando create la vostra prima Organizzazione di tipo UNIT, assicuratevi che sia associata al vostro Gruppo creato tramite il HUB. Per farlo, utilizzate il token generato dalle chiavi API create per il vostro Gruppo. Questo riflette la struttura gerarchica in cui la UNIT è annidata sotto il vostro GROUP, che a sua volta si trova all’interno del vostro ACCOUNT.

3. Passo 6: MANAGEMENT — Creare Subject (chiave API)

   Create un Subject di tipo API_KEY tramite l’endpoint createSubject. La connessione tra l’Organizzazione UNIT e la chiave API viene stabilita tramite l’X-Scope-Identifier (utilizzando l’id dell’Organizzazione appena creata).

4. Passo 7: MANAGEMENT — Creare nuovo token

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

5. Passo 8: OPERATION — Creare contribuente

   Siete ora pronti a creare i Contribuenti necessari per la fatturazione elettronica. Per farlo, utilizzate l’endpoint createTaxpayer. Dovrete impostare il Contribuente di tipo COMPANY.

   A seconda del paese, la configurazione di fiscalizzazione richiesta e i dati del contribuente necessari possono differire, quindi fate riferimento alle guide dedicate per paese:

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

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

   Quando si chiama l’endpoint createTaxpayer, viene automaticamente creata una Posizione di tipo HEAD_OFFICE. Potete confermarlo tramite l’endpoint listLocations.

6. Passo 9: OPERATION — Creare posizione

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

   Per la fiscalizzazione dei ricevuti, è necessario creare una Posizione di tipo BRANCH tramite l’endpoint createLocation per ogni sede aziendale.

   Quando si crea una Posizione di tipo BRANCH, il suo state viene inizialmente impostato su ACQUIRED. Per procedere, è necessario cambiare lo stato in COMMISSIONED utilizzando l’endpoint updateLocation.

7. Passo 10: OPERATION — Creare sistema

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

   A seconda della vostra configurazione, si applica quanto segue:

   • Nuovi clienti che utilizzano solo la fatturazione elettronica: create un singolo Sistema E_INVOICE_SERVICE (solo uno per Contribuente) e collegatelo alla Posizione HEAD_OFFICE che è stata automaticamente creata per voi nel passo 8.

   • Nuovi clienti che utilizzano la fiscalizzazione dei ricevuti e la fatturazione elettronica: create Sistemi FISCAL_DEVICE per i ricevuti e un Sistema E_INVOICE_SERVICE aggiuntivo (uno per Contribuente). Collegate il Sistema E_INVOICE_SERVICE alla Posizione di tipo HEAD_OFFICE e i Sistemi FISCAL_DEVICE a una Posizione di tipo BRANCH.

   • Clienti esistenti con dispositivi fiscali commissionati che aggiungono la fatturazione elettronica: create un Sistema E_INVOICE_SERVICE aggiuntivo e collegatelo alla Posizione di tipo HEAD_OFFICE. Quando viene creato un Contribuente, viene automaticamente generata una Posizione di tipo HEAD_OFFICE con lo stesso ID. Questo può essere verificato elencando le vostre Posizioni.

   Quando si crea un Sistema, il suo stato iniziale è impostato su ACQUIRED. Per procedere con il processo di integrazione della fatturazione elettronica, richiedete la messa in servizio del Sistema E_INVOICE_SERVICE utilizzando updateSystem.

   ⚠️Importante

   Dopo una richiesta di messa in servizio riuscita, il Sistema è in stato COMMISSIONED e inizialmente in modalità DEGRADED fino al completamento del Passo 11.

8. Passo 11: OPERATION — Caricare la prova di proprietà

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

   Ulteriori dettagli sul contenuto richiesto del documento sono forniti nella sezione Prova di proprietà.

9. Passo 12: OPERATION — Creare record

   ⚠️Importante

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

   💡Nota

   La creazione di un Record nell’API E-INVOICE richiederà 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

   PARTE A) Intenzione

   Per ogni operazione di fatturazione elettronica, chiamate 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 Sistema E_INVOICE_SERVICE che verrà utilizzato per emettere la fattura elettronica
   • Operazione di tipo TRANSACTION, indicante che il Sistema intende eseguire un’operazione di fatturazione elettronica.

   Parte B) Transazione

   Chiamate 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.

   Una volta che la Transazione viene elaborata con successo, la fattura elettronica viene creata e gestita in conformità con 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 nel blocco invoicing variano per paese — si prega di fare riferimento alle guide paese dedicate di seguito.

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

   • CORRECTION con data.type = INVOICE: Emette una nota di credito che fa riferimento a una fattura precedentemente trasmessa. La transazione deve includere un riferimento al documento precedente alla fattura originale, e il destinatario deve corrispondere all’originale. Consultate la guida alle note di credito per workflow e regole dettagliati.

   💡Nota

   I Record CORRECTION::INVOICE sono accettati solo da un sistema E_INVOICE_SERVICE.

Prossimi passi

Guida Belgio

Requisiti specifici per la fatturazione elettronica belga.

Guida Germania

Requisiti specifici per la fatturazione elettronica tedesca.

Prova di proprietà

Informazioni sul processo di verifica dei documenti.

Riferimento API

Documentazione completa dell'API E-INVOICE.