Le API bancarie permettono a due sistemi di scambiarsi richieste e risposte secondo regole documentate: per esempio, un gestionale può ricevere informazioni sui conti oppure avviare un pagamento attraverso il servizio abilitato. Il collegamento tecnico, però, non dimostra da solo che il denaro sia arrivato. Prima di affidargli incassi e riconciliazione bisogna capire quali funzioni espone, quali stati restituisce e che cosa viene fatturato.
Per un’impresa, la domanda utile non è soltanto “si collega alla mia banca?”. È anche: quali conti supporta, come riconosce la stessa operazione, che cosa accade durante un’interruzione e chi spiega un risultato ambiguo? Questa guida offre un percorso per valutare l’integrazione senza dover scrivere codice o confondere una dimostrazione con un servizio già operativo.
Che cosa fa un’API bancaria
API significa Application Programming Interface, cioè interfaccia di programmazione. Descrive come un’applicazione può chiedere una funzione o un’informazione a un altro sistema. La documentazione specifica gli indirizzi delle funzioni, i dati richiesti, le risposte possibili e le condizioni di accesso.
Per esempio, la pagina ufficiale di Banca Mediolanum presenta funzioni di gestione dei conti e di pagamento e rimanda alle specifiche del portale API. È una descrizione del proprio servizio, non la prova che tutte le banche offrano identiche funzioni, rapporti o condizioni.
Un’interfaccia non è una banca aggiuntiva e non coincide con un’app per consumatori. La stessa funzione può essere integrata in un gestionale o distribuita tramite un fornitore. Per il funzionamento quotidiano dei collegamenti personali, la guida all’open banking approfondisce conti, permessi e riconciliazione dei saldi.
Una specifica pubblica non apre qualsiasi conto
La possibilità di leggere la documentazione tecnica va distinta dall’accesso al servizio reale. Servono il ruolo pertinente, le condizioni previste dal fornitore e le autorizzazioni richieste per la funzione. Un esempio riuscito nell’ambiente di prova non attribuisce automaticamente il diritto di utilizzare dati o disporre operazioni in produzione.
Ricostruisci chi sviluppa il collegamento, chi fornisce la funzione finanziaria e con chi sottoscrivi il contratto. La consultazione degli albi Banca d’Italia permette di verificare soggetti e attività autorizzate: l’iscrizione del partner non è una certificazione della qualità di ogni software distribuito attraverso di lui.
Per la distinzione normativa fra accesso informativo, disposizione di ordini e autenticazione forte rimandiamo alla guida alla PSD2. Qui il controllo riguarda l’integrazione concreta, senza presumere che qualsiasi API finanziaria abbia lo stesso perimetro regolamentare.
Tre funzioni da separare nel progetto
Chiedi al fornitore quali funzioni siano effettivamente incluse per la banca, il rapporto e il paese che utilizzi. La tabella è uno schema di valutazione originale: non certifica un catalogo universale.
| Funzione | Che cosa verificare nella documentazione | Che cosa non dedurre |
|---|---|---|
| Informazioni sui conti | Conti coperti, campi, periodo e orario dell’ultimo aggiornamento | Che ogni informazione sia in tempo reale o ogni rapporto sia incluso |
| Avvio del pagamento | Dati necessari, autorizzazione, identificativo e risposte iniziali | Che la richiesta accettata equivalga già all’incasso |
| Verifica dello stato | Significato degli stati, loro evoluzione e durata della consultabilità | Che una parola come “completato” abbia ovunque lo stesso significato |
Verifica anche quali dati il gestionale conserva e quali mostra all’operatore. Un risultato privo di data, identificativo o spiegazione può rendere difficile capire se si stia osservando l’ultima risposta o una copia precedente. Il controllo deve arrivare fino alla schermata usata dalla persona che decide di spedire un ordine o registrare un incasso.
Sandbox e produzione: il test non muove denaro reale
La sandbox è un ambiente di prova. Nelle FAQ pubbliche di Mediobanca Premier è distinta dalla produzione: nel primo caso si ricevono dati di test, nel secondo si utilizzano dati reali e si eseguono realmente le operazioni. È un esempio concreto delle due funzioni, non una descrizione identica di ogni ambiente bancario.
Prima del passaggio operativo chiedi che cosa sia stato provato: una risposta favorevole, una richiesta incompleta, un’autorizzazione non terminata, una scadenza del collegamento o un risultato non definitivo. Un test con dati sintetici non dimostra da solo la compatibilità con tutti i conti che l’impresa utilizzerà.
Concorda chi approva l’avvio, come si distingue l’ambiente reale e come si arresta un flusso in caso di errore. Le credenziali di test non devono essere scambiate per quelle di produzione. Non occorre inserirle in un foglio di valutazione condiviso: è sufficiente documentare chi le gestisce e con quale procedura.
Risposta ricevuta, pagamento eseguito e incasso
Il documento del Comitato Pagamenti Italia sugli stati del pagamento, pubblicato nel maggio 2024, descrive come documentare l’evoluzione delle operazioni attraverso le interfacce API-PSD2. Sono buone pratiche adottabili su base volontaria, con un perimetro dichiarato: non nuove regole obbligatorie del 2026 applicabili a qualunque servizio.
Il punto pratico è distinguere la risposta alla richiesta dallo stato finanziario dell’operazione. Un messaggio può indicare che una fase è stata acquisita, mentre restano da completare autorizzazione, controlli o passaggi successivi. Nel documento CPI, gli stati vanno letti insieme al processo e alle informazioni fornite dal prestatore del conto.
Chiedi quindi che cosa dimostri la conferma usata dal tuo gestionale. Documenta separatamente l’ordine commerciale, il riferimento del pagamento e lo stato restituito. Due interrogazioni dello stesso pagamento non sono due incassi; una nuova lettura di un identificativo non crea una nuova disponibilità finanziaria.
Per tempi e caratteristiche dello strumento, consulta anche la guida al bonifico istantaneo. La presenza di un’API non rende istantaneo qualsiasi trasferimento né sostituisce la verifica di ciò che è stato effettivamente disposto.
Il costo può dipendere dalle chiamate, non dai pagamenti
Una chiamata è una richiesta al servizio. Chiedere un saldo, recuperare una pagina di movimenti e interrogare uno stato possono essere richieste distinte. Il contratto deve chiarire l’unità fatturata, gli utilizzi inclusi, i limiti e il trattamento di errori o tentativi ripetuti. Non presumiamo che tutte le API siano a pagamento o adottino la stessa tariffa.
Primo esempio interamente inventato: sei conti, quattro aggiornamenti al giorno e trenta giorni. Ogni aggiornamento di ciascun conto richiede tre chiamate; il modello ipotizza un canone di 39 euro e 0,02 euro per ogni chiamata, senza soglie incluse. Imposte, sviluppo, assistenza e altre spese sono esclusi.
| Voce del modello | Calcolo | Risultato |
|---|---|---|
| Aggiornamenti dei conti | 6 × 4 × 30 | 720 |
| Chiamate ordinarie | 720 × 3 | 2.160 |
| Costo senza tentativi aggiuntivi | 39 + 2.160 × 0,02 euro | 82,20 euro |
| Chiamate aggiuntive ipotizzate | 10% di 2.160 | 216 |
| Costo se anche queste sono fatturate | 39 + 2.376 × 0,02 euro | 86,52 euro |
La differenza è 4,32 euro. Non sono prezzi o tassi di errore osservati: l’ipotesi del 10% serve solo a mostrare perché conta la regola di conteggio. Prima di confrontare preventivi, ricostruisci il volume tecnico e verifica come viene misurato. “Numero di clienti”, “numero di pagamenti” e “numero di richieste” non sono unità intercambiabili.
Disponibilità del collegamento: percentuale e impatto sono diversi
Secondo esempio, anch’esso ipotetico: un periodo di trenta giorni consecutivi comprende 43.200 minuti. Se misurassimo soltanto la quota di tempo disponibile, senza alcuna esclusione, le percentuali seguenti corrisponderebbero ai minuti indicati. Non sono dati di una banca o livelli di servizio promessi.
| Disponibilità ipotetica | Quota non disponibile | Minuti nel periodo di 30 giorni |
|---|---|---|
| 99,9% | 0,1% | 43,2 |
| 99,5% | 0,5% | 216 |
Una percentuale non descrive quando si verifichi l’interruzione, se sia continua o distribuita, né quali funzioni colpisca. Chiedi come il fornitore misuri disponibilità e prestazioni, quali esclusioni applichi e come gestisca assistenza e incidenti. Un risultato storico non garantisce quello futuro e non quantifica da solo il danno economico dell’impresa.
Che cosa fare quando la risposta è incerta
Un errore visualizzato non basta a provare che l’operazione non sia stata ricevuta. Prima di ripeterla occorre ricostruire il riferimento già creato e la procedura prevista per quello stato. Chiedi al fornitore come gestisca i tentativi ripetuti senza confondere una nuova interrogazione con un nuovo ordine.
Prepara contatti e informazioni utili all’assistenza: orario, ambiente, funzione, identificativo e messaggio ricevuto, evitando password e codici attivi. Conserva la risposta originale e le correzioni del gestionale. La procedura va concordata prima che un risultato ambiguo blocchi una spedizione o produca una registrazione contabile errata.
Infine, verifica manutenzione e uscita: versione delle specifiche utilizzata, comunicazione delle modifiche, test prima degli aggiornamenti ed esportazione dei riferimenti necessari. Berlin Group pubblica documenti con modelli, regole operative e specifiche tecniche: l’esistenza di uno standard aiuta il confronto, ma non dimostra che ogni implementazione e configurazione siano identiche.
Domande frequenti sulle API bancarie
Un’API bancaria è un’app?
No. È un’interfaccia usata dai sistemi; un’app o un gestionale possono utilizzarla per offrire una funzione.
Documentazione pubblica significa accesso gratuito a ogni conto?
No. Documentazione, condizioni economiche, requisiti di accesso e autorizzazioni alla funzione sono aspetti differenti.
Un test in sandbox prova che il servizio è già operativo?
No. Occorre verificare il passaggio alla produzione e le funzioni concretamente disponibili per i rapporti interessati.
La conferma tecnica dimostra che ho incassato?
Non da sola. Devi conoscere il significato della risposta e lo stato del pagamento cui si riferisce.
Due interrogazioni dello stesso pagamento creano due incassi?
No. Sono letture da ricondurre all’operazione pertinente, non nuove entrate da sommare.
Il costo si calcola sul numero dei bonifici?
Dipende dal contratto. Possono contare richieste, funzioni, volumi inclusi e servizi aggiuntivi: chiedi come venga misurata ogni voce.
Un’indisponibilità significa che i soldi sono persi?
Non si può dedurlo dal solo errore del collegamento. Ricostruisci lo stato usando identificativi, documenti e assistenza competente.
Uno standard comune elimina i test fra fornitori?
No. Funzioni, versioni, configurazioni e procedure effettive devono essere verificate sull’integrazione utilizzata.
Fonti e nota metodologica
- Comitato Pagamenti Italia — Open banking, stati del pagamento, maggio 2024: perimetro e natura volontaria; passaggi pertinenti su documentazione, evoluzione degli stati, tempi e timeout.
- Mediobanca Premier — FAQ del portale sviluppatori: esempio concreto della distinzione fra sandbox e produzione, con dati di prova e operazioni reali.
- Berlin Group — Open Banking / NextGenPSD2: framework, modelli, regole operative e documenti tecnici; non verifica di una singola implementazione.
- Banca Mediolanum — Open Banking API: funzioni dichiarate di gestione dei conti e pagamento, rinvio alle specifiche; nessuna statistica di prestazione utilizzata.
- Banca d’Italia — Consultazione albi ed elenchi: soggetti iscritti, attività autorizzate e informazioni consultabili.
Fonti consultate il 30 ottobre 2026 nei passaggi pertinenti, non in ogni allegato o documento collegato. I due modelli numerici sono originali e ipotetici: il primo assume specifiche regole di fatturazione e tentativi aggiuntivi, il secondo una misura puramente temporale senza esclusioni. Non sono tariffe, frequenze di errore, risultati storici o livelli di servizio di operatori reali. I passaggi di valutazione sono un metodo editoriale, non un capitolato ufficiale o una certificazione. Illustrazione editoriale originale generata con IA per BorsaMagazine, simbolica e senza dati o sistemi bancari reali.