E-INVOICE IT per clienti SIGN IT

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

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 per i documenti commerciali

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

Passaggio 1 — Estendere i dati di onboarding del Taxpayer

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 al 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. tax_regime è facoltativo (valore predefinito ORDINARY). Questo blocco è facoltativo a livello di API, ma è richiesto dal SDI per le entità registrate e dovrebbe essere fornito al momento dell’onboarding.

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.

Passaggio 2 — Mettere in servizio un System aggiuntivo

Utilizza createSystem per creare un System E_INVOICE_SERVICE sulla Location del Taxpayer, quindi mettilo in servizio tramite updateSystem.

📘Note

È necessario un solo System E_INVOICE_SERVICE per Taxpayer, collegato alla Location HEAD_OFFICE — che viene creata automaticamente alla creazione del Taxpayer. Questo è separato dai System FISCAL_DEVICE utilizzati per la fiscalizzazione dei documenti commerciali, che sono collegati alle singole Location BRANCH e possono esistere in qualsiasi numero accanto a esso.

Passaggio 3 — Aggiungere il flusso di transazione della fattura

SIGN IT utilizza TRANSACTION::RECEIPT. E-INVOICE IT utilizza un tipo di transazione diverso nello stesso contenitore INTENTION::TRANSACTION:

Fattura B2B → crea una TRANSACTION::INVOICE collegata al System E_INVOICE_SERVICE
Nota di credito → crea una TRANSACTION::CORRECTION con data.type=INVOICE, che fa riferimento alla fattura originale tramite record.id

📘Solo B2B

Sono supportati solo destinatari di tipo BUSINESS. Il destinatario deve avere un blocco invoicing di tipo SDI con un destination_code valido. Le fatture B2C sono attualmente fuori ambito.

Gestione delle risposte del SDI

Esito asincrono

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

💡Tip

Gli esiti del SDI arrivano in genere entro pochi minuti. Tuttavia, la specifica del 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 del SDI è disponibile in logs[].message su tutti e tre i Record.

📘Note

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

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 Invopop (asincrona)	Invopop rifiuta prima di raggiungere il SDI	L’intera catena raggiunge `state=FAILED` — è necessaria una nuova catena per riprovare.
Rifiuto del SDI (asincrono)	Il SDI restituisce `NS`	L’intera catena raggiunge `state=FAILED` — è necessaria una nuova catena per riprovare.

Errori e nuovo invio

Se il 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 del 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

Was this page helpful?