Italia — E-INVOICE IT (Unified API)

In Italia, fiskaly supporta l’invio di fatture elettroniche B2B e B2C e la ricezione di fatture elettroniche B2B. Attualmente supportiamo la Fattura standard (Fattura, TD01). Il supporto per la Fattura semplificata (Fattura semplificata, TD07) sarà presto disponibile.

La fatturazione elettronica è obbligatoria e disciplinata dall’Agenzia delle Entrate. Tutte le fatture B2B devono essere scambiate tramite l’SDI (Sistema di Interscambio) nel formato XML FatturaPA (Fattura elettronica) e sono obbligatorie per legge dal gennaio 2019. Le fatture devono inoltre essere conservate a lungo termine tramite archiviazione certificata (conservazione a norma).

Questa pagina illustra i requisiti specifici per l’Italia che completano la Guida all’integrazione generale passo dopo passo per l’onboarding di un Taxpayer ai fini della fatturazione elettronica.

fiskaly gestisce entrambe le direzioni dello scambio con l’SDI, che però funzionano in modo diverso:

📤

Invio — B2B e B2C

fiskaly genera la FatturaPA e la trasmette all'SDI, che la valida e la inoltra al destinatario in modo asincrono. Non è richiesta alcuna registrazione alla rete. I destinatari business e i consumatori richiedono campi diversi.

📥

Ricezione — solo B2B

Facoltativa e abilitata per ciascun Taxpayer. Richiede una registrazione una tantum per ricevere le fatture dei tuoi fornitori.

Oltre a gestire entrambe le direzioni, fiskaly archivia automaticamente ogni fattura che invii e ricevi. Questo garantisce la conservazione certificata a lungo termine (conservazione a norma) per i 10 anni previsti dalla legge, senza alcuna configurazione da parte tua.

🗄️

Archiviazione

Come le fatture elettroniche vengono conservate e come recuperare l'XML FatturaPA e la ricevuta di conservazione tramite l'API.

💡Utilizzi già SIGN IT?

Se hai già un’integrazione SIGN IT, non parti da zero — estendi il tuo Taxpayer esistente con i dati di registrazione aggiuntivi e metti in servizio un System E_INVOICE_SERVICE. Consulta E-INVOICE IT per i clienti SIGN IT per tutti i passaggi.

Prerequisiti

Questi requisiti si applicano a qualsiasi Taxpayer di cui esegui l’onboarding per la fatturazione elettronica in Italia — sia che tu invii, riceva o faccia entrambe le cose. Assicurati di avere a disposizione le seguenti informazioni sul Taxpayer prima di procedere.

📘Per ora solo Taxpayer COMPANY

E-INVOICE IT supporta attualmente i Taxpayer di tipo COMPANY. L’onboarding di un Taxpayer INDIVIDUAL — un libero professionista o una ditta individuale che emette con il proprio codice fiscale invece della partita IVA di un’azienda — arriverà a breve.

Dati di registrazione specifici per l’Italia — trasmessi in content.fiscalization.registration:

• company_id — Numero Registro Imprese
• office — sigla della provincia della Camera di Commercio che ha rilasciato il numero REA, es. MI, RM
• entry — numero REA (6 o 7 cifre)
• legal_form — forma giuridica dell’entità (es. LIMITED_LIABILITY_COMPANY, JOINT_STOCK_COMPANY)
• capital — capitale sociale registrato in EUR (es. "10000.00")
• shareholder_status — SOLE_SHAREHOLDER o MULTIPLE_SHAREHOLDERS
• liquidation_status — IN_LIQUIDATION o NOT_IN_LIQUIDATION
• tax_regime — facoltativo, ORDINARY (predefinito) o FLAT_RATE_SCHEME (Regime Forfettario)

Campi standard del Taxpayer — parte del Taxpayer stesso (condivisi con SIGN IT se lo utilizzi):

