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

# Validation IBAN

> L'endpoint `iban` valide les numéros de compte bancaire international avec une validation complète spécifique à chaque pays, une vérification du format et des informations structurelles détaillées pour les applications financières.

## Premiers pas

### URL de base

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

### Endpoint de validation

L'endpoint `iban` requiert votre clé API et un paramètre IBAN pour effectuer une validation complète des numéros de compte bancaire international.

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

Cette requête réussie valide un IBAN allemand et renvoie des informations détaillées :

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

### Paramètres de requête

<ParamField query="api_key" type="String" required>
  Votre clé API unique. Notez que chaque utilisateur possède des clés API uniques *pour chacune des
  API Cleariflow* ; votre clé de l'API de validation bancaire ne fonctionnera pas pour votre API de
  taux de change, par exemple.
</ParamField>

<ParamField query="iban" type="String" required>
  Le numéro de compte bancaire international à valider. Les espaces sont autorisés et seront automatiquement supprimés lors du traitement. L'IBAN doit suivre le format standard ISO 13616.
</ParamField>

### Paramètres de réponse

La réponse de l'API est renvoyée dans un [format JSON](https://www.json.org/json-en.html) universel et léger.

<ResponseField name="iban" type="String">
  L'IBAN normalisé sans espaces, renvoyé en majuscules.
</ResponseField>

<ResponseField name="is_valid" type="Boolean">
  Résultat global de validation indiquant si l'IBAN est valide selon toutes les règles de validation.
</ResponseField>

<ResponseField name="country_code" type="String">
  Le code pays ISO à deux lettres (par ex., DE pour l'Allemagne, FR pour la France).
</ResponseField>

<ResponseField name="country_name" type="String">
  Le nom complet du pays associé à l'IBAN.
</ResponseField>

<ResponseField name="bank_code" type="String">
  Le code d'identification bancaire extrait de l'IBAN selon le format spécifique au pays.
</ResponseField>

<ResponseField name="account_number" type="String">
  La partie numéro de compte de l'IBAN, hors code pays, somme de contrôle et code bancaire.
</ResponseField>

<ResponseField name="length" type="Integer">
  La longueur réelle de l'IBAN fourni.
</ResponseField>

<ResponseField name="expected_length" type="Integer">
  La longueur attendue pour les IBAN du pays spécifique selon la norme ISO 13616.
</ResponseField>

<ResponseField name="checksum_valid" type="Boolean">
  Indique si la validation de la somme de contrôle IBAN a réussi à l'aide de l'algorithme MOD-97.
</ResponseField>

<ResponseField name="format_valid" type="Boolean">
  Indique si le format de l'IBAN correspond à la structure attendue pour le pays.
</ResponseField>

<ResponseField name="details" type="Object">
  Informations détaillées supplémentaires sur la structure et le formatage de l'IBAN.
</ResponseField>

<ResponseField name="details.structure" type="String">
  Une représentation visuelle de la structure IBAN utilisant les placeholders B (Banque), S (Guichet), C (Client) et K (Clé).
</ResponseField>

<ResponseField name="details.example" type="String">
  Un exemple correctement formaté de l'IBAN avec des espaces pour la lisibilité.
</ResponseField>

<ResponseField name="details.bank_name" type="String">
  Le nom de la banque (affiche actuellement « Bank information not available »).
</ResponseField>

<ResponseField name="details.bank_bic" type="String">
  Le code BIC de la banque (affiche actuellement « BIC not available »).
</ResponseField>

<ResponseField name="details.account_type" type="String">
  Le type de compte (généralement « Bank Account »).
</ResponseField>

<ResponseField name="details.currency" type="String">
  Le code devise du pays (par ex., EUR pour les pays de la zone euro, GBP pour le Royaume-Uni).
</ResponseField>

## Exemples

### IBAN allemand valide

**Requête :**

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

**Réponse :**

```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 français valide

**Requête :**

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

**Réponse :**

```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 invalide

**Requête :**

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

**Réponse :**

```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": ""
  }
}
```

## Gestion des erreurs

### Paramètre IBAN manquant

**Requête :**

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

**Réponse :**

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

### Clé API manquante

**Requête :**

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

**Réponse :**

```json theme={"system"}
{
  "error": {
    "message": "API key is required",
    "code": "missing_api_key"
  }
}
```

## Structure IBAN

L'IBAN se compose de plusieurs éléments :

1. **Code pays (2 caractères)** : code pays ISO 3166-1 alpha-2
2. **Chiffres de contrôle (2 caractères)** : validation par algorithme MOD-97
3. **Identifiant bancaire** : code bancaire spécifique au pays
4. **Numéro de compte** : identifiant du compte client

### Formats spécifiques par pays

Les différents pays ont des structures IBAN variables :

* **Allemagne (DE)** : 22 caractères — `BBBB BBBB BBBB BBBB BB`
* **France (FR)** : 27 caractères — `BBBB BSSS SSCC CCCC CCCC CCC KK`
* **Italie (IT)** : 27 caractères — `CAAA AABB BBSS CCCC CCCC CCX`
* **Royaume-Uni (GB)** : 22 caractères — `BBBB SSSS SSCC CCCC CC`
* **Espagne (ES)** : 24 caractères — `BBBB SSSS DDCC CCCC CCCC CC`

Où :

* **B** = Code banque
* **S** = Code guichet
* **C** = Numéro de compte client
* **K** = Clé/chiffre de contrôle
* **A** = Type de compte
* **D** = Chiffre de contrôle

## Règles de validation

L'API effectue une validation complète incluant :

1. **Validation du format** : vérifie si l'IBAN suit la structure attendue pour le pays
2. **Validation de la longueur** : vérifie que la longueur de l'IBAN correspond à la norme du pays
3. **Validation de la somme de contrôle** : effectue la validation par algorithme MOD-97
4. **Validation du code pays** : s'assure que le code pays est pris en charge
5. **Validation des caractères** : vérifie les caractères alphanumériques valides

## Pays pris en charge

L'API prend en charge la validation IBAN pour plus de 50 pays, notamment :

* **Europe** : Allemagne, France, Italie, Espagne, Pays-Bas, Belgique, Autriche, Suisse, Royaume-Uni, Pologne
* **Asie** : Émirats arabes unis, Bahreïn, Israël, Jordanie, Kazakhstan, Koweït
* **Amériques** : Brésil, Costa Rica, République dominicaine, Guatemala
* **Afrique** : Mauritanie, Maurice, Tunisie

Pour une liste complète des pays pris en charge, consultez la page [Pays pris en charge](/bank-validation/countries).