> ## 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` 端点验证国际银行账号，提供全面的国家特定验证、格式检查和详细的结构信息，适用于金融应用。

## 快速开始

### 基础 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 密钥。请注意，每个用户为每个 Cleariflow API 拥有
  独立的 API 密钥，因此您的银行验证 API 密钥无法用于汇率
  API，例如。
</ParamField>

<ParamField query="iban" type="String" required>
  要验证的国际银行账号。允许空格，处理过程中将自动移除。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">
  根据 ISO 13616 标准，特定国家 IBAN 的预期长度。
</ResponseField>

<ResponseField name="checksum_valid" type="Boolean">
  使用 MOD-97 算法的 IBAN 校验和验证是否通过。
</ResponseField>

<ResponseField name="format_valid" type="Boolean">
  IBAN 格式是否符合该国家的预期结构。
</ResponseField>

<ResponseField name="details" type="Object">
  关于 IBAN 结构和格式的附加详细信息。
</ResponseField>

<ResponseField name="details.structure" type="String">
  使用 B（银行）、S（分类）、C（客户）和 K（密钥）占位符的 IBAN 结构可视化表示。
</ResponseField>

<ResponseField name="details.example" type="String">
  带空格的可读 IBAN 格式示例。
</ResponseField>

<ResponseField name="details.bank_name" type="String">
  银行名称（当前显示 "Bank information not available"）。
</ResponseField>

<ResponseField name="details.bank_bic" type="String">
  银行的 BIC 代码（当前显示 "BIC not available"）。
</ResponseField>

<ResponseField name="details.account_type" type="String">
  账户类型（通常为 "Bank Account"）。
</ResponseField>

<ResponseField name="details.currency" type="String">
  国家的货币代码（例如欧元区国家为 EUR，英国为 GBP）。
</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** = 分类代码
* **C** = 客户账号
* **K** = 密钥/校验位
* **A** = 账户类型
* **D** = 控制位

## 验证规则

API 执行全面验证，包括：

1. **格式验证**：检查 IBAN 是否符合该国家的预期结构
2. **长度验证**：验证 IBAN 长度是否符合国家标准
3. **校验和验证**：执行 MOD-97 算法验证
4. **国家代码验证**：确保国家代码受支持
5. **字符验证**：检查有效的字母数字字符

## 支持的国家

API 支持 50 多个国家的 IBAN 验证，包括：

* **欧洲**：德国、法国、意大利、西班牙、荷兰、比利时、奥地利、瑞士、英国、波兰
* **亚洲**：阿联酋、巴林、以色列、约旦、哈萨克斯坦、科威特
* **美洲**：巴西、哥斯达黎加、多米尼加共和国、危地马拉
* **非洲**：毛里塔尼亚、毛里求斯、突尼斯

完整支持国家列表，请参阅[支持的国家](/bank-validation/countries)页面。