Documentazione dell’API di validazione IBAN

L’API REST di IBAN-Test verifica struttura e cifre di controllo degli IBAN, restituisce i dati bancari e BIC disponibili, controlla BIC e conti bancari tedeschi e genera IBAN dalle coordinate bancarie. Autenticati con il token API della dashboard e integra le risposte JSON nei moduli, nei processi di pagamento e nei sistemi interni.

Prova la verifica IBAN online · Usa il generatore IBAN · Collega il server MCP

Documentazione interattiva per sviluppatori

Il riferimento tecnico completo, con parametri, schemi di risposta e funzioni di prova, è disponibile nella documentazione OpenAPI.

Apri la documentazione OpenAPI

Autenticazione

Usa il token della sezione API overview come token Bearer nell’header HTTP:

Authorization: Bearer YOUR_API_TOKEN

Dopo l’accesso trovi il token in API overview. Non hai ancora un account? Crea la tua chiave API.

URL di base

https://www.iban-test.eu/api

Endpoint

GET /v2/iban/validate?iban=... – verificare un IBAN
GET /v2/iban/validate/{iban} – verificare un IBAN passato nel percorso dell’URL
POST /v2/iban/validate – verificare un IBAN passato nel corpo della richiesta
GET /v2/bic/validate/{bic} – verificare un BIC
GET /v2/bank-account/validate?bankcode=...&accountnumber=... – verificare un conto bancario tedesco
GET /v2/iban/generate?countrycode=...&bankcode=...&accountnumber=... – generare un IBAN

I controlli eseguiti su un IBAN

Codice paese, sequenza di caratteri e lunghezza del formato IBAN nazionale
Cifre di controllo IBAN verificate con il calcolo internazionale MOD-97
Dati disponibili negli archivi: nome della banca, città e BIC

Un risultato valido conferma la coerenza formale dell’IBAN. Non dimostra che il conto esista, appartenga a una determinata persona, sia attivo o possa ricevere pagamenti.

Esempi di richieste

Verifica un IBAN

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://www.iban-test.eu/api/v2/iban/validate?iban=DE89%203704%200044%200532%200130%2000"

Gli spazi negli IBAN sono ammessi e vengono rimossi automaticamente prima della verifica.

Verifica un BIC

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://www.iban-test.eu/api/v2/bic/validate/COBADEFFXXX"

Verifica un conto bancario

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://www.iban-test.eu/api/v2/bank-account/validate?bankcode=37040044&accountnumber=532013000"

Genera un IBAN

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://www.iban-test.eu/api/v2/iban/generate?countrycode=DE&bankcode=37040044&accountnumber=532013000"

Formato delle risposte e gestione degli errori

Tutti gli endpoint restituiscono JSON. Prima di accettare o salvare le coordinate bancarie, valuta la risposta HTTP e i campi error, code, message e il campo facoltativo details .

{
  "error": false,
  "code": 2100,
  "message": "IBAN is valid",
  "details": {}
}

Consulta OpenAPI per gli schemi aggiornati di parametri e risposte. Cifre di controllo corrette non confermano l’identità dell’intestatario del conto.

Codici di risultato e gestione degli errori

Controlla sia lo stato HTTP sia la risposta JSON. Una risposta HTTP 200 può contenere errori o risultati di verifica negativi. error: false da solo non conferma dati bancari validi. Valuta code; il testo traducibile di message serve solo per la visualizzazione.

Per una verifica individuale, 2100 indica un IBAN valido; 2200, una generazione riuscita, e 2500, un formato BIC valido. Per i conti tedeschi, 2300 indica solo che la verifica è stata eseguita: valuta anche bank.valid e konto.valid.

Codice JSON	Significato e azione
`3100`	IBAN non valido. Richiedi dati corretti; non riprovare automaticamente con gli stessi dati.
`3101`	Codice bancario non valido. Controlla e correggi i dati bancari.
`3102`	Numero di conto non valido. Controlla e correggi i dati del conto.
`3500`	Formato BIC non valido. Richiedi un BIC corretto.
`4002`	Autenticazione assente o non valida. Controlla il token Bearer e l’header Authorization.
`4003`	Quota API raggiunta. Sospendi le verifiche finché non torna disponibile; evita cicli di tentativi.
`4004`	Utente o accesso API disattivato. Verifica lo stato dell’account o contatta l’assistenza.
`4100`	IBAN mancante. Fornisci il parametro iban.
`4110`	BIC mancante. Fornisci un BIC.
`4201` / `4210`	Codice bancario mancante. Fornisci bankcode; la generazione usa 4201, la verifica del conto usa 4210.
`4212` / `4213`	Codice bancario troppo lungo (4212) o corto (4213). Verifica la lunghezza prevista per il paese.
`4220` / `4222` / `4223`	Numero di conto mancante (4220), troppo lungo (4222) o corto (4223). Correggi accountnumber.
`4230` / `4231`	Codice paese mancante (4230) o non valido (4231). Controlla countrycode.
`4233`	Impossibile generare l’IBAN. Verifica la combinazione di paese, codice bancario e numero di conto.
`5001`	Errore interno di elaborazione. Riprova più tardi con attese crescenti e un numero limitato di tentativi; contatta l’assistenza se persiste.

