Ciò che lo SDI non copre
Da anni, ogni fattura tra soggetti IVA italiani viaggia come XML strutturato attraverso il Sistema di Interscambio — il tuo gestionale la legge già in modo nativo, senza bisogno di OCR. Ma la contabilità di un'azienda non è fatta solo di fatture italiane B2B. Un estratto conto bancario mensile, uno scontrino di un dipendente, la fattura di un fornitore estero che non passa dallo SDI, un DDT, una nota spese — tutti questi documenti arrivano ancora come PDF o come una foto scattata con il telefono.
Questa pagina descrive l'API che legge esattamente quella parte — ciò che resta fuori dal circuito elettronico obbligatorio — restituendo uno schema tipizzato invece di un output OCR grezzo che il tuo team dovrebbe ancora interpretare.
Perché costruirlo in casa si arena
Un servizio OCR generico restituisce testo, non campi
Textract, Document AI o un motore OCR generico leggono i pixel — trasformarli in importo, data, causale resta un lavoro di analisi che il tuo team deve scrivere e mantenere da solo.
Le tabelle multi-riga sono la parte difficile
I campi di intestazione sono relativamente semplici. Ricostruire correttamente una tabella di righe su più pagine — con descrizioni che vanno a capo e colonne diverse da fornitore a fornitore — è dove la maggior parte dei progetti interni si ferma per mesi.
Ogni nuovo formato è un ticket, non una funzionalità
Un fornitore mai visto prima, una banca mai vista prima: senza un motore che legge dalla struttura del documento invece che da un modello fisso, ogni nuovo layout diventa una correzione urgente.
L'indice di affidabilità è facile da saltare e costoso da saltare
Senza un segnale di affidabilità per campo, o si controlla tutto a mano (lento) o ci si fida di tutto (dati sbagliati nel gestionale) — costruire bene questo livello è un progetto a sé.
Nessuno di questi punti significa che costruire da soli sia sempre una scelta sbagliata — un gestionale con un parco fornitori molto ristretto e competenze OCR già in squadra può farlo funzionare. Significa che il costo reale del "costruire" è di solito un progetto di più trimestri con manutenzione continua, non un weekend passato a collegare un'API.
Cosa questa API non decide
Non legge le fatture elettroniche XML dallo SDI
Quel canale resta quello che il tuo gestionale già usa — questa API si occupa solo di ciò che arriva fuori dal flusso elettronico obbligatorio.
Non decide la categoria contabile
Restituisce il documento letto e strutturato. Assegnarlo a un conto o a una categoria resta la logica del tuo prodotto, informata dal piano dei conti del tuo cliente.
Non esegue la riconciliazione bancaria al posto tuo
Restituisce dati puliti e affidabili. Abbinare un movimento a una fattura resta la logica del tuo gestionale, che ha il contesto che il documento da solo non ha.
Dove finisce lo SDI e dove inizia questa API
È una distinzione che vale la pena rendere esplicita, perché confonderla porta a integrare la cosa sbagliata. Lo SDI è un canale di trasmissione obbligatorio per le fatture elettroniche italiane — dati già strutturati, già completi, che il tuo gestionale riceve e legge senza bisogno di estrazione. Questa API si occupa di tutto il resto: documenti che nessuna norma obbliga a strutturare, che arrivano ancora come immagine di una pagina.
In pratica, per un gestionale italiano tipico questo significa: estratti conto di ogni banca, scontrini e ricevute, fatture di fornitori esteri che non passano dallo SDI, DDT, note spese e polizze assicurative. Nessuno di questi ha un canale strutturato equivalente allo SDI — restano PDF o scansioni, e restano il punto dove un gestionale continua a dipendere da OCR.
Le chiamate che contano
Quattro endpoint coprono l'intero flusso di estrazione. Sono documentati per intero, con ogni parametro, nella pagina della documentazione API — qui sotto la forma che userai davvero dalla pipeline di ingestione del tuo gestionale.
curl -X POST https://flowparse.io/api/v1/extract \
-H "Authorization: Bearer pf_live_xxx" \
-H "Content-Type: application/json" \
-d '{ "file": "JVBERi0xLjcK...", "filename": "estratto-conto-agosto.pdf" }'
# → { "type":"bank_statement", "pages":3, "billedPages":3,
# "price": { "eur":0.10, "perPageEur":0.035, "complexity":"standard" },
# "data": { "type":"bank_statement", "data": { "transactions":[ ... ],
# "opening_balance":4120.50, "closing_balance":5980.15 } } }curl -X POST https://flowparse.io/api/v1/validate \
-H "Authorization: Bearer pf_live_xxx" \
-H "Content-Type: application/json" \
-d '{ "type": "invoice", "data": { "supplier_name": "Fornitore Estero SRL",
"invoice_number": "2026-114", "total": 980.00, "currency": "EUR" } }'
# → { "valid": true, "issues": [] }/validateè gratuito su ogni piano, il posto giusto per prototipare il tuo modello dati prima di spendere qualcosa sull'estrazione vera e propria. /reconcile e /merge estendono lo stesso modello per abbinare fatture a movimenti bancari e per unire più documenti in un unico export.
Cosa viene letto
| Tipo di documento | Cosa restituisce |
|---|---|
| Estratto conto | Ogni movimento con data, causale, importo firmato, saldo progressivo |
| Fattura estera (fuori SDI) | Fornitore, numero, date, valuta, righe con quantità e prezzo unitario |
| Scontrino o ricevuta | Esercente, data, totale, IVA quando presente, righe se leggibili |
| DDT e nota spese | Data, riferimenti, righe di dettaglio, totale |
Un documento con una tabella di righe su più pagine viene letto come una tabella unica e continua — le righe non vengono duplicate né perse al cambio di pagina, uno degli errori più comuni in una pipeline di estrazione costruita in casa.
Come funziona il prezzo
L'estrazione viene fatturata a pagina, per livelli di complessità — un estratto conto pulito a una pagina costa meno di un documento denso e multi-pagina o di una scansione di bassa qualità. Nessuna licenza per postazione, nessun impegno minimo mensile per iniziare.
curl https://flowparse.io/api/v1/usage \
-H "Authorization: Bearer pf_live_xxx"
# → { "plan":"PRO", "pageRangeEur": { "minEur":0.01, "maxEur":0.15 },
# "balance": { "pages":812, "monthlyRemaining":712, "bonusPages":100 },
# "thisMonth": { "requests":143, "pages":288, "spendEur":8.18 } }Per un fornitore di gestionali, questo si traduce direttamente nel proprio modello tariffario — il costo di leggere un documento diventa un dato noto e prevedibile da inserire nel proprio prezzo per cliente, invece di una voce di infrastruttura cloud opaca.
Come si inserisce nel tuo flusso
Il documento arriva nel tuo gestionale
Caricamento manuale, casella email dedicata o cartella condivisa — dove il tuo prodotto già riceve i documenti.
La tua pipeline chiama /extract
Una sola chiamata POST; JSON strutturato con campi, righe e indice di affidabilità torna indietro.
Applichi la tua soglia di affidabilità
I documenti ad alta affidabilità proseguono automaticamente; quelli incerti vanno in una coda di revisione.
I dati confermati entrano nel gestionale
Direttamente come JSON, oppure esportati via /export come file pronto per la tua importazione.
Un esempio: un estratto conto in ingresso
Un gestionale riceve l'estratto conto mensile di un cliente, inoltrato dalla stessa casella email che già usa per raccogliere le fatture. Il file va a /extract: la risposta contiene 41 movimenti, saldo iniziale e finale, con un indice di affidabilità medio di 0,98 — sopra la soglia di 0,9 impostata dal gestionale per l'inserimento automatico nel libro banca.
| Passaggio | Risultato |
|---|---|
| Estrazione | 0,6 secondi, 3 pagine, €0,10 |
| Controllo saldo | Saldo iniziale + movimenti = saldo finale, verificato |
| Affidabilità media | 0,98 — sopra la soglia di inserimento automatico |
| Revisione umana necessaria | No — inserito direttamente nel libro banca |
Un secondo estratto, scansionato da un cliente che non usa l'home banking, torna con un'affidabilità di 0,79 su un solo movimento con causale poco leggibile. Sotto soglia, va in revisione con quella singola riga evidenziata — non l'intero documento segnato come sospetto.
Costruire in casa contro integrare
| Costruirlo in casa | Integrare questa API |
|---|---|
| Un servizio OCR generico più la tua analisi, la ricostruzione delle righe e l'indice di affidabilità | Uno schema tipizzato da una sola chiamata |
| Tempo di sviluppo misurato in mesi, più manutenzione continua per ogni nuovo formato | Integrazione operativa tipicamente in un giorno o due |
| Infrastruttura da ospitare, monitorare e scalare da soli | Nessuna infrastruttura — prezzo a consumo |
| Ogni regressione di precisione è del tuo team | La qualità dell'estrazione è il prodotto principale di chi la offre |
Nessuno dei due lati di questa tabella è sempre giusto — un gestionale con esigenze di estrazione genuinamente particolari e competenze OCR già in squadra può ottenere un sistema più su misura costruendolo. La maggior parte dei fornitori di software gestionale, soprattutto prima di aver raggiunto il volume che ripaga un sistema proprietario, è meglio servita investendo quel tempo di sviluppo su ciò che differenzia davvero il prodotto — flussi, integrazioni, esperienza utente — piuttosto che sull'OCR.
Precisione e indice di affidabilità
La precisione a livello di campo si attesta intorno al 99% sui layout standard — documenti generati digitalmente da un sistema di fatturazione o di home banking. Un documento scansionato o fotografato può variare di più, ed è esattamente per questo che ogni campo porta il proprio indice di affidabilità invece di un singolo segnale per l'intero documento.
Questa granularità per campo è ciò che permette a una coda di revisione di restare proporzionata al rischio reale — un documento con un solo campo incerto non richiede lo stesso sforzo di revisione di uno dove l'estrazione ha genuinamente faticato ovunque.
Formati di export
Oltre al JSON grezzo, lo stesso documento estratto può essere esportato direttamente in xlsx, csv, o file pronti per Xero, QuickBooks, Sage, DATEV, Zoho Books, NetSuite e altri target — 14 in totale.
curl -X POST https://flowparse.io/api/v1/export \
-H "Authorization: Bearer pf_live_xxx" \
-H "Content-Type: application/json" \
-d '{ "format": "xlsx", "type": "bank_statement", "data": { ... } }'
# → { "format":"xlsx", "filename":"estratto-conto.xlsx",
# "encoding":"base64", "content":"UEsDBB..." }Non esiste un formato nativo per un gestionale italiano specifico — nessun fornitore lo ha ancora integrato direttamente. Il percorso realistico oggi è JSON o Excel/CSV, che la tua routine di importazione già mappa sul tuo modello dati interno, con l'opzione di costruire in futuro un formato di export dedicato una volta che il volume lo giustifica.
Errori e limiti
| Codice | Significato |
|---|---|
| 400 | Richiesta malformata o formato non supportato |
| 401 | Chiave API mancante, non valida o revocata |
| 422 | Nessun dato estraibile nel documento fornito |
| 429 | Saldo pagine esaurito — ricarica per continuare |
| 500 | Errore imprevisto nella generazione della risposta |
Non c'è un limite di richieste al secondo da progettare — l'unico limite è il saldo pagine, che si ricarica immediatamente alla conferma del pagamento, così un picco di documenti a fine mese non richiede una gestione speciale nella tua pipeline di ingestione.
Dal primo test al volume reale
Un gestionale che integra questa API per la prima volta di solito inizia con qualche documento di prova su /extract, conferma che lo schema corrisponde a ciò che la propria logica si aspetta, poi la collega alla pipeline reale una volta calibrata la soglia di affidabilità sul rischio accettabile per i propri clienti.
Da lì, il volume cresce senza cambiare nulla nell'integrazione — la stessa chiamata gestisce dieci documenti al giorno o diecimila, dato che prezzo e capacità sono a consumo invece che legati a un livello di infrastruttura fisso da prevedere in anticipo.
Per chi è pensata
Fornitori di gestionali per PMI
Uno strato di estrazione fin dal primo giorno, senza un progetto OCR di più trimestri prima di poter servire il primo cliente reale.
Team di sviluppo che valutano costruire o integrare
Un'API concreta su cui prototipare prima di impegnare la roadmap su un sistema proprietario.
Piattaforme che migrano da un servizio OCR generico
Uno schema tipizzato per documenti che sostituisce uno strato di analisi costruito a mano sopra un servizio OCR generico.
Software verticali che aggiungono un modulo contabile
Estrazione documenti integrata come funzionalità, senza diventare un team OCR dedicato.
Perché i team smettono di costruirselo da soli
Un primo prototipo di estrazione, testato su una manciata di documenti puliti, sembra ingannevolmente vicino al finito. È solo quando i clienti reali portano fornitori mai visti prima, banche mai viste prima e scontrini fotografati male, che la distanza tra "funziona in demo" e "affidabile abbastanza da fidarsi con dati reali" diventa visibile — di solito dopo che la decisione di costruire è già stata presa e le risorse di sviluppo già impegnate altrove.
Quella manutenzione continua è ciò che, in pratica, è difficile da presidiare dentro un team di un gestionale la cui vera differenziazione dovrebbe essere il flusso di lavoro — non la ricerca OCR. Trattare l'accuratezza dell'estrazione come il prodotto principale di qualcun altro, migliorato continuamente e indipendentemente dal proprio ciclo di rilascio, è dove la maggior parte dei team arriva dopo aver gestito la versione fatta in casa per un anno o due.
Ottieni la tua chiave API
Prendi una chiave API gratuita e prova un documento reale su /extract prima di impegnarti su qualsiasi cosa — nessuna carta di credito richiesta per vedere la forma della risposta sul tuo documento.
Sicurezza e privacy
Caricamento cifrato con TLS end-to-end.
Elaborazione su infrastruttura con controlli allineati a SOC 2.
Il documento originale viene eliminato subito dopo l'elaborazione.
Nulla di ciò che carichi viene mai usato per addestrare modelli di IA.
Per un gestionale che elabora i documenti finanziari dei propri clienti, questo conta tanto per la fiducia dei tuoi clienti quanto per la tua — dettagli completi nella pagina sulla sicurezza.