• content.name — denominazione legale registrata dell’azienda o del soggetto
• content.address — indirizzo legale registrato
• content.address.region — Provincia (codice provincia, es. MI, RM); obbligatorio sul Taxpayer e validato al momento della messa in servizio

📘Il campo region è obbligatorio per E-INVOICE

Per la fatturazione elettronica in Italia, content.address.region (Provincia) è un campo obbligatorio sul Taxpayer. Viene validato al momento della messa in servizio del System E_INVOICE_SERVICE — se region è mancante, la messa in servizio fallisce. Assicurati che sia impostata o aggiornata sul Taxpayer in anticipo.

Invio di fatture elettroniche: requisiti del destinatario

Per inviare una fattura elettronica indichi il destinatario e i suoi dati di routing direttamente nel Record della fattura. Quando crei la fattura (TRANSACTION::INVOICE) con createRecord, aggiungi il destinatario al suo array recipients. I campi da valorizzare dipendono da chi stai fatturando:

🏢

Destinatari business (B2B)

Instradati tramite il codice destinatario SDI, o via PEC se non hanno una casella SDI.

🧑

Destinatari consumatori (B2C)

I residenti in Italia sono identificati dal codice fiscale, i consumatori all'estero da un identificativo estero.

Ogni destinatario ha invoicing.type = SDI. Ciò che cambia tra i tre casi è l’identificazione, il codice destinatario e la presenza o meno di una PEC:

	Business	Consumatore in Italia	Consumatore all’estero
type	BUSINESS	CONSUMER	CONSUMER
identification	VAT — validata	TAX — codice fiscale, validato	qualsiasi tipo; non validato
invoicing.destination_code	il codice di 7 caratteri del destinatario, oppure "0000000" o "XXXXXXX"	"0000000"	"XXXXXXX"
invoicing.pec	obbligatoria con "0000000"	facoltativa	non utilizzata
address.region	obbligatoria quando l’indirizzo è in Italia	obbligatoria	non obbligatoria
name	ragione sociale	gender, forename, surname	gender, forename, surname

📘Quale codice destinatario inviare?

• Il codice di 7 caratteri che ti ha comunicato il destinatario (es. ABC1234): solo lettere maiuscole e cifre.
• "0000000": il destinatario non ha una casella SDI, come tutti i consumatori e le aziende che ricevono via PEC.
• "XXXXXXX": il destinatario è all’estero.

Destinatari business (B2B)

Ogni destinatario business è di tipo BUSINESS con il blocco invoicing compilato, come spiega l’integrazione generale passo a passo. Oltre ai dati standard richiesti da ogni fattura elettronica (nome del destinatario, indirizzo, identificazione fiscale, righe della fattura e così via), l’Italia aggiunge i campi di routing SDI indicati sopra.

I valori che destination_code e pec assumono dipendono dal destinatario:

Scenario	destination_code	pec
Il destinatario ha una casella SDI registrata	il suo codice di 7 caratteri (es. ABC1234)	facoltativo
Il destinatario non è registrato all’SDI	"0000000"	obbligatorio
Il destinatario è fuori dall’Italia	"XXXXXXX"	non utilizzato

📘Indirizzi PEC

Una pec è un indirizzo di Posta Elettronica Certificata. L’SDI verifica il dominio, quindi una casella di posta ordinaria viene rifiutata.

"0000000" significa consegna via PEC, ed è per questo che in quel caso la pec è obbligatoria per un destinatario business.

⚠️Indica la region (Provincia) del destinatario

recipients[].address.region (la Provincia del destinatario) non è contrassegnata come obbligatoria nello schema condiviso della Unified API, ma l’Italia la richiede ogni volta che l’indirizzo è in Italia. Non viene verificata alla creazione del Record: createRecord va a buon fine e la trasmissione fallisce più tardi, portando l’intera catena a FAILED. Impostala fin da subito, invece di scoprirlo in modo asincrono.

