Documentación de la API de IBAN: endpoints y ejemplos

URL base

https://generaterandomiban.com/api/v1

Autenticación

Todos los endpoints, salvo el índice del servicio, necesitan una clave de API. Envíala en la cabecera X-API-Key (Authorization: Bearer también funciona). Guarda la clave en tu servidor y no la incluyas nunca en código del lado del cliente.

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

Las claves se conceden a mano. Escríbenos con una breve descripción de tu caso de uso y te enviaremos una.

apis@generaterandomiban.com

Límites de peticiones

Los límites se aplican por clave: 60 peticiones por minuto por defecto, o el límite personalizado de tu clave. Si lo superas, la API responde con HTTP 429 (Too Many Requests).

Endpoints

GET `/api/v1` Público

Índice del servicio con metadatos y la lista de endpoints. No necesita clave de API.

Ejemplo de petición

curl https://generaterandomiban.com/api/v1

Ejemplo de respuesta

{
  "name": "Generate Random IBAN API",
  "version": "v1",
  "documentation": "https://generaterandomiban.com/es/apis/docs",
  "authentication": { "type": "api_key", "header": "X-API-Key" }
}

GET `/api/v1/countries`

Todos los países disponibles con su formato de IBAN.

Ejemplo de petición

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

Ejemplo de respuesta

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

El formato de IBAN de un país.

Parámetro	Ubicación	Descripción
`code`	path	Código de país ISO 3166-1 alfa-2, por ejemplo DE, FR o IT.

Ejemplo de petición

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

Ejemplo de respuesta

{
  "country": {
    "code": "DE",
    "name": "Germany",
    "iban_length": 22,
    "bban_format": "8n10n",
    "example": "DE89370400440532013000"
  }
}

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

Genera uno o varios IBAN aleatorios y válidos de un país.

Los dígitos de control nacionales (como la clé RIB francesa, el CIN italiano o el DC español) se calculan en ambos modos. Ningún banco ha emitido los IBAN realistas, pero alguno podría coincidir por casualidad con una cuenta real: no los uses nunca para pagos.

Parámetro	Ubicación	Descripción
`country`	path	Código de país ISO 3166-1 alfa-2.
`count`	query	Cuántos IBAN devolver, de 1 a 100. Por defecto: 1.
`realistic`	query	Opcional. 1 o true para IBAN realistas: solo dígitos y, cuando está disponible, el código real de un banco importante, con un número de cuenta aleatorio. 0 o false para IBAN totalmente aleatorios, con letras donde el formato las admite. Por defecto: 1.

Ejemplo de petición

curl -H "X-API-Key: YOUR_KEY" "https://generaterandomiban.com/api/v1/generate/DE?count=2"

Ejemplo de respuesta

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

Genera IBAN con los parámetros en un cuerpo JSON.

Parámetro	Ubicación	Descripción
`country`	body	Código de país ISO 3166-1 alfa-2. Obligatorio.
`count`	body	Cuántos IBAN devolver, de 1 a 100. Por defecto: 1.
`realistic`	body	Booleano opcional, igual que el parámetro realistic de la URL. Por defecto: true.

Ejemplo de petición

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

Ejemplo de respuesta

{
  "country": { "code": "FR", "name": "France", "iban_length": 27 },
  "count": 3,
  "realistic": true,
  "ibans": [ /* … */ ]
}

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

Valida un IBAN incluido en la URL, sin espacios.

Parámetro	Ubicación	Descripción
`iban`	path	El IBAN que se quiere validar, solo letras y dígitos.

Ejemplo de petición

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

Ejemplo de respuesta

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

Valida un IBAN enviado en un cuerpo JSON. Admite espacios.

Parámetro	Ubicación	Descripción
`iban`	body	El IBAN que se quiere validar. Obligatorio.

Ejemplo de petición

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

Ejemplo de respuesta

{
  "iban": "DE89370400440532013000",
  "valid": true,
  "country_code": "DE",
  "checks": { "mod97": true, "length": true, "format": true, "country_supported": true }
}

Errores y códigos de estado

Los errores usan códigos de estado HTTP estándar y un cuerpo JSON con un objeto error que contiene un code y un message. Los más habituales son 401 (clave ausente o no válida), 404 (país o endpoint desconocido), 422 (parámetros no válidos) y 429 (límite de peticiones superado).

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

Descargar una lista (sin clave)

El generador también te da un archivo: hasta 100 IBAN de un país en CSV, JSON, SQL (sentencias INSERT) o texto plano, con una columna por segmento del BBAN. No necesita clave de API y admite 30 descargas por minuto.

Parámetro	Ubicación	Descripción
`country`	path	Código de país ISO 3166-1 alfa-2.
`format`	query	csv, json, sql o txt. Por defecto: csv.
`count`	query	Cuántos IBAN, de 1 a 100. Por defecto: 10.
`realistic`	query	1 para IBAN realistas, 0 para IBAN totalmente aleatorios. Por defecto: 1.

Ejemplo de petición

curl -OJ "https://generaterandomiban.com/export/de?format=csv&count=50"

Ejemplo de respuesta

iban,iban_print,country,check_digits,bank,account
DE89370400440532013000,DE89 3704 0044 0532 0130 00,DE,89,37040044,0532013000

Servidor MCP

Los agentes de IA pueden usar las mismas funciones a través de un servidor Model Context Protocol en /mcp (Streamable HTTP, JSON-RPC 2.0). Es público, no necesita clave de API y acepta hasta 120 peticiones por minuto.

Herramienta	Descripción
`list_countries`	Lista los países disponibles con la longitud de su IBAN.
`generate_iban`	Genera de 1 a 100 IBAN de prueba de un país.
`validate_iban`	Comprueba un IBAN: MOD-97, longitud esperada y si el país está disponible.

Ejemplo de petición

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 también acepta "realistic", que por defecto es true. Pasa "realistic": false para obtener IBAN totalmente aleatorios.

Ficha del servidor (server card) para el descubrimiento: /.well-known/mcp/server-card.json

Especificación OpenAPI

Una descripción OpenAPI 3.1 de la API REST, legible por máquinas, para generadores de clientes y herramientas de API: /api/v1/openapi.json

Biblioteca JavaScript

Para validar IBAN en el navegador o sin conexión, sin llamar a la API, usa nuestro paquete de código abierto iban-check para JavaScript y TypeScript (sin dependencias, licencia MIT): GitHub · npm

Terminal

npm install iban-check

Documentación de la API

URL base

Autenticación

Límites de peticiones

Endpoints

GET /api/v1 Público

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

Errores y códigos de estado

Descargar una lista (sin clave)

Servidor MCP

Especificación OpenAPI

Biblioteca JavaScript

Consigue una clave de API

GET `/api/v1` Público

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`