MEGAENGINE

Invoice → JSON API

Un endpoint REST per le fatture italiane. Manda una fattura elettronica — l’XML della FatturaPA, la busta firmata .xml.p7m o lo ZIP che il Cassetto fiscale scarica con le fatture del mese — oppure un PDF, e ricevi un JSON con fornitore, cliente, numero, data, righe di dettaglio, riepilogo IVA, totali e scadenze di pagamento, più l’esito del controllo di quadratura. Dalle fatture elettroniche i dati si copiano dal tracciato, non si leggono a occhio: nessun OCR, nessuna interpretazione. È lo stesso motore che gira dietro Fattura → Excel e JSON, senza un umano che carichi i file.

In arrivo

Questo strumento non è ancora disponibile: lo stiamo preparando con la stessa cura del resto del motore.

Prova «Fattura → Excel e JSON», disponibile ora

Guarda un esempio di risultato

Stato: il contratto è pubblicato, l’endpoint è ancora chiuso

Va detto prima di tutto il resto, perché decide se questa pagina ti serve oggi. L’accesso programmatico di Mega Engine è spento a livello di piattaforma: le chiamate autenticate con una chiave API rispondono 401 finché il gestore non lo attiva. Non è una lista d’attesa e non è marketing: è un interruttore, e la decisione di accenderlo non è tecnica.

Quello che è cambiato, e che questa pagina pubblica: il motore, l’ingresso e il contratto sono quelli veri, non una specifica scritta in anticipo. Le chiamate qui sotto sono le rotte già registrate nel servizio, con i nomi dei parametri, gli header e i codici di errore letti dal codice che le serve. L’esempio di risposta è il risultato di una fattura di esempio pubblica dell’Agenzia delle Entrate, elaborata dal motore di produzione. Se stai valutando l’integrazione, da qui puoi preventivarla: quando l’interruttore si accende, non cambia una riga.

Oggi, senza aspettare: lo stesso motore è usabile da Fattura → Excel e JSON, con lo stesso prezzo e gli stessi file. Se il tuo caso è «mille fatture del mese, una volta al mese», quella strada ti basta: lo ZIP del Cassetto fiscale è un caricamento e un credito. Se il tuo caso è «ogni fattura che arriva, mentre arriva, dentro il gestionale», quello lo fa solo l’endpoint, e serve l’interruttore.

Il contratto

Modello asincrono: crei un lavoro, ricevi un identificativo, leggi l’esito quando è pronto. Base REST: https://megaengine.it/wp-json/mega-engine/v1/. Autenticazione con chiave API nell’header X-ME-API-Key, chiavi conservate solo come hash e legate a scope: per creare un lavoro serve jobs:write, per leggerlo jobs:read. Le chiavi si creeranno da /app/: la sezione della dashboard esiste nel codice ma compare solo quando l’accesso programmatico è attivo, quindi oggi non la trovi.

1. Creare il lavoro

curl -X POST https://megaengine.it/wp-json/mega-engine/v1/jobs 
  -H "X-ME-API-Key: $ME_API_KEY" 
  -F "product=invoice-to-json-api" 
  -F "file=@IT01234567890_FPR01.xml" 
  -F "idempotency_key=fatt-2026-000123"

Il file si manda come multipart/form-data nel campo file. Estensioni accettate: xml, p7m, zip, pdf, fino a 15 MB. Il file viene controllato per estensione, byte iniziali e tipo MIME reale prima che il lavoro parta: un .zip rinominato .xml viene respinto con un messaggio che dice cosa non torna, e non ti viene addebitato nulla. L’idempotency_key è facoltativa e serve a te: due chiamate con la stessa chiave non creano due lavori e non spendono due crediti, così un retry dopo un timeout di rete non raddoppia il costo.

Risposta 201:

{
  "ok": true,
  "job": { "uuid": "8f14e45f-ceea-467a-a1cd-0b4f9b3c2a71", "status": "queued", "product": "invoice-to-json-api" },
  "notify_email": false
}

2. Leggere l’esito