Destinatari consumatori (B2C)

Quando il tuo cliente è una persona fisica e non un’azienda, imposta recipients[].type su CONSUMER. La fattura passa dall’SDI come documento FatturaPA (TD01), come una fattura B2B.

I consumatori non hanno una casella SDI, quindi il routing funziona in modo diverso. Il modo in cui identifichi il consumatore dipende dalla sua residenza in Italia:

• Residente in Italia — identificato dal codice fiscale, instradato con il codice destinatario "0000000".
• Fuori dall’Italia — non esiste alcun codice fiscale, quindi al suo posto subentra un identificativo estero e la fattura viene instradata con "XXXXXXX".

Oltre ai campi della tabella qui sopra, un destinatario consumatore riporta sempre name.gender, name.forename e name.surname, insieme al suo indirizzo.

Consumatori residenti in Italia

Invia il codice fiscale come identificazione di tipo TAX (16 caratteri), l’indirizzo di residenza inclusa la region (Provincia) e il codice destinatario "0000000". Una pec può essere aggiunta, ma non è obbligatoria.

⚠️Il codice fiscale viene validato

Per un consumatore residente in Italia l’identificazione è obbligatoria, deve essere di tipo TAX e il codice fiscale viene verificato già alla creazione del Record: se manca o è formalmente errato, la richiesta viene rifiutata lì e nessuna fattura viene creata. L’SDI lo valida di nuovo nel registro tributario, quindi un codice formalmente corretto ma sconosciuto viene rifiutato in quella fase.

Consumatori fuori dall’Italia

Un consumatore non residente in Italia non ha un codice fiscale: invia al suo posto un identificativo estero, di norma un numero fiscale o di partita IVA estero.

Campo	Valore
recipients[].identification	obbligatoria; VAT, TAX, PASSPORT, DOCUMENT o OTHER, a seconda dell’identificativo di cui disponi
recipients[].address.country	il Paese del consumatore come codice ISO 3166-1 alpha-2
recipients[].address.code	"00000" — FatturaPA accetta solo un CAP di 5 cifre
recipients[].invoicing.destination_code	"XXXXXXX"

L’identificativo viene trasmesso all’SDI come IdCodice; né fiskaly né l’SDI ne verificano la validità quando il Paese dell’indirizzo non è l’Italia. La region non è obbligatoria per un indirizzo non italiano.

⚠️Consegna tu la copia leggibile

"XXXXXXX" segnala all’SDI che si richiede il nulla osta ma che la consegna tramite il sistema di interscambio non si applica: l’SDI non ha alcun canale per raggiungere un destinatario all’estero. Invia al consumatore la sua copia della fattura (PDF o equivalente) separatamente, fuori dall’SDI.

📘Se non disponi del sesso del consumatore

gender è richiesto dalla Unified API, non dall’SDI: la fattura FatturaPA non prevede alcun campo di questo tipo. Invia DIVERSE quando non hai il dato.

Per un consumatore residente in Italia, l’SDI deposita la fattura originale nella sua area riservata sul portale AdE (Fatture e Corrispettivi).

Quando il cliente ha bisogno della fattura invece del documento commerciale

L’Italia trasmette i due documenti su canali separati — il documento commerciale tramite i corrispettivi, la fattura tramite l’SDI — e nulla li collega automaticamente.

Raccogli la richiesta prima che la vendita venga chiusa. Quando il cliente ti comunica che ha bisogno di una fattura, emetti una TRANSACTION::INVOICE al posto di una TRANSACTION::RECEIPT. È il flusso che fiskaly supporta oggi da un capo all’altro, sia che il cliente lo chieda prima sia durante la vendita.

📘Il passaggio da documento commerciale a fattura è in sviluppo

Stiamo realizzando un percorso supportato che collega tra loro un documento commerciale fiscalizzato e una fattura elettronica, in modo che una stessa operazione porti una sola fattura e un solo percorso di audit. Fino ad allora, raccogli la richiesta di fattura prima che la transazione venga chiusa.

