> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Validazione IBAN

> L'endpoint `iban` valida gli International Bank Account Numbers con validazione completa specifica per paese, controllo del formato e informazioni strutturali dettagliate per applicazioni finanziarie.

## 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:

<ResponseExample>
  ```json theme={"system"}
  {
    "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"
    }
  }
  ```
</ResponseExample>

### Parametri della richiesta

<ParamField query="api_key" type="String" required>
  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.
</ParamField>

<ParamField query="iban" type="String" required>
  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.
</ParamField>

### Parametri della risposta

La risposta API viene restituita in un [formato JSON](https://www.json.org/json-en.html) universale e leggero.

<ResponseField name="iban" type="String">
  L'IBAN normalizzato senza spazi, restituito in formato maiuscolo.
</ResponseField>

<ResponseField name="is_valid" type="Boolean">
  Risultato complessivo della validazione che indica se l'IBAN è valido secondo tutte le regole di validazione.
</ResponseField>

<ResponseField name="country_code" type="String">
  Il codice paese ISO a due lettere (es. DE per Germania, FR per Francia).
</ResponseField>

<ResponseField name="country_name" type="String">
  Il nome completo del paese associato all'IBAN.
</ResponseField>

<ResponseField name="bank_code" type="String">
  Il codice identificativo della banca estratto dall'IBAN secondo il formato specifico del paese.
</ResponseField>

<ResponseField name="account_number" type="String">
  La porzione del numero di conto dell'IBAN, esclusi codice paese, checksum e codice bancario.
</ResponseField>

<ResponseField name="length" type="Integer">
  La lunghezza effettiva dell'IBAN fornito.
</ResponseField>

<ResponseField name="expected_length" type="Integer">
  La lunghezza prevista per gli IBAN del paese specifico secondo lo standard ISO 13616.
</ResponseField>

<ResponseField name="checksum_valid" type="Boolean">
  Se la validazione del checksum IBAN è passata usando l'algoritmo MOD-97.
</ResponseField>

<ResponseField name="format_valid" type="Boolean">
  Se il formato IBAN corrisponde alla struttura prevista per il paese.
</ResponseField>

<ResponseField name="details" type="Object">
  Informazioni dettagliate aggiuntive sulla struttura e formattazione dell'IBAN.
</ResponseField>

<ResponseField name="details.structure" type="String">
  Una rappresentazione visiva della struttura IBAN usando i segnaposto B (Bank), S (Sort), C (Customer) e K (Key).
</ResponseField>

<ResponseField name="details.example" type="String">
  Un esempio correttamente formattato dell'IBAN con spazi per la leggibilità.
</ResponseField>

<ResponseField name="details.bank_name" type="String">
  Il nome della banca (attualmente mostra "Bank information not available").
</ResponseField>

<ResponseField name="details.bank_bic" type="String">
  Il codice BIC della banca (attualmente mostra "BIC not available").
</ResponseField>

<ResponseField name="details.account_type" type="String">
  Il tipo di conto (tipicamente "Bank Account").
</ResponseField>

<ResponseField name="details.currency" type="String">
  Il codice valuta per il paese (es. EUR per i paesi dell'Eurozona, GBP per il Regno Unito).
</ResponseField>

## Esempi

### IBAN tedesco valido

**Richiesta:**

```
GET https://bankvalidation.cleariflow.com/v1/iban/?api_key=YOUR_API_KEY&iban=DE89370400440532013000
```

**Risposta:**

```json theme={"system"}
{
  "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:**

```json theme={"system"}
{
  "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:**

```json theme={"system"}
{
  "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:**

```json theme={"system"}
{
  "error": {
    "message": "Missing iban",
    "code": "missing_iban"
  }
}
```

### Chiave API mancante

**Richiesta:**

```
GET https://bankvalidation.cleariflow.com/v1/iban/?iban=DE89370400440532013000
```

**Risposta:**

```json theme={"system"}
{
  "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](/bank-validation/countries).