Документация IBAN API: эндпоинты и примеры

Базовый 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/ru/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`

Генерирует IBAN по параметрам из тела запроса в JSON.

Параметр	Где	Описание
`country`	body	Код страны ISO 3166-1 alpha-2. Обязательный.
`count`	body	Сколько IBAN вернуть, от 1 до 100. По умолчанию: 1.
`realistic`	body	Необязательный булев параметр, то же, что realistic в URL. По умолчанию: 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}`

Проверяет IBAN, переданный в URL без пробелов.

Параметр	Где	Описание
`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`

Проверяет IBAN из тела запроса в JSON. Пробелы допускаются.

Параметр	Где	Описание
`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 загрузок в минуту.

Параметр	Где	Описание
`country`	path	Код страны ISO 3166-1 alpha-2.
`format`	query	csv, json, sql или txt. По умолчанию: csv.
`count`	query	Сколько IBAN, от 1 до 100. По умолчанию: 10.
`realistic`	query	1 для реалистичных IBAN, 0 для полностью случайных. По умолчанию: 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-сервер

ИИ-агенты могут пользоваться теми же функциями через сервер Model Context Protocol по адресу /mcp (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

Базовый URL

Аутентификация

Лимиты запросов

Эндпоинты

GET `/api/v1` Публичный

GET `/api/v1/countries`

GET `/api/v1/countries/{code}`

GET `/api/v1/generate/{country}`

POST `/api/v1/generate`

GET `/api/v1/validate/{iban}`

POST `/api/v1/validate`

Ошибки и коды состояния

Скачать список (без ключа)

MCP-сервер

Спецификация OpenAPI

Библиотека для JavaScript

Получите API-ключ

Документация API

Базовый URL

Аутентификация

Лимиты запросов

Эндпоинты

GET /api/v1 Публичный

GET /api/v1/countries

GET /api/v1/countries/{code}

GET /api/v1/generate/{country}

POST /api/v1/generate

GET /api/v1/validate/{iban}

POST /api/v1/validate

Ошибки и коды состояния

Скачать список (без ключа)

MCP-сервер

Спецификация OpenAPI

Библиотека для JavaScript

Получите API-ключ

GET `/api/v1` Публичный

GET `/api/v1/countries`

GET `/api/v1/countries/{code}`

GET `/api/v1/generate/{country}`

POST `/api/v1/generate`

GET `/api/v1/validate/{iban}`

POST `/api/v1/validate`