Gestione delle risposte dell’SDI

A differenza di una chiamata API sincrona, l’esito dell’SDI è asincrono. Dopo aver creato la fattura (TRANSACTION::INVOICE) con createRecord, interroga o resta in ascolto degli aggiornamenti sul Record E_INVOICE::TRANSMISSION per sapere se l’SDI l’ha accettata.

💡Tip

Gli esiti dell’SDI arrivano in genere entro pochi minuti. Tuttavia, la specifica dell’SDI consente fino a 48 ore.

Tutti e tre i Record raggiungono il loro stato finale insieme:

Record	Stato finale
E_INVOICE::TRANSMISSION	COMPLETED o FAILED, mode=FINISHED
TRANSACTION::INVOICE	COMPLETED o FAILED, mode=FINISHED
INTENTION::TRANSACTION	COMPLETED o FAILED, mode=FINISHED

In caso di errore, il motivo del rifiuto dell’SDI è disponibile in logs[].message su tutti e tre i Record. Per maggiori dettagli, consulta How to check the status of an e-invoice sulla nostra pagina di supporto.

Fasi di errore

Gli errori possono verificarsi in tre fasi distinte, ciascuna con un comportamento diverso:

Fase	Quando	Comportamento
Validazione UAPI (sincrona)	Payload non valido	Viene restituito immediatamente 4xx — nessun Record viene creato. Correggi il payload e riprova sullo stesso INTENTION::TRANSACTION.
Validazione pre-SDI (asincrona)	La fattura viene rifiutata prima di raggiungere l’SDI	L’intera catena raggiunge state=FAILED — è necessaria una nuova catena per riprovare.
Rifiuto dell’SDI (asincrono)	L’SDI restituisce NS	L’intera catena raggiunge state=FAILED — è necessaria una nuova catena per riprovare.

Errori e nuovo invio

Se l’SDI restituisce NS (Notifica di Scarto), la fattura è giuridicamente inesistente:

1. Leggi logs[].message su uno qualsiasi dei tre Record per ottenere il motivo del rifiuto dell’SDI
2. Crea una nuova INTENTION::TRANSACTION e una nuova TRANSACTION::INVOICE con i dati corretti
3. Lo stesso document.number può essere riutilizzato entro 5 giorni dal rifiuto NS
4. La catena fallita rimane FAILED in modo permanente — viene conservata a fini di audit

⚠️Nessun nuovo tentativo automatico

Ogni nuovo invio avvia una nuova catena di transazione — UAPI la tratta come un invio del tutto nuovo.

Ricezione di fatture elettroniche

Un System E_INVOICE_SERVICE può sia inviare che ricevere fatture elettroniche. La ricezione è facoltativa — un Taxpayer che si limita a inviare può saltare questa sezione.

Sono coinvolte due cose distinte e indipendenti:

• Predisposizione alla ricezione — fiskaly la configura automaticamente quando metti in servizio il System.
• Registrazione del codice destinatario SDI (manuale, a tua cura) — nel tuo portale dell’Agenzia delle Entrate (AdE), imposta il codice destinatario SDI di fiskaly JKKZDGR come destinazione SDI della tua azienda, in modo che l’SDI instradi le tue fatture in entrata verso fiskaly.

La risposta alla messa in servizio mostra compliance.state come TRANSMISSION_ONLY. Passa poi automaticamente a TRANSMISSION_RECEPTION una volta completata la registrazione del Taxpayer — cosa che normalmente avviene, indipendentemente dal fatto che tu abbia effettuato la registrazione presso l’AdE o intenda ricevere.

⚠️Pronto a ricevere non è la stessa cosa di ricevere