curl https://megaengine.it/wp-json/mega-engine/v1/jobs/8f14e45f-ceea-467a-a1cd-0b4f9b3c2a71 
  -H "X-ME-API-Key: $ME_API_KEY"

Lo stato passa da queued a succeeded o failed. Il file completo del risultato si scarica da GET /jobs/{uuid}/download. Un lavoro ancora in coda si annulla con POST /jobs/{uuid}/cancel, e l’elenco dei tuoi lavori è GET /jobs.

Errori, con i codici veri

  • 401 — chiave assente, non valida, o accesso programmatico non attivo (è il caso di oggi).
  • 403 — la chiave esiste ma non ha lo scope richiesto.
  • 402 — insufficient_credits: crediti finiti. Il lavoro non parte e non viene addebitato.
  • 429 — limite di frequenza superato. I caricamenti hanno un tetto proprio, più severo delle chiamate normali: 10 file ogni 10 minuti per utente.
  • 400 — il file non è accettabile (estensione, dimensione, contenuto che non è una fattura) o il prodotto non è disponibile. Il messaggio è in italiano e dice cosa fare.
  • 503 — provider_unavailable: l’elaborazione non è disponibile in questo momento.
  • Tetto giornaliero: 50 elaborazioni al giorno per account, che contano le chiamate e non le fatture. Uno ZIP con le fatture del mese è una elaborazione sola: è il motivo per cui su un flusso di fatture elettroniche conviene raggrupparle.

Se un lavoro fallisce dopo essere partito, il credito viene riaccreditato e la risposta dice il motivo. Se il file non è una fattura — una ricevuta o una notifica dello SdI, un XML di altro tipo — te lo diciamo prima di cominciare e non viene addebitato nulla.

Un esempio di risposta vero

Non è un mock. Questo è ciò che il motore di produzione restituisce per IT01234567890_FPR01.xml, la fattura di esempio che l’Agenzia delle Entrate pubblica su fatturapa.gov.it: puoi scaricarla e confrontare tu stesso, campo per campo.

{
  "fields": {
    "fornitore": {
      "ragione_sociale": "SOCIETA' ALPHA SRL",
      "partita_iva": "01234567890",
      "indirizzo": "VIALE ROMA 543, 07100 SASSARI (SS)"
    },
    "cliente": {
      "ragione_sociale": "DITTA BETA",
      "codice_fiscale": "09876543210",
      "indirizzo": "VIA TORINO 38-B, 00145 ROMA (RM)"
    },
    "numero_documento": "123",
    "data_documento": "2014-12-18",
    "righe": [
      { "descrizione": "DESCRIZIONE DELLA FORNITURA", "quantita": 5, "prezzo_unitario": 1, "aliquota_iva": "22%", "importo": 5 }
    ],
    "imponibile": 5,
    "iva": [ { "aliquota": "22%", "imponibile": 5, "imposta": 1.1 } ],
    "totale_documento": 6.1,
    "scadenze": [ { "data": "2015-01-30", "importo": 6.1 } ],
    "modalita_pagamento": "contanti (MP01)"
  },
  "tipo": "TD01",
  "divisa": "EUR",
  "note": [
    "La fattura non riporta il totale documento: nel tracciato è un campo facoltativo (ImportoTotaleDocumento) e chi l'ha emessa non l'ha compilato. I 6,10 euro che trovi come totale sono la somma di imponibile e imposta del riepilogo IVA, calcolata da noi: non è un numero scritto nella fattura."
  ]
}

Guarda l’ultima riga, perché è il motivo per cui questo servizio esiste. ImportoTotaleDocumento è un campo facoltativo del tracciato, e la maggior parte dei gestionali non lo compila: su 31 fatture elettroniche vere del nostro corpus di prova, 27 non lo portano — gli esempi ufficiali dell’Agenzia compresi. Un’integrazione scritta in fretta legge null e registra zero, oppure lo calcola e lo passa per un dato del documento. Qui il totale viene calcolato dal riepilogo IVA e dichiarato come calcolo nostro, nel risultato, con la frase che ti spiega perché. Nessun numero inventato, e nessun numero nostro travestito da dato letto.

