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

# Validación de IBAN

> El endpoint `iban` valida números de cuenta bancaria internacional con validación exhaustiva específica por país, comprobación de formato e información estructural detallada para aplicaciones financieras.

## Primeros pasos

### URL base

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

### Endpoint de validación

El endpoint `iban` requiere su clave API y un parámetro IBAN para realizar una validación exhaustiva de números de cuenta bancaria internacional.

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

Esta solicitud exitosa valida un IBAN alemán y devuelve información detallada:

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

### Parámetros de solicitud

<ParamField query="api_key" type="String" required>
  Su clave API única. Tenga en cuenta que cada usuario tiene claves API únicas *para cada una de las APIs de Cleariflow*, por lo que su clave de la API de validación bancaria no funcionará para su API de tipos de cambio, por ejemplo.
</ParamField>

<ParamField query="iban" type="String" required>
  El número de cuenta bancaria internacional a validar. Se permiten espacios y se eliminarán automáticamente durante el procesamiento. El IBAN debe seguir el formato estándar ISO 13616.
</ParamField>

### Parámetros de respuesta

La respuesta de la API se devuelve en un [formato JSON](https://www.json.org/json-en.html) universal y ligero.

<ResponseField name="iban" type="String">
  El IBAN normalizado sin espacios, devuelto en formato mayúsculas.
</ResponseField>

<ResponseField name="is_valid" type="Boolean">
  Resultado general de la validación que indica si el IBAN es válido según todas las reglas de validación.
</ResponseField>

<ResponseField name="country_code" type="String">
  El código de país ISO de dos letras (p. ej., DE para Alemania, FR para Francia).
</ResponseField>

<ResponseField name="country_name" type="String">
  El nombre completo del país asociado al IBAN.
</ResponseField>

<ResponseField name="bank_code" type="String">
  El código identificador bancario extraído del IBAN según el formato específico del país.
</ResponseField>

<ResponseField name="account_number" type="String">
  La parte del número de cuenta del IBAN, excluyendo el código de país, el dígito de control y el código bancario.
</ResponseField>

<ResponseField name="length" type="Integer">
  La longitud real del IBAN proporcionado.
</ResponseField>

<ResponseField name="expected_length" type="Integer">
  La longitud esperada para los IBAN del país específico según el estándar ISO 13616.
</ResponseField>

<ResponseField name="checksum_valid" type="Boolean">
  Si la validación del dígito de control del IBAN pasó utilizando el algoritmo MOD-97.
</ResponseField>

<ResponseField name="format_valid" type="Boolean">
  Si el formato del IBAN coincide con la estructura esperada para el país.
</ResponseField>

<ResponseField name="details" type="Object">
  Información detallada adicional sobre la estructura y el formato del IBAN.
</ResponseField>

<ResponseField name="details.structure" type="String">
  Una representación visual de la estructura del IBAN usando marcadores de posición B (Banco), S (Sort), C (Cliente) y K (Clave).
</ResponseField>

<ResponseField name="details.example" type="String">
  Un ejemplo correctamente formateado del IBAN con espacios para facilitar la lectura.
</ResponseField>

<ResponseField name="details.bank_name" type="String">
  El nombre del banco (actualmente muestra "Bank information not available").
</ResponseField>

<ResponseField name="details.bank_bic" type="String">
  El código BIC del banco (actualmente muestra "BIC not available").
</ResponseField>

<ResponseField name="details.account_type" type="String">
  El tipo de cuenta (normalmente "Bank Account").
</ResponseField>

<ResponseField name="details.currency" type="String">
  El código de moneda del país (p. ej., EUR para países de la zona euro, GBP para Reino Unido).
</ResponseField>

## Ejemplos

### IBAN alemán válido

**Solicitud:**

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

**Respuesta:**

```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 francés válido

**Solicitud:**

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

**Respuesta:**

```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 no válido

**Solicitud:**

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

**Respuesta:**

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

## Manejo de errores

### Parámetro IBAN faltante

**Solicitud:**

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

**Respuesta:**

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

### Clave API faltante

**Solicitud:**

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

**Respuesta:**

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

## Estructura del IBAN

El IBAN consta de varios componentes:

1. **Código de país (2 caracteres)**: código de país ISO 3166-1 alpha-2
2. **Dígitos de control (2 caracteres)**: validación mediante algoritmo MOD-97
3. **Identificador bancario**: código bancario específico del país
4. **Número de cuenta**: identificador de la cuenta del cliente

### Formatos específicos por país

Los distintos países tienen estructuras de IBAN variables:

* **Alemania (DE)**: 22 caracteres - `BBBB BBBB BBBB BBBB BB`
* **Francia (FR)**: 27 caracteres - `BBBB BSSS SSCC CCCC CCCC CCC KK`
* **Italia (IT)**: 27 caracteres - `CAAA AABB BBSS CCCC CCCC CCX`
* **Reino Unido (GB)**: 22 caracteres - `BBBB SSSS SSCC CCCC CC`
* **España (ES)**: 24 caracteres - `BBBB SSSS DDCC CCCC CCCC CC`

Donde:

* **B** = Código bancario
* **S** = Código de sucursal
* **C** = Número de cuenta del cliente
* **K** = Dígito de control/clave
* **A** = Tipo de cuenta
* **D** = Dígito de control

## Reglas de validación

La API realiza una validación exhaustiva que incluye:

1. **Validación de formato**: comprueba si el IBAN sigue la estructura esperada para el país
2. **Validación de longitud**: verifica que la longitud del IBAN coincida con el estándar del país
3. **Validación de dígito de control**: realiza la validación mediante algoritmo MOD-97
4. **Validación del código de país**: garantiza que el código de país esté admitido
5. **Validación de caracteres**: comprueba que los caracteres alfanuméricos sean válidos

## Países admitidos

La API admite la validación de IBAN para más de 50 países, incluidos:

* **Europa**: Alemania, Francia, Italia, España, Países Bajos, Bélgica, Austria, Suiza, Reino Unido, Polonia
* **Asia**: EAU, Baréin, Israel, Jordania, Kazajistán, Kuwait
* **América**: Brasil, Costa Rica, República Dominicana, Guatemala
* **África**: Mauritania, Mauricio, Túnez

Para una lista completa de países admitidos, consulte la página [Países admitidos](/bank-validation/countries).