Section navigation

E-INVOICE IT per clienti SIGN IT

Stai visualizzando la documentazione per la versione API 2026-06-01.

Questa guida è rivolta ai clienti che dispongono già di un’integrazione SIGN IT funzionante e desiderano aggiungere la fatturazione elettronica italiana (E-INVOICE IT) — B2B e B2C. Entrambi i prodotti si basano sulla stessa API Unificata e condividono la stessa struttura di Taxpayer e Location — sono necessarie solo poche aggiunte.

Vieni da SIGN IT 2024-10-31 o 2025-08-12? Espandi e leggi prima questo.

Dopo la versione 2025-08-12, alcune risorse sono state rinominate e ne sono state introdotte di nuove per la fatturazione elettronica. I nuovi endpoint possono essere richiamati con gli stessi {id} già in uso.

Fino alla versione 2025-08-12	Dopo la versione 2025-08-12	Note
`ASSET` — `/assets`	`ORGANIZATION` — `/organizations`	Solo una rinomina — stesso ID di prima.
`ENTITY` (`COMPANY`/`INDIVIDUAL`) — `/entities`	`TAXPAYER` (`COMPANY`/`INDIVIDUAL`) — `/taxpayers`	Solo una rinomina — stesso ID di prima.
`ENTITY` (`LOCATION`) — `/entities`	`LOCATION` — `/locations`	Questa risorsa è ora divisa in due tipi: `HEAD_OFFICE` location: creata automaticamente alla creazione del Taxpayer — stesso ID del tuo vecchio `ENTITY` (`COMPANY`/`INDIVIDUAL`) `BRANCH` location: qualsiasi location aggiuntiva. Creata tramite l’endpoint `createLocation` — stesso ID del tuo vecchio `ENTITY` (`LOCATION`)
`SYSTEM` con riferimento a `entity: {id}`	`SYSTEM` con riferimento a `location: {id}`	Solo una rinomina — stesso ID di prima.

Prima di continuare:

Aggiorna l’header X-Api-Version alla versione indicata nel banner qui sopra.
Assicurati di puntare agli URL di base corretti: test.api.fiskaly.com (TEST) e live.api.fiskaly.com (LIVE).
Aggiungi fiscalization.credentials.tax_id_number alle tue credenziali FISCONLINE, se non è già presente. Questo campo non era richiesto in 2024-10-31, era opzionale in 2025-08-12, ma ora è obbligatorio.
Rivedi i principali aggiornamenti alla struttura dei record nella documentazione API — questa FAQ può esserti utile. Per qualsiasi domanda, contatta dev-support@fiskaly.com.

Cosa copre già la tua integrazione SIGN IT

Prima di iniziare, si presuppone che la tua integrazione disponga di:

Un Taxpayer creato con dati di fiscalizzazione italiani (fiscalization.type=IT, tax_id_number, vat_id_number, credentials)
Il Taxpayer messo in servizio (state=COMMISSIONED, mode=OPERATIVE)
Un System FISCAL_DEVICE messo in servizio sulla Location del Taxpayer
Un flusso INTENTION::TRANSACTION → TRANSACTION::RECEIPT / TRANSACTION::CORRECTION / TRANSACTION::CANCELLATION per i documenti commerciali

Nulla di tutto ciò deve essere modificato. I passaggi seguenti aggiungono E-INVOICE IT alla configurazione esistente.

Estendere i dati di onboarding del Taxpayer

Aggiungi i dati aggiuntivi di registrazione dell'azienda richiesti dalla fatturazione elettronica italiana.

Mettere in servizio un System aggiuntivo

Abilita il servizio di fatturazione elettronica sul tuo Taxpayer — questo copre l'invio e, facoltativamente, la ricezione.

Aggiungere il flusso di transazione della fattura

Inizia a emettere fatture e note di credito ad aziende e consumatori.

Step 1 — Estendere i dati di onboarding del Taxpayer

📘Per ora solo Taxpayer COMPANY

E-INVOICE IT supporta attualmente i Taxpayer di tipo COMPANY. Un Taxpayer INDIVIDUAL — un libero professionista o una ditta individuale che emette con il proprio codice fiscale invece della partita IVA di un’azienda — non può ancora essere esteso; il supporto arriverà a breve.

Sono necessarie due aggiunte al Taxpayer che SIGN IT da solo non richiede:

address.region — il codice della Provincia italiana (es. MI, RM) è obbligatorio per l’invio all’SDI. Se non è già impostato sul Taxpayer, aggiungilo tramite updateTaxpayer.
fiscalization.registration — un nuovo blocco contenente i dati del Registro delle Imprese / REA.

Campi obbligatori: company_id, office, entry, legal_form, capital, shareholder_status, liquidation_status. Il campo tax_regime usa ORDINARY per impostazione predefinita se non lo indichi.

L’SDI richiede questo blocco per le entità registrate, quindi fornitelo al momento dell’onboarding del Taxpayer.

Esempio: PATCH /taxpayers/{taxpayer_id}

{
  "content": {
    "address": {
      "region": "MI"
    },
    "fiscalization": {
      "type": "IT",
      "registration": {
        "company_id": "MI12345678901234567",
        "office": "MI",
        "entry": "1234567",
        "legal_form": "LIMITED_LIABILITY_COMPANY",
        "capital": "10000.00",
        "shareholder_status": "MULTIPLE_SHAREHOLDERS",
        "liquidation_status": "NOT_IN_LIQUIDATION"
      }
    }
  }
}

💡Hai già address.region?

Se la tua integrazione SIGN IT raccoglie già l’indirizzo completo del Taxpayer, inclusa region, non è necessaria alcuna modifica qui — aggiungi semplicemente il blocco registration.