Al primo livello il file del risultato porta summary, preview, not_found (i campi che il documento non dichiara, per nome), quadratura, quality e download. Il risultato completo — righe, riepilogo IVA, scadenze, tipo di documento, esito della quadratura fattura per fattura, blocco dei valori calcolati e note — ha esattamente la forma documentata sulla pagina di Fattura → Excel e JSON: è lo stesso motore, e le due strade non divergono. Differenza dell’endpoint: consegna solo JSON, senza la copia in Excel che serve a chi apre il file a mano.

Quanto costa

1 credito per chiamata, cioè da 0,49 € a 0,98 € secondo il pacchetto di crediti acquistato. I 3 crediti di benvenuto di ogni account nuovo pagano le prime 3 chiamate, quindi la prova non costa niente.

Il credito si conta per chiamata, non per fattura, e su un flusso di fatture elettroniche questa è la differenza che conta: uno ZIP con le fatture del mese è una chiamata e un credito, fino a 15 MB e 2.000 file, e torna un JSON con tutte le fatture. Chi manda una fattura per volta paga un credito per fattura; chi le raggruppa paga un credito per gruppo. La scelta è tua e la sai prima di chiamare: non ci sono costi a pagina, a campo o a token.

Per chi è

Chi scrive software che qualcun altro usa: gestionali e software di contabilità per PMI, portali fornitori, flussi di approvazione spese, integrazioni fra cassetto fiscale e ERP. E studi di commercialisti con un tecnico interno, che devono far entrare in contabilità le fatture di molti clienti senza aprire un file per volta. Se invece le fatture le apri tu, poche volte al mese, lo strumento web costa uguale e non richiede codice.

Input supportati

Fattura elettronica (FatturaPA). Il file XML, anche nella busta firmata .xml.p7m (in binario o in base64), o lo ZIP del Cassetto fiscale, fino a 15 MB e 2.000 file: ogni .xml e .xml.p7m che contiene viene letto come se fosse arrivato da solo, e le fatture diventano una risposta sola, per un credito. Ricevute, notifiche e metadati dello SdI vengono riconosciuti e lasciati fuori, e il risultato lo dice; la stessa fattura presente due volte — in .xml e in .xml.p7m — si conta una volta; un file che non si apre viene nominato, e il risultato non si dichiara completo. Anche la fattura semplificata (FSM10) si legge. La firma digitale non viene verificata: ne leggiamo il contenuto. Se al posto della fattura mandi una ricevuta o una notifica dello SdI, o un XML che non è una fattura, la risposta lo dice prima di cominciare e non viene addebitato nulla.

