API per software di contabilità

Perché la contabilità è affidabile solo quanto i dati che riceve

La riconciliazione bancaria e il matching fattura-pagamento sono affidabili solo quanto l'input più debole tra i due, e il documento è di solito quello che arriva come PDF non strutturato da una parte esterna che il tuo software non controlla. Una logica di matching costruita su dati di documento incompleti produce falsi disallineamenti che erodono la fiducia nell'automazione, anche quando i dati bancari sottostanti sono perfettamente accurati.

Non è un caso limite ipotetico — è lo stato normale di un software di contabilità in crescita. Man mano che il numero di clienti cresce, cresce anche la diversità dei fornitori, e una logica di lettura che funzionava bene solo su un set ristretto di formati ben educati si rompe esattamente dove conta di più: la coda lunga di fornitori mai visti di un nuovo cliente nelle prime settimane.

Cosa legge

flowparse.io

Quali campi vengono estratti

Come funziona

Un lotto di documenti misti, elaborato

Un software di contabilità che fa l'onboarding di un nuovo cliente elabora un primo lotto di 24 documenti tra estratti conto, scontrini e fatture estere, diversi fornitori mai visti prima.

Tutti i 24 documenti sono confluiti nello stesso output strutturato — l'onboarding del nuovo cliente non è stato rallentato dal suo parco fornitori insolito, proprio la situazione in cui un parser interno costruito su un set ristretto di modelli tende a faticare di più.

Un software di contabilità ad alto volume, su scala

Un software di contabilità più grande elabora circa 30.000 documenti al mese su centinaia di clienti e diverse migliaia di fornitori distinti.

Nessuno di questi miglioramenti ha richiesto cambiamenti alla logica di matching o approvazione del software — è cambiato solo ciò che la alimentava. Il tempo di sviluppo liberato dalla manutenzione dell'estrazione è andato invece a un flusso di approvazione più rapido e a una coda di revisione delle eccezioni ridisegnata, le due funzionalità che il feedback dei clienti chiedeva davvero.

Cosa significa precisione su più tipi di documento

La precisione a livello di campo su un documento generato digitalmente si colloca vicino alla parte alta dell'intervallo, indipendentemente dal fornitore che lo ha emesso. Un documento scansionato o fotografato introduce più variabilità, ed è esattamente lì che l'indice di affidabilità per campo si dimostra utile — segnalando i campi specifici che meritano un secondo sguardo invece di trattare l'intero documento come sospetto.

Su un parco fornitori tipico e diversificato, la precisione complessiva a livello di campo si attesta intorno al 99% — e poiché la lettura non dipende da un modello fisso legato a un fornitore, un fornitore che cambia layout, o un cliente che cambia fornitori, non richiede al tuo software di accorgersene e adattarsi.

Questa coerenza tra fornitori, più che il numero complessivo di precisione da solo, è di solito la cosa più utile da valutare — un software che serve centinaia di clienti incontrerà inevitabilmente migliaia di layout di fornitori diversi nel tempo, ed è il comportamento della lettura sui layout mai visti prima a determinare se la precisione regge in produzione, non solo la precisione su un set di test curato.

flowparse.io

Formati di output

JSON per impostazione predefinita per l'integrazione diretta nel tuo modello dati, oppure Excel, CSV e 14 formati contabili via /export quando il tuo software deve consegnare direttamente un file pronto per il commercialista o per il cliente.

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": { ... } }'

Manuale contro integrato

Il divario si allarga con la complessità del documento, non si riduce — un documento a una riga è gestibile in entrambi gli approcci. Un documento a quaranta righe con più pagine è esattamente dove un'analisi solo per intestazione perde silenziosamente la propria affidabilità, ed è proprio quel tipo di documento a diventare più comune man mano che un software matura.

Da un primo test al volume di produzione

La stessa chiamata gestisce un'integrazione pilota che elabora una manciata di documenti al giorno o un software in produzione che ne elabora decine di migliaia al mese — lo sforzo di revisione cresce con le eccezioni segnalate, non con il volume grezzo, dato che prezzo e capacità sono a consumo invece che legati a un livello di infrastruttura da prevedere in anticipo.

Situazioni comuni che gestisce

