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

# Перевірка IBAN

> Ендпоінт `iban` перевіряє міжнародні банківські рахунки (IBAN) з повною перевіркою за країною, контролем формату та детальною структурною інформацією для фінансових застосунків.

## Початок роботи

### Базовий URL

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

### Ендпоінт перевірки

Ендпоінт `iban` потребує API-ключа та параметра IBAN для комплексної перевірки міжнародних банківських рахунків.

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

Цей успішний запит перевіряє німецький IBAN і повертає детальну інформацію:

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

### Параметри запиту

<ParamField query="api_key" type="String" required>
  Ваш унікальний API-ключ. Зверніть увагу: у кожного користувача є унікальні API-ключі *для кожного з
  API Cleariflow*, тому ключ Bank Validation API не працюватиме для Exchange
  Rates API, наприклад.
</ParamField>

<ParamField query="iban" type="String" required>
  Міжнародний банківський рахунок (IBAN) для перевірки. Пробіли дозволені та автоматично видаляються. IBAN має відповідати формату ISO 13616.
</ParamField>

### Параметри відповіді

Відповідь API повертається у універсальному та легкому форматі [JSON](https://www.json.org/json-en.html).

<ResponseField name="iban" type="String">
  Нормалізований IBAN без пробілів у верхньому регістрі.
</ResponseField>

<ResponseField name="is_valid" type="Boolean">
  Загальний результат перевірки дійсності IBAN згідно з усіма правилами.
</ResponseField>

<ResponseField name="country_code" type="String">
  Дволітерний ISO-код країни (наприклад, DE — Німеччина, FR — Франція).
</ResponseField>

<ResponseField name="country_name" type="String">
  Повна назва країни, пов'язаної з IBAN.
</ResponseField>

<ResponseField name="bank_code" type="String">
  Код ідентифікації банку з IBAN відповідно до формату країни.
</ResponseField>

<ResponseField name="account_number" type="String">
  Частина номера рахунку IBAN без коду країни, контрольних цифр і коду банку.
</ResponseField>

<ResponseField name="length" type="Integer">
  Фактична довжина наданого IBAN.
</ResponseField>

<ResponseField name="expected_length" type="Integer">
  Очікувана довжина IBAN для країни згідно з ISO 13616.
</ResponseField>

<ResponseField name="checksum_valid" type="Boolean">
  Чи пройшла перевірка контрольної суми IBAN за MOD-97.
</ResponseField>

<ResponseField name="format_valid" type="Boolean">
  Чи відповідає формат IBAN очікуваній структурі для країни.
</ResponseField>

<ResponseField name="details" type="Object">
  Додаткова інформація про структуру та форматування IBAN.
</ResponseField>

<ResponseField name="details.structure" type="String">
  Візуальне представлення структури IBAN: B (Bank), S (Sort), C (Customer), K (Key).
</ResponseField>

<ResponseField name="details.example" type="String">
  Приклад IBAN з пробілами для зручності читання.
</ResponseField>

<ResponseField name="details.bank_name" type="String">
  The name of the bank (currently shows "Bank information not available").
</ResponseField>

<ResponseField name="details.bank_bic" type="String">
  The BIC code for the bank (currently shows "BIC not available").
</ResponseField>

<ResponseField name="details.account_type" type="String">
  Тип рахунку (зазвичай «Bank Account»).
</ResponseField>

<ResponseField name="details.currency" type="String">
  Код валюти країни (наприклад, EUR для єврозони, GBP для UK).
</ResponseField>

## Приклади

### Дійсний німецький IBAN

**Запит:**

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

**Відповідь:**

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

**Запит:**

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

**Відповідь:**

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

**Запит:**

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

**Відповідь:**

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

## Обробка помилок

### Відсутній параметр IBAN

**Запит:**

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

**Відповідь:**

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

### Відсутній API-ключ

**Запит:**

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

**Відповідь:**

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

## Структура IBAN

IBAN складається з кількох компонентів:

1. **Код країни (2 символи)**: ISO 3166-1 alpha-2
2. **Контрольні цифри (2 символи)**: перевірка MOD-97
3. **Ідентифікатор банку**: код банку країни
4. **Номер рахунку**: ідентифікатор рахунку клієнта

### Формати за країнами

Різні країни мають різні структури IBAN:

* **Німеччина (DE)**: 22 символи - `BBBB BBBB BBBB BBBB BB`
* **Франція (FR)**: 27 символів - `BBBB BSSS SSCC CCCC CCCC CCC KK`
* **Італія (IT)**: 27 символів - `CAAA AABB BBSS CCCC CCCC CCX`
* **Велика Британія (GB)**: 22 символи - `BBBB SSSS SSCC CCCC CC`
* **Іспанія (ES)**: 24 символи - `BBBB SSSS DDCC CCCC CCCC CC`

Де:

* **B** = код банку
* **S** = sort code
* **C** = номер рахунку клієнта
* **K** = ключ/контрольна цифра
* **A** = тип рахунку
* **D** = контрольна цифра

## Правила перевірки

API виконує комплексну перевірку:

1. **Перевірка формату**: чи IBAN відповідає структурі країни
2. **Перевірка довжини**: чи довжина відповідає стандарту країни
3. **Перевірка контрольної суми**: MOD-97
4. **Перевірка коду країни**: чи код підтримується
5. **Перевірка символів**: дійсні буквено-цифрові символи

## Підтримувані країни

API підтримує перевірку IBAN для 50+ країн, включаючи:

* **Європа**: Німеччина, Франція, Італія, Іспанія, Нідерланди, Бельгія, Австрія, Швейцарія, UK, Польща
* **Азія**: ОАЕ, Бахрейн, Ізраїль, Jordan, Казахстан, Кувейт
* **Америка**: Бразилія, Costa Rica, Домініканська Республіка, Гватемала
* **Африка**: Мавританія, Маврикій, Туніс

Повний список — на сторінці [Підтримувані країни](/bank-validation/countries).