PDF. Fatture, pro-forma e note di credito in PDF fino a 15 MB con testo selezionabile, in italiano o in inglese. Un job elabora un documento alla volta, e questo vale anche dentro un solo file: se il PDF che carichi contiene più di una fattura — capita con gli invii mensili di un fornitore e con i PDF scaricati in blocco — il risultato ne riporta una sola. Non te lo lasciamo scoprire in contabilità: quando il file dichiara più di una testata il risultato ti dice quale fattura abbiamo letto, ti elenca i numeri di quelle che non sono nel risultato e non si dichiara completo. Per averle tutte, caricale come lavori separati, un PDF per ciascuna. I PDF fatti solo di immagini — le scansioni che non sono passate da un OCR — non sono ancora supportati: l’elaborazione si ferma subito, viene segnalata come non riuscita e non ti viene addebitato nulla. I PDF protetti da password vengono rifiutati allo stesso modo: senza la password le pagine non si aprono, l’elaborazione si ferma subito e non ti viene addebitato nulla. Apri il file con la sua password, salvane una copia senza protezione e carica quella. Per saperlo prima di caricare: se il PDF si apre senza chiederti una password e riesci a selezionare una riga di testo, il documento si legge — ma la prova vale pagina per pagina. Un documento in parte digitale e in parte scansionato (una pagina fotografata, un allegato firmato a mano) viene elaborato e addebitato, perché il testo delle altre pagine c’è: in quel caso il risultato ti dice quali pagine non contenevano testo selezionabile e che il loro contenuto non è nel file, invece di dichiararsi completo. Se invece da quelle pagine non esce nessuno dei dati che questo strumento estrae — è il caso della copertina digitale generata dal gestionale sopra un documento fotocopiato — l’elaborazione si ferma, non ti viene addebitato nulla e il messaggio ti dice quante pagine sono immagini: il gesto che sblocca è passare il PDF per un OCR, non caricare un altro file. Ogni elaborazione legge al massimo le prime 80 pagine del PDF e, dentro quelle, circa 280.000 caratteri di testo. I due tetti sono tarati per mordere nello stesso punto: misurato l’8 settembre 2026 su dieci documenti di gara italiani veri, è esattamente quanto testo portano ottanta pagine. Solo su un documento molto più fitto della media — un computo metrico, un allegato a righe serrate — è il limite sui caratteri ad arrivare per primo, e la lettura si ferma prima dell’ottantesima pagina. Il risultato dichiara sempre a quale pagina la lettura si è fermata, e il messaggio ti dice da quale pagina ripartire. Se un dato obbligatorio è rimasto oltre il taglio l’elaborazione si ferma e non ti viene addebitato nulla; se invece i dati obbligatori erano tutti nelle pagine lette il risultato ti viene consegnato e i crediti restano spesi, e ciò che non abbiamo trovato è dichiarato come non presente nella parte letta, mai come assente dal documento. In entrambi i casi puoi caricare come lavoro separato un PDF con le pagine che ti servono, tenendo dentro anche le pagine iniziali del documento: questo strumento estrae i suoi dati in una lettura sola, e un PDF con le sole pagine finali verrebbe rifiutato perché i dati di apertura non ci sarebbero.

Risultato

Un JSON solo, senza la copia in Excel che serve a chi apre il file a mano. Al primo livello: summary con i campi della fattura, preview con le coppie etichetta-valore che la pagina del lavoro mostra, not_found con i campi che il documento non dichiara — per nome, non come silenzio — quadratura con l’esito del controllo sui totali, quality e download. Gli importi sono numeri, le date sono date, le partite IVA tengono gli zeri davanti. I campi non presenti in fattura restano assenti e non vengono stimati; l’unico numero che calcoliamo noi è il totale di una fattura elettronica che non lo riporta, e il risultato lo dichiara nel blocco dei valori calcolati.

Questo vale solo per le fatture in PDF: da una fattura elettronica — XML, .p7m o ZIP — le righe arrivano tutte, perché si copiano dal tracciato. In un PDF le righe di dettaglio e le voci del riepilogo IVA sono elenchi, e su un elenco lungo il risultato può contenerne solo una parte anche quando la lettura arriva in fondo al documento. Non è il limite di lettura descritto sopra — quello riguarda quante pagine apriamo — ma quante voci l’elaborazione riesce a restituire, e non c’è una soglia fissa da dirti in anticipo: dipende da quante voci ha l’elenco e da quanto è lunga ognuna. Quando il documento numera le voci — 1), 2), 3) — ce ne accorgiamo e te lo diciamo: il file porta un blocco elenchi_incompleti con la prima voce che manca, e dentro quality il campo complete passa a false. Quando invece il documento le elenca senza numerarle — trattini, puntini, rientri — non abbiamo modo di accorgercene, e un elenco accorciato ti arriva senza nessun avviso. In tutti e due i casi il risultato ti viene consegnato e i crediti restano spesi. Se ti serve l’elenco completo, dividi il documento in più PDF di poche pagine ciascuno, caricali come lavori separati e unisci i risultati.

Limiti

