Vai al contenuto principale
GET
/
v1
/
iban
Validazione IBAN
curl --request GET \
  --url https://bankvalidation.cleariflow.com/v1/iban/
{
  "iban": "DE89370400440532013000",
  "is_valid": true,
  "country_code": "DE",
  "country_name": "Germany",
  "bank_code": "37040044",
  "account_number": "0532013000",
  "length": 22,
  "expected_length": 22,
  "checksum_valid": true,
  "format_valid": true,
  "details": {
    "structure": "BBBB BBBB BBBB BBBB BB",
    "example": "DE89 3704 0044 0532 0130 00",
    "bank_name": "Bank information not available",
    "bank_bic": "BIC not available",
    "account_type": "Bank Account",
    "currency": "EUR"
  }
}

​
Per iniziare

​
URL di base

https://bankvalidation.cleariflow.com/v1/iban/

​
Endpoint di validazione

L’endpoint iban richiede la tua chiave API e un parametro IBAN per eseguire una validazione completa degli International Bank Account Numbers. 
https://bankvalidation.cleariflow.com/v1/iban/
? api_key = YOUR_UNIQUE_API_KEY
& iban = DE89370400440532013000
Questa richiesta riuscita valida un IBAN tedesco e restituisce informazioni dettagliate: 
{
  "iban": "DE89370400440532013000",
  "is_valid": true,
  "country_code": "DE",
  "country_name": "Germany",
  "bank_code": "37040044",
  "account_number": "0532013000",
  "length": 22,
  "expected_length": 22,
  "checksum_valid": true,
  "format_valid": true,
  "details": {
    "structure": "BBBB BBBB BBBB BBBB BB",
    "example": "DE89 3704 0044 0532 0130 00",
    "bank_name": "Bank information not available",
    "bank_bic": "BIC not available",
    "account_type": "Bank Account",
    "currency": "EUR"
  }
}

​
Parametri della richiesta

​
api_key
String
obbligatorio
La tua chiave API univoca. Nota che ogni utente ha chiavi API univoche per ciascuna delle API Cleariflow, quindi la chiave dell’API di validazione bancaria non funzionerà per l’API tassi di cambio, ad esempio.
​
iban
String
obbligatorio
L’International Bank Account Number da validare. Gli spazi sono consentiti e verranno rimossi automaticamente durante l’elaborazione. L’IBAN deve seguire il formato standard ISO 13616.

​
Parametri della risposta

La risposta API viene restituita in un formato JSON universale e leggero.
​
iban
String
L’IBAN normalizzato senza spazi, restituito in formato maiuscolo.
​
is_valid
Boolean
Risultato complessivo della validazione che indica se l’IBAN è valido secondo tutte le regole di validazione.
​
country_code
String
Il codice paese ISO a due lettere (es. DE per Germania, FR per Francia).
​
country_name
String
Il nome completo del paese associato all’IBAN.
​
bank_code
String
Il codice identificativo della banca estratto dall’IBAN secondo il formato specifico del paese.
​
account_number
String
La porzione del numero di conto dell’IBAN, esclusi codice paese, checksum e codice bancario.
​
length
Integer
La lunghezza effettiva dell’IBAN fornito.
​
expected_length
Integer
La lunghezza prevista per gli IBAN del paese specifico secondo lo standard ISO 13616.
​
checksum_valid
Boolean
Se la validazione del checksum IBAN è passata usando l’algoritmo MOD-97.
​
format_valid
Boolean
Se il formato IBAN corrisponde alla struttura prevista per il paese.
​
details
Object
Informazioni dettagliate aggiuntive sulla struttura e formattazione dell’IBAN.
​
details.structure
String
Una rappresentazione visiva della struttura IBAN usando i segnaposto B (Bank), S (Sort), C (Customer) e K (Key).
​
details.example
String
Un esempio correttamente formattato dell’IBAN con spazi per la leggibilità.
​
details.bank_name
String
Il nome della banca (attualmente mostra “Bank information not available”).
​
details.bank_bic
String
Il codice BIC della banca (attualmente mostra “BIC not available”).
​
details.account_type
String
Il tipo di conto (tipicamente “Bank Account”).
​
details.currency
String
Il codice valuta per il paese (es. EUR per i paesi dell’Eurozona, GBP per il Regno Unito).

​
Esempi

​
IBAN tedesco valido