TRANSMISSION_RECEPTION significa che il System è in grado di ricevere, ma non che le fatture in entrata vengano effettivamente recapitate al Taxpayer. Tale recapito richiede la registrazione presso l’AdE: finché non è attiva, il Taxpayer non riceve alcuna fattura, anche se il System è pronto. Puoi completare la registrazione presso l’AdE in qualsiasi momento — ad esempio, per abilitare la ricezione su un Taxpayer precedentemente configurato solo per l’invio.

Chiama retrieveSystem in qualsiasi momento per leggere lo stato attuale di compliance.state, che riflette solo la predisposizione — non la registrazione presso l’AdE:

• TRANSMISSION_RECEPTION — fiskaly ha configurato il System per la ricezione.
• TRANSMISSION_ONLY — quella configurazione non è stata completata.

📘Se il System resta su TRANSMISSION_ONLY

Se retrieveSystem continua a restituire compliance.state = TRANSMISSION_ONLY dopo la messa in servizio, la registrazione del Taxpayer non è stata completata. Trattalo come una transizione bloccata e contatta il supporto fiskaly all’indirizzo dev-support@fiskaly.com indicando la partita IVA del Taxpayer, in modo da poter indagare.

Non c’è nulla di aggiuntivo da configurare per l’instradamento: fiskaly abbina automaticamente ogni fattura in arrivo al Taxpayer corretto utilizzando il suo codice fiscale — motivo per cui ogni codice fiscale deve appartenere a un solo Taxpayer registrato. Non è necessario configurare o memorizzare un codice di instradamento separato.

Quando arriva una fattura

Quando ti viene inviata una fattura tramite l’SDI, fiskaly la riceve automaticamente:

• la consegna in entrata attiva un webhook
• viene creato un record di ricezione per la fattura
• l’XML firmato, il PDF e i metadati vengono archiviati insieme al record
• le consegne duplicate vengono deduplicate

In pratica, la prima fattura che ti raggiunge in questo modo è anche la conferma che la ricezione è configurata correttamente.

📘Utilizzi E-INVOICE senza SIGN IT?

Se stai integrando E-INVOICE IT senza SIGN IT, contatta il supporto fiskaly all’indirizzo dev-support@fiskaly.com — ti guideremo nella configurazione del Taxpayer per il tuo caso specifico.

Archiviazione

La legge italiana richiede che le fatture elettroniche siano conservate a lungo termine tramite archiviazione digitale certificata (conservazione a norma): devono essere conservate per almeno 10 anni e memorizzate in modo che rimangano immutabili, autentiche e facilmente recuperabili, con firme digitali e marche temporali (marca temporale). Conservare una propria copia dell’XML non è sufficiente — fiskaly se ne occupa per te.

Per l’Italia, l’archiviazione è automatica e sempre attiva: ogni fattura che invii e ogni fattura che ricevi tramite l’SDI viene conservata legalmente, senza alcuna configurazione aggiuntiva o chiamata API da parte tua. Si basa unicamente sul codice fiscale italiano del Taxpayer, che fa già parte dell’onboarding. Ogni fattura conservata riceve una ricevuta di conservazione come prova della conservazione a norma. La conservazione si completa di solito in pochi secondi; la ricevuta stessa può richiedere alcuni minuti per essere emessa, dopodiché fiskaly la allega automaticamente — non è richiesto nulla da parte tua.

Recupera gli artefatti di una fattura elettronica dal suo record con retrieveRecord, selezionando l’artefatto tramite un parametro di query:

• compliance-artifact — il documento con valore legale. Per l’Italia, l’XML FatturaPA validato dall’SDI.
• archive-artifact — la ricevuta di conservazione che attesta la conservazione legale (conservazione a norma), disponibile come PDF leggibile e come XML firmato per uso di audit o legale.

📘Test vs live

Nell’ambiente di test l’archiviazione viene eseguita per intero, ma il risultato non ha validità legale — è solo a scopo di test di integrazione. Solo le fatture elaborate in live sono certificate come legalmente conservate.