Generate Random IBAN

Documentazione API

Genera e valida via HTTP IBAN di test strutturalmente validi (ISO 13616, MOD-97). Tutte le risposte sono in JSON. Gli IBAN generati sono dati di test: nessuna banca li ha emessi.

URL di base

https://generaterandomiban.com/api/v1

Autenticazione

Tutti gli endpoint, tranne l'indice del servizio, richiedono una chiave API. Inviala nell'header X-API-Key (funziona anche Authorization: Bearer). Tieni la chiave sul tuo server e non inserirla mai nel codice lato client.

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

Le chiavi vengono rilasciate a mano. Scrivici una breve descrizione del tuo caso d'uso e te ne invieremo una.

apis@generaterandomiban.com

Limiti di richieste

I limiti valgono per chiave: 60 richieste al minuto di default, oppure il limite personalizzato impostato sulla tua chiave. Oltre il limite l'API risponde con HTTP 429 (Too Many Requests).

Endpoint

GET /api/v1 Pubblico

Indice del servizio con i metadati e l'elenco degli endpoint. Non serve una chiave API.

Esempio di richiesta
curl https://generaterandomiban.com/api/v1
Esempio di risposta
{
  "name": "Generate Random IBAN API",
  "version": "v1",
  "documentation": "https://generaterandomiban.com/it/apis/docs",
  "authentication": { "type": "api_key", "header": "X-API-Key" }
}

GET /api/v1/countries

Tutti i paesi supportati, ciascuno con il suo formato IBAN.

Esempio di richiesta
curl -H "X-API-Key: YOUR_KEY" https://generaterandomiban.com/api/v1/countries
Esempio di risposta
{
  "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}

Il formato IBAN di un singolo paese.

Parametro Posizione Descrizione
code path Codice paese ISO 3166-1 alpha-2, per esempio DE, FR o IT.
Esempio di richiesta
curl -H "X-API-Key: YOUR_KEY" https://generaterandomiban.com/api/v1/countries/DE
Esempio di risposta
{
  "country": {
    "code": "DE",
    "name": "Germany",
    "iban_length": 22,
    "bban_format": "8n10n",
    "example": "DE89370400440532013000"
  }
}

GET /api/v1/generate/{country}

Genera uno o più IBAN casuali e validi di un paese.

Le cifre di controllo nazionali (come la clé RIB francese, il CIN italiano o il DC spagnolo) sono calcolate in entrambe le modalità. Nessuna banca ha emesso gli IBAN realistici, ma uno potrebbe coincidere per caso con un conto reale: non usarli mai per pagamenti.

Parametro Posizione Descrizione
country path Codice paese ISO 3166-1 alpha-2.
count query Quanti IBAN restituire, da 1 a 100. Predefinito: 1.
realistic query Facoltativo. 1 o true per IBAN realistici: solo cifre e, dove disponibile, il codice reale di una grande banca, con un numero di conto casuale. 0 o false per IBAN completamente casuali, con lettere dove il formato le ammette. Predefinito: 1.
Esempio di richiesta
curl -H "X-API-Key: YOUR_KEY" "https://generaterandomiban.com/api/v1/generate/DE?count=2"
Esempio di risposta
{
  "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 i parametri passati in un body JSON.

Parametro Posizione Descrizione
country body Codice paese ISO 3166-1 alpha-2. Obbligatorio.
count body Quanti IBAN restituire, da 1 a 100. Predefinito: 1.
realistic body Booleano facoltativo, uguale al parametro realistic nell'URL. Predefinito: true.
Esempio di richiesta
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
Esempio di risposta
{
  "country": { "code": "FR", "name": "France", "iban_length": 27 },
  "count": 3,
  "realistic": true,
  "ibans": [ /* … */ ]
}

GET /api/v1/validate/{iban}

Valida un IBAN passato nell'URL, senza spazi.

Parametro Posizione Descrizione
iban path L'IBAN da validare, solo lettere e cifre.
Esempio di richiesta
curl -H "X-API-Key: YOUR_KEY" https://generaterandomiban.com/api/v1/validate/DE89370400440532013000
Esempio di risposta
{
  "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 inviato in un body JSON. Gli spazi sono ammessi.

Parametro Posizione Descrizione
iban body L'IBAN da validare. Obbligatorio.
Esempio di richiesta
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
Esempio di risposta
{
  "iban": "DE89370400440532013000",
  "valid": true,
  "country_code": "DE",
  "checks": { "mod97": true, "length": true, "format": true, "country_supported": true }
}

Errori e codici di stato

Gli errori usano i codici di stato HTTP standard e un body JSON con un oggetto error che contiene un codice e un messaggio. I più comuni sono 401 (chiave mancante o non valida), 404 (paese o endpoint sconosciuto), 422 (parametri non validi) e 429 (limite di richieste superato).

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

Scaricare una lista (senza chiave)

Il generatore ti dà anche un file: fino a 100 IBAN di un paese in CSV, JSON, SQL (istruzioni INSERT) o testo semplice, con una colonna per ogni segmento del BBAN. Non serve una chiave API e il limite è di 30 download al minuto.

Parametro Posizione Descrizione
countrypathCodice paese ISO 3166-1 alpha-2.
formatquerycsv, json, sql o txt. Predefinito: csv.
countqueryQuanti IBAN, da 1 a 100. Predefinito: 10.
realisticquery1 per IBAN realistici, 0 per IBAN completamente casuali. Predefinito: 1.
Esempio di richiesta
curl -OJ "https://generaterandomiban.com/export/de?format=csv&count=50"
Esempio di risposta
iban,iban_print,country,check_digits,bank,account
DE89370400440532013000,DE89 3704 0044 0532 0130 00,DE,89,37040044,0532013000

Server MCP

Gli agenti AI possono usare le stesse funzioni tramite un server Model Context Protocol su /mcp (Streamable HTTP, JSON-RPC 2.0). È pubblico, non richiede una chiave API e accetta fino a 120 richieste al minuto.

Tool Descrizione
list_countriesElenca i paesi supportati con la lunghezza del loro IBAN.
generate_ibanGenera da 1 a 100 IBAN di test di un paese.
validate_ibanControlla un IBAN: MOD-97, lunghezza prevista e supporto del paese.
Esempio di richiesta
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 accetta anche "realistic", che per impostazione predefinita è true. Passa "realistic": false per IBAN completamente casuali.

Server card per la discovery: /.well-known/mcp/server-card.json

Specifica OpenAPI

Una descrizione OpenAPI 3.1 dell'API REST in formato leggibile dalle macchine, per generatori di client e strumenti per API: /api/v1/openapi.json

Libreria JavaScript

Per validare gli IBAN nel browser o offline, senza chiamare l'API, usa il nostro pacchetto open source iban-check per JavaScript e TypeScript (nessuna dipendenza, licenza MIT): GitHub · npm

Terminal
npm install iban-check

Ottieni una chiave API

Le chiavi vengono rilasciate a mano. Scrivici una breve descrizione del tuo caso d'uso e te ne invieremo una.

Richiedi una chiave API