Con HTTP 401, correggi l’autenticazione. Con HTTP 429, rispetta Retry-After se presente. Con HTTP 5xx o errori di rete, limita i tentativi e aumenta progressivamente le attese. Una pagina di errore HTML o una risposta JSON assente non è un risultato di verifica.

SEPA: addebiti diretti, bonifici e bonifici istantanei

La verifica IBAN restituisce anche la partecipazione della banca a quattro schemi SEPA, controllata nei registri dei partecipanti dell’EPC.

details.sepa.sddCore – Addebito diretto SEPA Core
details.sepa.sddB2b – Addebito diretto SEPA B2B
details.sepa.sct – Bonifico SEPA (SCT)
details.sepa.sctInst – Bonifico istantaneo SEPA (SCT Inst)

I quattro schemi vengono verificati indipendentemente. confirmed indica una corrispondenza univoca e attuale nel registro. unknown indica che non è stato possibile confermare la partecipazione, non che la banca non supporti lo schema.

Ogni schema restituisce soltanto status e reason. Lo stato SEPA non modifica il risultato della verifica dell’IBAN.

Esempio: estratto di una risposta di verifica IBAN

{
  "details": {
    "sepa": {
      "sddCore": {
        "status": "confirmed",
        "reason": "matched"
      },
      "sddB2b": {
        "status": "confirmed",
        "reason": "matched"
      },
      "sct": {
        "status": "confirmed",
        "reason": "matched"
      },
      "sctInst": {
        "status": "confirmed",
        "reason": "matched"
      }
    }
  }
}

Significato di reason

matched – Partecipazione confermata
no_data – Dati del registro non disponibili
missing_bic – BIC non disponibile
ambiguous_bank – Associazione bancaria ambigua
no_match – Nessuna voce corrispondente
ambiguous_participant – Più voci corrispondenti
not_current – Partecipazione attualmente non effettiva
stale_data – Dati del registro obsoleti
lookup_error – Consultazione del registro non riuscita

Disponibile per la verifica IBAN tramite REST e con gli strumenti MCP validate_iban e validate_iban_batch. La generazione dell’IBAN include questi campi quando restituisce dati bancari. Le verifiche separate di BIC e di codice bancario/numero di conto tedesco non li restituiscono.

La verifica riguarda la partecipazione della banca. Non conferma l’esistenza o l’idoneità del conto, un mandato o il successo di un pagamento. SCT Inst conferma la partecipazione allo schema, non la raggiungibilità in tempo reale tramite RT1/TIPS né l’esecuzione istantanea garantita per un conto specifico.

Fonte dei dati: European Payments Council (EPC).

MCP per client IA

Oltre all’API REST, IBAN-Test mette a disposizione un server Model Context Protocol per la verifica IBAN. MCP espone le stesse funzioni bancarie come strumenti strutturati per client e agenti IA compatibili.

Endpoint MCP

Collega il tuo client compatibile con MCP a questo indirizzo e autenticati con il token API.

https://www.iban-test.eu/mcp

Authorization: Bearer YOUR_API_TOKEN

Strumenti MCP disponibili

validate_iban – verifica un singolo IBAN
validate_iban_batch – verifica più IBAN; ogni IBAN conta come una richiesta API
generate_test_iban – genera un IBAN da codice paese, codice bancario e numero di conto
ibantest_bank_account_validate – verifica un codice bancario e un numero di conto tedeschi
ibantest_bic_validate – verifica un BIC e restituisce i dati bancari disponibili
get_usage_info – Mostra l’utilizzo dell’API senza consumare una richiesta di verifica.

Le chiamate funzionali agli strumenti MCP vengono conteggiate nella quota API di IBAN-Test, come le richieste REST.

Note

L’API REST e MCP utilizzano token Bearer.
La precedente API basata su un codice di autenticazione non è descritta in questa documentazione.
Le richieste funzionali vengono conteggiate nella quota API corrente.

Domande frequenti sull’API IBAN-Test

Le risposte su token Bearer, richieste, risposte JSON, quote e integrazioni sono nelle FAQ di IBAN-Test.

Come si usa l’API IBAN-Test?

Come si costruisce una richiesta API?

Come si costruisce una richiesta API?

Trasmetti il token API come token Bearer nell’header HTTP.

Authorization: Bearer YOUR_API_TOKEN

URL di base:

https://www.iban-test.eu/api

Verifica di un IBAN:

GET /v2/iban/validate/{iban}

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://www.iban-test.eu/api/v2/iban/validate/DE89%203704%200044%200532%200130%2000"

Verifica di un BIC:

