Generate Random IBAN

API 文档

通过 HTTP 生成和验证结构有效的测试 IBAN（ISO 13616，MOD-97）。所有响应均为 JSON。生成的 IBAN 属于测试数据，并非银行发放。

基础 URL

https://generaterandomiban.com/api/v1

身份验证

除服务索引外，所有接口都需要 API 密钥。请在 X-API-Key 请求头中发送（也可以使用 Authorization: Bearer）。密钥应保存在服务器端，切勿放进客户端代码。

curl -H "X-API-Key: YOUR_KEY" https://generaterandomiban.com/api/v1/countries

密钥由人工发放。发邮件简要说明您的使用场景，我们会给您发送一个密钥。

apis@generaterandomiban.com

速率限制

速率限制按密钥计算：默认每分钟 60 次请求，或按您的密钥单独设置的上限。超出限制时，API 返回 HTTP 429（Too Many Requests）。

接口列表

GET /api/v1 公开

服务索引，包含元数据和接口列表。无需 API 密钥。

请求示例
curl https://generaterandomiban.com/api/v1
响应示例
{
  "name": "Generate Random IBAN API",
  "version": "v1",
  "documentation": "https://generaterandomiban.com/zh/apis/docs",
  "authentication": { "type": "api_key", "header": "X-API-Key" }
}

GET /api/v1/countries

所有支持的国家及其 IBAN 格式。

请求示例
curl -H "X-API-Key: YOUR_KEY" https://generaterandomiban.com/api/v1/countries
响应示例
{
  "count": 91,
  "countries": [
    {
      "code": "DE",
      "name": "Germany",
      "slug": "germany",
      "iban_length": 22,
      "bban_length": 18,
      "bban_format": "8n10n",
      "structure": "DEkk bbbb bbbb cccc cccc cc",
      "example": "DE89370400440532013000"
    }
  ]
}

GET /api/v1/countries/{code}

单个国家的 IBAN 格式。

参数 位置 说明
code path ISO 3166-1 alpha-2 国家代码，例如 DE、FR 或 IT。
请求示例
curl -H "X-API-Key: YOUR_KEY" https://generaterandomiban.com/api/v1/countries/DE
响应示例
{
  "country": {
    "code": "DE",
    "name": "Germany",
    "iban_length": 22,
    "bban_format": "8n10n",
    "example": "DE89370400440532013000"
  }
}

GET /api/v1/generate/{country}

为指定国家生成一个或多个随机、有效的 IBAN。

两种模式都会计算各国的国内校验位（如法国的 clé RIB、意大利的 CIN、西班牙的 DC）。仿真 IBAN 并非银行发放，但可能碰巧与真实账户一致，切勿用于付款。

参数 位置 说明
country path ISO 3166-1 alpha-2 国家代码。
count query 返回的 IBAN 数量，1 到 100。默认值：1。
realistic query 可选。设为 1 或 true 时生成仿真 IBAN：仅含数字，并在有数据时使用大型银行的真实银行代码，账号随机。设为 0 或 false 时生成完全随机的 IBAN，格式允许的位置可能出现字母。默认值：1。
请求示例
curl -H "X-API-Key: YOUR_KEY" "https://generaterandomiban.com/api/v1/generate/DE?count=2"
响应示例
{
  "country": { "code": "DE", "name": "Germany", "iban_length": 22 },
  "count": 2,
  "realistic": true,
  "ibans": [
    {
      "iban": "DE89370400440532013000",
      "formatted": "DE89 3704 0044 0532 0130 00",
      "country": "DE",
      "check_digits": "89",
      "bban": "370400440532013000",
      "length": 22,
      "valid": true
    }
  ]
}

POST /api/v1/generate

通过 JSON 请求体传入参数，生成 IBAN。

参数 位置 说明
country body ISO 3166-1 alpha-2 国家代码。必填。
count body 返回的 IBAN 数量，1 到 100。默认值：1。
realistic body 可选布尔值，与 URL 参数 realistic 相同。默认值：true。
请求示例
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"FR","count":3,"realistic":true}' https://generaterandomiban.com/api/v1/generate
响应示例
{
  "country": { "code": "FR", "name": "France", "iban_length": 27 },
  "count": 3,
  "realistic": true,
  "ibans": [ /* … */ ]
}

