Costruire con InvoiceTronic: fatturazione elettronica senza il dolore

Se hai mai provato a integrarti direttamente con il Sistema di Interscambio italiano — l'SDI — sai di cosa parlo. È un formato XML imposto per legge con la propria versione delle specifiche, requisiti di firma digitale, una pipeline di invio che implica la gestione di certificati, e un modello di stato della consegna che può richiedere ore o giorni per risolversi.

Non volevo nulla di tutto questo. Volevo inviare fatture.

Quindi ho costruito il mio gestionale — una contabilità completa per Honeyside, la mia ditta individuale — sopra InvoiceTronic, una REST API che si frappone tra te e l'SDI e gestisce tutto ciò che non vuoi gestire. Ecco cosa ho imparato.

Cosa richiede davvero l'SDI

La fatturazione elettronica italiana è obbligatoria dal 2019. Ogni fattura tra imprese, e la maggior parte delle fatture B2C sopra certe soglie, deve essere trasmessa attraverso l'SDI in formato FatturaPA — uno schema XML mantenuto da AgID (l'agenzia digitale italiana) attualmente alla versione 1.2.1.

L'XML in sé è gestibile. Ho costruito il generatore da solo usando xmlbuilder2 — il formato è ben documentato e le specifiche sono pubbliche. Quello che non è gestibile da uno sviluppatore solo:

• Firma digitale — le fatture inviate all'SDI devono essere firmate con un certificato qualificato (formato P7M). Ottenere e gestire quel certificato è un processo a sé.
• Protocollo di trasmissione — non si fa un POST direttamente all'SDI. C'è un livello intermediario, credenziali, e un canale da gestire.
• Polling dello stato — dopo l'invio, l'SDI risponde in modo asincrono. La tua fattura potrebbe risultare "consegnata", "scartata", o bloccata nel limbo per ore. Devi gestire tutto questo.
• Ricezione fatture passive — anche le fatture dei tuoi fornitori arrivano attraverso l'SDI. Parsarle e archiviarle è un problema separato.

Nulla di tutto questo è impossibile. È solo molto impianto idraulico che non ha nulla a che fare con la gestione di un'impresa.

Cosa toglie dal piatto InvoiceTronic

InvoiceTronic è, in termini pratici, un intermediario SDI esposto come una REST API pulita. Tu mandi l'XML, lui valida, firma e trasmette. Ricevi uno stato. Quando qualcosa cambia — consegna, rifiuto, arrivo di una fattura fornitore — ti manda un webhook.

Le cose principali che gestisce:

Validazione XML prima dell'invio. L'SDI restituisce codici di scarto criptici; InvoiceTronic ti dà errori dettagliati e leggibili a livello 422 prima che nulla raggiunga il governo. Solo questo, in sviluppo, ha risparmiato ore.

Firma digitale. Non ti serve un certificato. InvoiceTronic firma per tuo conto. Per le fatture al settore privato (B2B/B2C) è opzionale ma consigliata; per la pubblica amministrazione è obbligatoria. In ogni caso, è gestita.

Trasmissione SDI e tracking dello stato. Invii e dimentichi — l'API restituisce un invoicetronicId e da quel momento puoi fare polling o aspettare i webhook.

Ricezione fatture passive. Le fatture dei tuoi fornitori arrivano all'endpoint di InvoiceTronic, vengono inoltrate al tuo sistema via webhook, e tu le parsi dall'XML che consegnano. Un'integrazione sola, entrambe le direzioni.

L'esperienza da sviluppatore

L'API è lineare. L'autenticazione è una API key nell'header Authorization: Bearer. Il base URL è https://api.invoicetronic.com/v1. C'è un ambiente sandbox, gratuito, che ti permette di testare la pipeline completa incluse le risposte SDI simulate.

Inviare una fattura assomiglia a questo:

const response = await fetch(`${INVOICETRONIC_URL}/invoice/send`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ xml: base64EncodedXml }),
});

Gli aggiornamenti di stato arrivano via webhook. Gli eventi che gestisco in produzione:

• invoice.send.updated — una fattura inviata ha cambiato stato (consegnata, scartata, ecc.)
• invoice.update.created — è arrivata una notifica SDI per una fattura inviata
• invoice.receive.created — è arrivata una fattura passiva da un fornitore

Il payload del webhook contiene dati sufficienti per aggiornare lo stato locale senza una chiamata API successiva nella maggior parte dei casi. Quando non bastano — quando ti serve l'XML completo di una fattura ricevuta — c'è un endpoint apposito.

Cosa ho trovato lungo la strada

Non è perfetto. Alcune cose vale la pena sapere se ci stai costruendo sopra:

L'XML delle fatture passive non è sempre immediatamente disponibile. Quando arriva una fattura fornitore, il webhook scatta velocemente — ma l'XML completo a volte richiede qualche minuto prima di essere recuperabile dall'API. Lo gestisco salvando subito i metadati che arrivano con il webhook, poi recuperando l'XML su richiesta (con un pulsante di retry nell'UI per il raro caso in cui non sia ancora disponibile).

Il sandbox si comporta in modo leggermente diverso dalla produzione. I tempi di risposta dell'SDI, i codici di scarto e i flussi di consegna sono simulati in modalità sandbox. Sufficientemente vicino per lo sviluppo, ma non dare per scontato che il comportamento sandbox corrisponda 1:1 alla produzione.

Le sottoscrizioni webhook vanno gestite. InvoiceTronic non ti iscrive automaticamente agli eventi — crei le sottoscrizioni webhook tramite l'API. Le gestisco attraverso una sezione dedicata nel gestionale e le tengo sincronizzate all'avvio.

Nessuno di questi è un blocco. È la normale texture dell'integrazione con qualsiasi API di terze parti. La complessità SDI che InvoiceTronic astrae via è di gran lunga superiore.

Il compromesso

InvoiceTronic è un servizio a pagamento. C'è un costo per ogni fattura trasmessa e ricevuta. Per Honeyside, dove il volume di fatture è basso, il costo è trascurabile rispetto all'alternativa — che sarebbe mantenere il proprio setup come intermediario SDI, con certificati qualificati e integrazione diretta del protocollo.

Quella matematica non funziona per operazioni ad alto volume. Se stai elaborando migliaia di fatture al mese, l'economia cambia e un'integrazione diretta potrebbe avere senso. Per uno studio piccolo o una ditta individuale, è una scelta facile.

Lo userei di nuovo

Sì. Senza esitazione.

Il gestionale che ho costruito copre il ciclo completo della contabilità semplificata per una ditta individuale: fatturazione elettronica in entrambe le direzioni, registri IVA, liquidazioni IVA periodiche, comunicazioni LIPE, generazione F24, piano dei conti, partita doppia e registro cespiti. Mi ha richiesto qualche settimana di serate e weekend.

InvoiceTronic è il motivo per cui il layer della fatturazione ha richiesto giorni, non mesi. La generazione XML, la state machine, la gestione dei webhook — tutto mio. Tutto ciò che riguarda il parlare con lo Stato italiano — loro.

È esattamente la divisione del lavoro che volevo.