GET /v2/bic/validate/{bic}

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://www.iban-test.eu/api/v2/bic/validate/COBADEFFXXX"

Verifica di un conto bancario:

GET /v2/bank-account/validate?bankcode=37040044&accountnumber=532013000

Generazione di un IBAN:

GET /v2/iban/generate?countrycode=DE&bankcode=37040044&accountnumber=532013000

Trovi parametri, campi delle risposte e funzioni di prova nella Documentazione API.

Quale formato di risposta usa l’API?

Che cosa restituisce l’API?

Che cosa restituisce l’API?

Tutti gli endpoint restituiscono JSON. Il risultato contiene error, code, message e i dettagli specifici dell’endpoint.

{
  "error": false,
  "code": 2100,
  "message": "IBAN is valid",
  "details": {}
}

A seconda dell’endpoint e del paese, i dettagli possono includere informazioni bancarie, BIC, risultati della verifica del conto o l’IBAN generato.

Per codici di stato, parametri e schemi di risposta aggiornati, consulta la Documentazione API.

Addebiti diretti SEPA: Core e B2B

La verifica dell’IBAN restituisce anche la partecipazione della banca agli schemi di addebito diretto SEPA, verificata nei registri dei partecipanti dell’EPC.

details.sepa.sddCore – Addebito diretto SEPA Core
details.sepa.sddB2b – Addebito diretto SEPA B2B

I due schemi vengono verificati separatamente. confirmed indica una corrispondenza univoca e attuale nel registro. unknown indica che non è stato possibile confermare la partecipazione; non significa che la banca non supporti lo schema.

La verifica riguarda la partecipazione della banca. Non conferma l’esistenza del conto, la sua idoneità all’addebito, un mandato o il buon esito di un incasso.

Campi SEPA ed esempi di risposta

Perché il mio accesso API è bloccato?

Perché il mio accesso API è bloccato o disattivato?

Perché il mio accesso API è bloccato o disattivato?

Può accadere se hai esaurito la quota, se il token API non è valido o se viene rilevato un utilizzo sospetto o abusivo.

Se hai semplicemente esaurito la quota, attendi il prossimo rinnovo oppure scegli un piano con un volume di richieste maggiore.

Se l’accesso sembra bloccato per un altro motivo, contatta l’assistenza tramite il modulo di contatto.

Posso integrare IBAN-Test nei moduli o nell’e-commerce?

Sì.

Sì. L’API IBAN-Test è progettata per le verifiche automatiche in moduli, e-commerce, prodotti SaaS, mandati SEPA e strumenti gestionali.

Puoi controllare le coordinate al checkout, durante la registrazione, prima di un addebito diretto o prima di importare grandi quantità di dati di pagamento.

In questo modo individui errori di battitura e coordinate non valide prima che causino pagamenti non riusciti o addebiti respinti.

Verifica dei dati bancari

Verifiche negli archivi bancari di 40 Paesi

IBAN-Test va oltre le cifre di controllo. Per i paesi elencati confrontiamo il codice della banca con gli archivi disponibili e restituiamo le informazioni presenti, come istituto, città e BIC. Scopri come funziona la verifica IBAN.

ALAlbania ADAndorra ATAustria BEBelgio BGBulgaria HRCroazia CYCipro CZCechia DKDanimarca EEEstonia FIFinlandia FRFrancia DEGermania GIGibilterra GRGrecia HUUngheria ISIslanda IEIrlanda ITItalia LVLettonia LILiechtenstein LTLituania LULussemburgo MTMalta MDMoldavia MEMontenegro NLPaesi Bassi MKMacedonia del Nord NONorvegia PLPolonia PTPortogallo RORomania SMSan Marino RSSerbia SKSlovacchia SISlovenia ESSpagna SESvezia CHSvizzera VACittà del Vaticano

Controllo del formato IBAN

Controllo di 115 formati IBAN

Controlla struttura, lunghezza e cifre di controllo per individuare errori di battitura e cifre invertite prima di un pagamento. Per i paesi indicati sopra è disponibile anche la verifica negli archivi bancari.

API e automazione

Automatizza la verifica degli IBAN e dei dati bancari

Verifica struttura e cifre di controllo e usa i dati degli archivi bancari nei tuoi moduli, prodotti SaaS, processi SEPA e agenti IA. Automatizza tutto tramite REST o MCP.

Ottieni una chiave API Consulta la documentazione API

API di validazione IBANVerifiche IBAN automatiche per applicazioni, moduli e pagamenti. Come funziona la verifica IBANScopri i controlli su formato, cifre di controllo e dati bancari alla base di ogni risultato. API di validazione IBAN per SEPAIndividua gli errori evitabili prima di inviare i pagamenti SEPA. Server MCP per agenti IACollega i tuoi strumenti IA alla verifica IBAN, al controllo BIC e ai dati di utilizzo.

Server MCP per agenti IA – Collega i tuoi client IA agli strumenti di verifica IBAN – https://www.iban-test.eu/mcp – Documentazione API