Un nuovo cliente il cui parco fornitori è del tutto sconosciuto al tuo software — letto allo stesso modo di un fornitore già noto, senza ritardo nell'onboarding in attesa di costruire un nuovo modello. Un fornitore che cambia sistema di fatturazione a metà rapporto, con un layout completamente diverso — letto senza interruzioni, dato che l'estrazione non dipende da un modello fisso legato a un layout. Un documento con una colonna descrizione-e-codice-articolo unita, o senza colonna IVA — le colonne effettivamente presenti vengono lette e restituite, invece che far fallire l'intera estrazione.

In ogni caso, il valore non è una funzionalità dedicata costruita per quella situazione specifica — lo stesso processo di lettura generale li gestisce tutti senza richiedere al tuo team di sviluppo di costruire una soluzione ad hoc.

Un documento con importi in una valuta diversa dall'euro o con un formato di data insolito per il tuo parco clienti prevalentemente italiano — letto e normalizzato allo stesso modo di un documento familiare, così il primo fornitore estero di un cliente non diventa un ticket di supporto. Un fornitore ricorrente la cui fattura include intenzionalmente un arrotondamento da un credito precedente — letto come stampato, con l'arrotondamento visibile nelle righe invece di essere silenziosamente appianato.

Cosa cambia specificamente per l'onboarding di un nuovo cliente

L'onboarding è il momento in cui l'affidabilità dell'estrazione conta di più e viene messa alla prova più duramente — un nuovo cliente tipicamente importa un arretrato di documenti storici da fornitori che il tuo software non ha mai elaborato prima, tutti insieme, senza un periodo di rodaggio graduale che smussi eventuali imperfezioni. È esattamente lo scenario in cui un parser interno basato su modelli fissi fatica di più, perché è il momento in cui la diversità dei fornitori è al massimo rispetto a ciò per cui il parser è stato davvero calibrato.

Poiché la lettura qui si basa sulla struttura propria di ogni documento invece che sull'esposizione precedente a quel fornitore specifico, la precisione durante l'onboarding di un nuovo cliente resta la stessa della precisione a regime di un cliente consolidato — non c'è un periodo di rodaggio durante il quale l'esperienza di un nuovo cliente è percepibilmente peggiore di quella di uno già affermato.

Questo conta particolarmente per la reputazione commerciale del tuo software — un nuovo cliente che confronta più fornitori durante le prime settimane forma un'impressione duratura proprio in quella finestra, e un'estrazione che inciampa sui suoi documenti specifici è un modo costoso di perdere quella prima impressione.

Chi la usa

Ognuno di questi ruoli tocca l'estrazione documenti in un punto diverso del proprio flusso — un team di integrazione ERP durante la migrazione iniziale di un cliente, un'équipe di sviluppo gestionale ogni volta che riceve un documento nuovo. La stessa API serve tutti e tre senza richiedere un'impostazione diversa per ciascuno.

Integrarla nella tua pipeline

Per un software che riceve documenti da decine o centinaia di fornitori ogni giorno, questa API è pensata per essere chiamata direttamente da dove i documenti già arrivano — una casella email condivisa, un portale fornitori, un sistema di gestione documentale già in uso — senza che una persona debba toccare ogni singolo documento.

La maggior parte dei team inizia con qualche chiamata di test manuale per confermare che la forma della risposta corrisponda al proprio modello dati interno, poi la collega alla pipeline reale una volta calibrata la soglia di affidabilità sulla propria tolleranza al rischio.

Cosa non fa

Questo confine è deliberato: leggere e strutturare documenti in modo affidabile è qualcosa che si può automatizzare con alta fiducia, indipendentemente da quanti fornitori o clienti siano coinvolti. Decidere come il tuo software debba categorizzare quei dati resta una scelta che dipende dal contesto specifico di ogni cliente — un contesto che solo il tuo software ha.

Sicurezza

I documenti caricati vengono elaborati cifrati e non vengono condivisi con terze parti. Dettagli completi nella pagina sulla sicurezza.

Questo vale per ogni tipo di documento che passa attraverso questa API, dagli estratti conto più sensibili alle note spese più semplici — lo stesso livello di protezione, senza eccezioni per tipo di documento o per volume elaborato.

Se hai domande specifiche di sicurezza non coperte qui, la pagina dedicata è il punto di riferimento più aggiornato — vale la pena consultarla direttamente prima di qualsiasi valutazione formale.

Domande frequenti

Continua a leggere