Dalle fatture elettroniche (XML, .p7m, ZIP) i dati si copiano dal tracciato: la firma digitale non viene verificata, ne leggiamo il contenuto. Dai PDF il motore individua intestazione, righe e riepilogo IVA, con i casi limite dichiarati qui sopra. I totali dichiarati vengono ricontrollati sommando le righe: se non tornano, la differenza viene segnalata, non corretta in silenzio. Il servizio estrae i dati e non fa valutazioni fiscali: se una fattura debba essere registrata così, e quale fra totale documento e importo da pagare vada in contabilità, resta una decisione di chi la registra.

Privacy e dati

Una fattura contiene dati fiscali e commerciali di due aziende, e se la manda un’integrazione i dati non sono tuoi: sono dei tuoi clienti. Quindi i numeri, non le rassicurazioni. Il file che carichi viene messo in un archivio privato non raggiungibile dal web, elaborato e poi cancellato; il file del risultato resta scaricabile 14 giorni e poi viene cancellato, mentre lo storico del lavoro può conservare il nome del file e una piccola anteprima anche dopo; il file di ingresso di un lavoro fallito resta fino a 2 giorni per capire cosa è andato storto. I tempi completi sono nella informativa privacy. Nessun documento viene usato per addestrare modelli, e le chiavi API sono salvate solo come hash.

Dove finisce il documento. Da una fattura elettronica, in nessun posto fuori da qui: l’XML si legge sul nostro server, e nessun dato parte verso un modello. Da un PDF sì: il testo estratto dalle pagine viene mandato a OpenAI per individuare i campi, come per lo strumento web — è dichiarato nella pagina Trattamento dati & AI, con la destinazione e i tempi di conservazione dei log del fornitore. Se questo per te è un problema, manda l’XML: è anche la strada più precisa.

Domande frequenti

Posso provarlo oggi?

L’endpoint no: l’accesso programmatico è spento a livello di piattaforma e risponde 401. Il motore sì, e con gli stessi file: Fattura → Excel e JSON accetta XML, .p7m, ZIP e PDF, costa lo stesso credito e restituisce lo stesso JSON (più una copia in Excel). È il modo di verificare la qualità dell’estrazione sui tuoi documenti veri prima di scrivere una riga di integrazione.

Supporta la fattura elettronica XML e i file .p7m?

Sì, ed è il caso in cui serve di più: la busta firmata .xml.p7m si apre da sola, anche quando è scritta in base64, e i dati si copiano dai campi del tracciato invece di essere letti da una copia in PDF. Quindi tutte le righe, importi esatti, e le note di credito, le ritenute, il bollo e la scissione dei pagamenti nominati con il loro importo. Anche la fattura semplificata (FSM10) si legge.

Perché un’API se un parser FatturaPA open source è gratis?

Domanda giusta, e la risposta è onesta: se il tuo flusso è solo XML puliti e ti basta leggere i campi, una libreria gratuita fa il lavoro e non devi pagare niente. Quello che qui non devi scrivere né mantenere è il resto: aprire la busta CAdES del .p7m (in DER e in base64), riconoscere dentro uno ZIP del Cassetto fiscale le ricevute e i metadati dello SdI e lasciarli fuori, contare una volta sola la stessa fattura presente in .xml e in .xml.p7m, gestire il tracciato semplificato, calcolare il totale quando il campo facoltativo manca dichiarandolo, rifare la quadratura su ogni fattura, e — quando la fattura arriva in PDF, come dai fornitori esteri — leggerla senza inventare numeri. È il motivo per cui il prezzo è per chiamata e non per fattura.

Cosa succede se un campo non viene trovato?

Il campo resta assente e il risultato lo dichiara: nessun valore viene inventato per riempire i buchi, e nessun numero calcolato da noi viene consegnato come se fosse scritto nel documento. Quando un importo nel PDF non compare da nessuna parte viene tolto e dichiarato, così uno 0,00 che la fattura non scrive non arriva in contabilità come se lo scrivesse.

Emettete fattura per l’acquisto dei crediti?

No, e per chi integra un servizio in un prodotto aziendale è un’informazione che serve prima di provare: il gestore è una persona fisica senza partita IVA e non emette fattura. Se il tuo acquisto deve essere un costo registrabile, scrivici prima di comprare.