Documentação da API de IBAN: endpoints e exemplos

URL base

https://generaterandomiban.com/api/v1

Autenticação

Todos os endpoints, exceto o índice do serviço, precisam de uma chave de API. Envie-a no cabeçalho X-API-Key (Authorization: Bearer também funciona). Mantenha a chave no seu servidor e nunca a inclua em código do lado do cliente.

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

As chaves são emitidas manualmente. Envie-nos um e-mail com uma breve descrição do seu caso de uso e enviamos-lhe uma.

apis@generaterandomiban.com

Limites de pedidos

Os limites aplicam-se por chave: 60 pedidos por minuto por omissão, ou o limite personalizado definido na sua chave. Acima do limite, a API responde com HTTP 429 (Too Many Requests).

Endpoints

GET `/api/v1` Público

Índice do serviço com metadados e a lista de endpoints. Não precisa de chave de API.

Exemplo de pedido

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

Exemplo de resposta

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

GET `/api/v1/countries`

Todos os países suportados, com o respetivo formato IBAN.

Exemplo de pedido

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

Exemplo de resposta

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

O formato IBAN de um país.

Parâmetro	Local	Descrição
`code`	path	Código de país ISO 3166-1 alfa-2, por exemplo DE, FR ou IT.

Exemplo de pedido

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

Exemplo de resposta

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

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

Gera um ou mais IBAN aleatórios e válidos para um país.

Os dígitos de controlo nacionais (como a clé RIB francesa, o CIN italiano ou o DC espanhol) são calculados nos dois modos. Nenhum banco emitiu os IBAN realistas, mas algum pode coincidir por acaso com uma conta real: nunca os utilize para pagamentos.

Parâmetro	Local	Descrição
`country`	path	Código de país ISO 3166-1 alfa-2.
`count`	query	Quantos IBAN devolver, de 1 a 100. Por omissão: 1.
`realistic`	query	Opcional. 1 ou true para IBAN realistas: apenas dígitos e, quando disponível, o código real de um grande banco, com um número de conta aleatório. 0 ou false para IBAN totalmente aleatórios, com letras onde o formato as permite. Por omissão: 1.

Exemplo de pedido

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

Exemplo de resposta

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

Gera IBAN com os parâmetros num corpo JSON.

Parâmetro	Local	Descrição
`country`	body	Código de país ISO 3166-1 alfa-2. Obrigatório.
`count`	body	Quantos IBAN devolver, de 1 a 100. Por omissão: 1.
`realistic`	body	Booleano opcional, igual ao parâmetro realistic do URL. Por omissão: true.

Exemplo de pedido

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

Exemplo de resposta

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

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

Valida um IBAN passado no URL, sem espaços.

Parâmetro	Local	Descrição
`iban`	path	O IBAN a validar, apenas letras e dígitos.

Exemplo de pedido

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

Exemplo de resposta

{
  "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 um IBAN enviado num corpo JSON. Aceita espaços.

Parâmetro	Local	Descrição
`iban`	body	O IBAN a validar. Obrigatório.

Exemplo de pedido

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

Exemplo de resposta

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

Erros e códigos de estado

Os erros usam códigos de estado HTTP padrão e um corpo JSON com um objeto error, que contém um código e uma mensagem. Os mais comuns são 401 (chave ausente ou inválida), 404 (país ou endpoint desconhecido), 422 (parâmetros inválidos) e 429 (limite de pedidos excedido).

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

Transferir uma lista (sem chave)

O gerador também lhe dá um ficheiro: até 100 IBAN de um país em CSV, JSON, SQL (instruções INSERT) ou texto simples, com uma coluna por segmento do BBAN. Não precisa de chave de API e permite 30 transferências por minuto.

Parâmetro	Local	Descrição
`country`	path	Código de país ISO 3166-1 alfa-2.
`format`	query	csv, json, sql ou txt. Por omissão: csv.
`count`	query	Quantos IBAN, de 1 a 100. Por omissão: 10.
`realistic`	query	1 para IBAN realistas, 0 para IBAN totalmente aleatórios. Por omissão: 1.

Exemplo de pedido

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

Exemplo de resposta

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

Servidor MCP

Os agentes de IA podem usar as mesmas funcionalidades através de um servidor Model Context Protocol em /mcp (Streamable HTTP, JSON-RPC 2.0). É público, não precisa de chave de API e aceita até 120 pedidos por minuto.

Ferramenta	Descrição
`list_countries`	Lista os países suportados com o comprimento do IBAN.
`generate_iban`	Gera de 1 a 100 IBAN de teste para um país.
`validate_iban`	Verifica um IBAN: MOD-97, comprimento esperado e se o país é suportado.

Exemplo de pedido

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 também aceita "realistic", que por omissão é true. Passe "realistic": false para obter IBAN totalmente aleatórios.

Cartão do servidor para descoberta: /.well-known/mcp/server-card.json

Especificação OpenAPI

Uma descrição OpenAPI 3.1 da API REST, legível por máquinas, para geradores de clientes e ferramentas de API: /api/v1/openapi.json

Biblioteca JavaScript

Para validar IBAN no navegador ou offline, sem chamar a API, use o nosso pacote de código aberto iban-check para JavaScript e TypeScript (sem dependências, licença MIT): GitHub · npm

Terminal

npm install iban-check

Documentação da API

URL base

Autenticação

Limites de pedidos

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

Erros e códigos de estado

Transferir uma lista (sem chave)

Servidor MCP

Especificação OpenAPI

Biblioteca JavaScript

Obter uma chave 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`