GET /api/v1/validate/{iban}

验证通过 URL 传入的 IBAN（不含空格）。

参数 位置 说明
iban path 要验证的 IBAN，只能包含字母和数字。
请求示例
curl -H "X-API-Key: YOUR_KEY" https://generaterandomiban.com/api/v1/validate/DE89370400440532013000
响应示例
{
  "iban": "DE89370400440532013000",
  "valid": true,
  "country_code": "DE",
  "country_supported": true,
  "check_digits": "89",
  "bban": "370400440532013000",
  "length": 22,
  "expected_length": 22,
  "checks": { "mod97": true, "length": true, "format": true, "country_supported": true }
}

POST /api/v1/validate

验证通过 JSON 请求体发送的 IBAN，允许包含空格。

参数 位置 说明
iban body 要验证的 IBAN。必填。
请求示例
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"iban":"DE89 3704 0044 0532 0130 00"}' https://generaterandomiban.com/api/v1/validate
响应示例
{
  "iban": "DE89370400440532013000",
  "valid": true,
  "country_code": "DE",
  "checks": { "mod97": true, "length": true, "format": true, "country_supported": true }
}

错误与状态码

出错时返回标准 HTTP 状态码和一个 JSON 响应体，其中的 error 对象包含 code 和 message。常见的有 401（缺少密钥或密钥无效）、404（未知国家或接口）、422（参数无效）和 429（超出速率限制）。

{
  "error": {
    "code": "invalid_request",
    "message": "The \"count\" parameter must be an integer between 1 and 100."
  }
}

下载列表（无需密钥）

生成器还可以直接提供文件：同一国家最多 100 个 IBAN，格式为 CSV、JSON、SQL（INSERT 语句）或纯文本，BBAN 的每个分段各占一列。无需 API 密钥，每分钟最多下载 30 次。

参数 位置 说明
countrypathISO 3166-1 alpha-2 国家代码。
formatquerycsv、json、sql 或 txt。默认值：csv。
countqueryIBAN 数量，1 到 100。默认值：10。
realisticquery1 表示仿真 IBAN，0 表示完全随机的 IBAN。默认值：1。
请求示例
curl -OJ "https://generaterandomiban.com/export/de?format=csv&count=50"
响应示例
iban,iban_print,country,check_digits,bank,account
DE89370400440532013000,DE89 3704 0044 0532 0130 00,DE,89,37040044,0532013000

MCP 服务器

AI 智能体可以通过位于 /mcp 的 Model Context Protocol 服务器使用同样的功能（Streamable HTTP，JSON-RPC 2.0）。该服务器公开开放，无需 API 密钥，每分钟最多接受 120 次请求。

工具 说明
list_countries列出支持的国家及其 IBAN 长度。
generate_iban为指定国家生成 1 到 100 个测试 IBAN。
validate_iban检查 IBAN：MOD-97 校验、预期长度以及该国家是否受支持。
请求示例
curl -X POST https://generaterandomiban.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"generate_iban","arguments":{"country":"IT","count":2}}}'

generate_iban 还接受 "realistic" 参数，默认为 true；传入 "realistic": false 可生成完全随机的 IBAN。

用于服务发现的服务器卡片： /.well-known/mcp/server-card.json

OpenAPI 规范

REST API 的机器可读 OpenAPI 3.1 描述文件，可用于客户端生成器和各类 API 工具： /api/v1/openapi.json

JavaScript 库

如需在浏览器中或离线验证 IBAN 而不调用 API，可使用我们的开源 iban-check 包，适用于 JavaScript 和 TypeScript（无依赖，MIT 许可证）： GitHub · npm

Terminal
npm install iban-check

获取 API 密钥

密钥由人工发放。发邮件简要说明您的使用场景，我们会给您发送一个密钥。

申请 API 密钥

我们使用 Cookie 来改善您的体验

我们和选定的第三方会出于技术目的使用 Cookie 或类似技术，并在您同意后用于网站流量分析。

您可以随时自由地给予、拒绝或撤回同意。

请阅读我们的 Cookie 政策和隐私政策。