Richiesta: 
GET https://bankvalidation.cleariflow.com/v1/iban/?api_key=YOUR_API_KEY&iban=DE89370400440532013000
Risposta: 
{
  "iban": "DE89370400440532013000",
  "is_valid": true,
  "country_code": "DE",
  "country_name": "Germany",
  "bank_code": "37040044",
  "account_number": "0532013000",
  "length": 22,
  "expected_length": 22,
  "checksum_valid": true,
  "format_valid": true,
  "details": {
    "structure": "BBBB BBBB BBBB BBBB BB",
    "example": "DE89 3704 0044 0532 0130 00",
    "bank_name": "Bank information not available",
    "bank_bic": "BIC not available",
    "account_type": "Bank Account",
    "currency": "EUR"
  }
}

​
IBAN francese valido

Richiesta: 
GET https://bankvalidation.cleariflow.com/v1/iban/?api_key=YOUR_API_KEY&iban=FR1420041010050500013M02606
Risposta: 
{
  "iban": "FR1420041010050500013M02606",
  "is_valid": true,
  "country_code": "FR",
  "country_name": "France",
  "bank_code": "2004101005",
  "account_number": "0500013M02606",
  "length": 27,
  "expected_length": 27,
  "checksum_valid": true,
  "format_valid": true,
  "details": {
    "structure": "BBBB BSSS SSCC CCCC CCCC CCC KK",
    "example": "FR14 2004 1010 0505 0001 3M02 606",
    "bank_name": "Bank information not available",
    "bank_bic": "BIC not available",
    "account_type": "Bank Account",
    "currency": "EUR"
  }
}

​
IBAN non valido

Richiesta: 
GET https://bankvalidation.cleariflow.com/v1/iban/?api_key=YOUR_API_KEY&iban=INVALID
Risposta: 
{
  "iban": "",
  "is_valid": false,
  "country_code": "",
  "country_name": "",
  "bank_code": "",
  "account_number": "",
  "length": 7,
  "expected_length": 0,
  "checksum_valid": false,
  "format_valid": false,
  "details": {
    "structure": "",
    "example": ""
  }
}

​
Gestione degli errori

​
Parametro IBAN mancante

Richiesta: 
GET https://bankvalidation.cleariflow.com/v1/iban/?api_key=YOUR_API_KEY
Risposta: 
{
  "error": {
    "message": "Missing iban",
    "code": "missing_iban"
  }
}

​
Chiave API mancante

Richiesta: 
GET https://bankvalidation.cleariflow.com/v1/iban/?iban=DE89370400440532013000
Risposta: 
{
  "error": {
    "message": "API key is required",
    "code": "missing_api_key"
  }
}

​
Struttura IBAN

L’IBAN è composto da diversi elementi:
  1. Codice paese (2 caratteri): codice paese ISO 3166-1 alpha-2
  2. Cifre di controllo (2 caratteri): validazione con algoritmo MOD-97
  3. Identificativo bancario: codice bancario specifico per paese
  4. Numero di conto: identificativo del conto cliente

​
Formati specifici per paese

Paesi diversi hanno strutture IBAN differenti:
  • Germania (DE): 22 caratteri - BBBB BBBB BBBB BBBB BB
  • Francia (FR): 27 caratteri - BBBB BSSS SSCC CCCC CCCC CCC KK
  • Italia (IT): 27 caratteri - CAAA AABB BBSS CCCC CCCC CCX
  • Regno Unito (GB): 22 caratteri - BBBB SSSS SSCC CCCC CC
  • Spagna (ES): 24 caratteri - BBBB SSSS DDCC CCCC CCCC CC
Dove:
  • B = Codice bancario
  • S = Codice di smistamento
  • C = Numero di conto cliente
  • K = Chiave/cifra di controllo
  • A = Tipo di conto
  • D = Cifra di controllo

​
Regole di validazione

L’API esegue una validazione completa che include:
  1. Validazione del formato: verifica se l’IBAN segue la struttura prevista per il paese
  2. Validazione della lunghezza: verifica che la lunghezza dell’IBAN corrisponda allo standard del paese
  3. Validazione del checksum: esegue la validazione con algoritmo MOD-97
  4. Validazione del codice paese: assicura che il codice paese sia supportato
  5. Validazione dei caratteri: verifica caratteri alfanumerici validi

​
Paesi supportati

L’API supporta la validazione IBAN per oltre 50 paesi tra cui:
  • Europa: Germania, Francia, Italia, Spagna, Paesi Bassi, Belgio, Austria, Svizzera, Regno Unito, Polonia
  • Asia: Emirati Arabi Uniti, Bahrain, Israele, Giordania, Kazakistan, Kuwait
  • Americhe: Brasile, Costa Rica, Repubblica Dominicana, Guatemala
  • Africa: Mauritania, Mauritius, Tunisia
Per un elenco completo dei paesi supportati, consulta la pagina Paesi supportati.