Step 2 — Mettere in servizio un System aggiuntivo

Il System E_INVOICE_SERVICE è l’unico System che crea e trasmette fatture elettroniche (e riceve quelle in entrata). Non sostituisce i tuoi System FISCAL_DEVICE: continui a creare il record della fattura (TRANSACTION::INVOICE) su un System FISCAL_DEVICE (uno qualsiasi sullo stesso Taxpayer), e il System E_INVOICE_SERVICE trasforma quei dati nella fattura elettronica.

📘Vuoi anche ricevere?

La ricezione è facoltativa. Se la desideri, imposta il codice destinatario SDI di fiskaly JKKZDGR come destinazione SDI della tua azienda nel tuo portale Agenzia delle Entrate (AdE) — in qualsiasi momento, prima o dopo la messa in servizio. Senza di esso il Taxpayer non riceverà fatture, anche una volta che il System è pronto. Salta questo passaggio se il Taxpayer si limiterà a inviare.

Utilizza createSystem per creare un System E_INVOICE_SERVICE sulla Location HEAD_OFFICE del Taxpayer, quindi mettilo in servizio tramite updateSystem impostando il suo state su COMMISSIONED.

⚠️Caution

Per ogni Taxpayer può essere messo in servizio un solo System E_INVOICE_SERVICE, sulla Location HEAD_OFFICE (creata automaticamente insieme al Taxpayer) — la messa in servizio di un secondo fallisce. Resta separato dai System FISCAL_DEVICE usati per la fiscalizzazione dei documenti commerciali, che non vengono influenzati, indipendentemente da quanti ne hai.

📘Se il System resta su TRANSMISSION_ONLY

La risposta alla messa in servizio mostra sempre TRANSMISSION_ONLY; chiama retrieveSystem successivamente per leggere l’effettivo compliance.state del System. Se resta su TRANSMISSION_ONLY anziché passare a TRANSMISSION_RECEPTION, 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.

Per il flusso di ricezione completo, consulta Ricezione di fatture elettroniche sulla pagina Italia.

Step 3 — Aggiungere il flusso di transazione della fattura

SIGN IT utilizza TRANSACTION::RECEIPT / TRANSACTION::CORRECTION / TRANSACTION::CANCELLATION.

E-INVOICE IT utilizza tipi di transazione diversi nello stesso contenitore INTENTION::TRANSACTION:

Fattura (B2B o B2C) → crea una TRANSACTION::INVOICE su un System FISCAL_DEVICE (come nello Step 2)
Nota di credito → crea una TRANSACTION::CORRECTION con data.type=INVOICE, che fa riferimento alla fattura originale tramite record.id

Sono supportati sia i destinatari di tipo BUSINESS sia quelli di tipo CONSUMER. Per un destinatario business, la voce nell’array recipients della fattura necessita di un blocco invoicing di tipo SDI, oltre alla Provincia del destinatario:

recipients[].type = BUSINESS
recipients[].invoicing.type = SDI
recipients[].invoicing.destination_code — il codice di 7 caratteri della casella SDI del destinatario
recipients[].invoicing.pec — (dove richiesto) l’indirizzo PEC del destinatario
recipients[].address.region — la Provincia del destinatario (es. MI, RM)

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

⚠️Indica la Provincia del destinatario

Imposta la Provincia del destinatario in recipients[].address.region. 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.

Per un destinatario consumatore (B2C) i campi sono diversi: nessun destination_code a scelta del destinatario e nessuna partita IVA, ma il codice fiscale è obbligatorio:

recipients[].type = CONSUMER
recipients[].identification.type = TAX, con number impostato sul codice fiscale del consumatore
recipients[].name — gender, forename e surname
recipients[].address — l’indirizzo di residenza del consumatore, inclusa la region (Provincia)
recipients[].invoicing.destination_code = "0000000", con pec facoltativa

📘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 i requisiti completi del destinatario, consulta Invio di fatture elettroniche sulla pagina Italia.

Quando il cliente ha bisogno della fattura invece del documento commerciale

I tuoi due flussi trasmettono a destinazioni diverse — il documento commerciale all’AdE, la fattura all’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 sul System E_INVOICE_SERVICE al posto del documento commerciale. È 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

Esito asincrono

A differenza dei flussi dei documenti commerciali, l’esito dell’SDI è asincrono. Dopo aver creato la TRANSACTION::INVOICE, interroga o resta in ascolto degli aggiornamenti sul Record E_INVOICE::TRANSMISSION.

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

Le fatture elettroniche inviate e ricevute vengono conservate automaticamente a lungo termine (conservazione a norma, almeno 10 anni), con una ricevuta di conservazione disponibile dall’archive-artifact del Record. Non è richiesta alcuna configurazione. Per i dettagli, consulta Archiviazione sulla pagina Italia.

📘Note

L’artefatto di conformità per la fatturazione elettronica italiana è l’XML FatturaPA, accessibile sul Record E_INVOICE::TRANSMISSION.

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:

Leggi logs[].message su uno qualsiasi dei tre Record per ottenere il motivo del rifiuto dell’SDI
Crea una nuova INTENTION::TRANSACTION e una nuova TRANSACTION::INVOICE con i dati corretti
Lo stesso document.number può essere riutilizzato entro 5 giorni dal rifiuto NS
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.

Cosa non cambia

Quanto segue rimane completamente invariato:

Il flusso di messa in servizio del Taxpayer e le credenziali Fisconline
Tutti i System FISCAL_DEVICE e le Location BRANCH
Il tuo flusso esistente di documenti commerciali INTENTION::TRANSACTION → TRANSACTION::RECEIPT / TRANSACTION::CORRECTION / TRANSACTION::CANCELLATION