Generate Random IBAN

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

Генерируйте и проверяйте структурно валидные тестовые IBAN (ISO 13616, MOD-97) по HTTP. Все ответы приходят в 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/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 загрузок в минуту.

Параметр Где Описание
countrypathКод страны ISO 3166-1 alpha-2.
formatquerycsv, json, sql или txt. По умолчанию: csv.
countqueryСколько IBAN, от 1 до 100. По умолчанию: 10.
realisticquery1 для реалистичных 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-ключ

Ключи выдаются вручную. Напишите нам с кратким описанием вашей задачи, и мы пришлём ключ.

Запросить API-ключ