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

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.

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

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.

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.