Saltar para o conteúdo principal
GET
/
v1
/
iban
Validação IBAN
curl --request GET \
  --url https://bankvalidation.cleariflow.com/v1/iban/
{
  "iban": "DE89370400440532013000",
  "is_valid": true,
  "country_code": "DE",
  "country_name": "Germany",
  "bank_code": "37040044",
  "account_number": "0532013000",
  "length": 22,
  "expected_length": 22,
  "checksum_valid": true,
  "format_valid": true,
  "details": {
    "structure": "BBBB BBBB BBBB BBBB BB",
    "example": "DE89 3704 0044 0532 0130 00",
    "bank_name": "Bank information not available",
    "bank_bic": "BIC not available",
    "account_type": "Bank Account",
    "currency": "EUR"
  }
}

​
Primeiros passos

​
URL base

https://bankvalidation.cleariflow.com/v1/iban/

​
Endpoint de validação

O endpoint iban requer a sua chave API e um parâmetro IBAN para realizar uma validação abrangente de International Bank Account Numbers. 
https://bankvalidation.cleariflow.com/v1/iban/
? api_key = YOUR_UNIQUE_API_KEY
& iban = DE89370400440532013000
Este pedido bem-sucedido valida um IBAN alemão e devolve informação detalhada: 
{
  "iban": "DE89370400440532013000",
  "is_valid": true,
  "country_code": "DE",
  "country_name": "Germany",
  "bank_code": "37040044",
  "account_number": "0532013000",
  "length": 22,
  "expected_length": 22,
  "checksum_valid": true,
  "format_valid": true,
  "details": {
    "structure": "BBBB BBBB BBBB BBBB BB",
    "example": "DE89 3704 0044 0532 0130 00",
    "bank_name": "Bank information not available",
    "bank_bic": "BIC not available",
    "account_type": "Bank Account",
    "currency": "EUR"
  }
}

​
Parâmetros de pedido

​
api_key
String
obrigatório
A sua chave API única. Tenha em conta que cada utilizador tem chaves API únicas para cada uma das APIs Cleariflow, por isso a sua chave da API de validação bancária não funcionará para a sua API de taxas de câmbio, por exemplo.
​
iban
String
obrigatório
O International Bank Account Number a validar. São permitidos espaços e serão removidos automaticamente durante o processamento. O IBAN deve seguir o formato padrão ISO 13616.

​
Parâmetros de resposta

A resposta da API é devolvida num formato JSON universal e leve.
​
iban
String
O IBAN normalizado sem espaços, devolvido em maiúsculas.
​
is_valid
Boolean
Resultado geral da validação que indica se o IBAN é válido de acordo com todas as regras de validação.
​
country_code
String
O código de país ISO de duas letras (p. ex., DE para Alemanha, FR para França).
​
country_name
String
O nome completo do país associado ao IBAN.
​
bank_code
String
O código identificador bancário extraído do IBAN conforme o formato específico do país.
​
account_number
String
A parte do número de conta do IBAN, excluindo o código de país, o dígito de controlo e o código bancário.
​
length
Integer
O comprimento real do IBAN fornecido.
​
expected_length
Integer
O comprimento esperado para IBAN do país específico segundo o padrão ISO 13616.
​
checksum_valid
Boolean
Se a validação do dígito de controlo do IBAN passou utilizando o algoritmo MOD-97.
​
format_valid
Boolean
Se o formato do IBAN coincide com a estrutura esperada para o país.
​
details
Object
Informação detalhada adicional sobre a estrutura e o formato do IBAN.
​
details.structure
String
Uma representação visual da estrutura do IBAN usando marcadores B (Banco), S (Sort), C (Cliente) e K (Chave).
​
details.example
String
Um exemplo corretamente formatado do IBAN com espaços para facilitar a leitura.
​
details.bank_name
String
O nome do banco (atualmente mostra “Bank information not available”).
​
details.bank_bic
String
O código BIC do banco (atualmente mostra “BIC not available”).
​
details.account_type
String
O tipo de conta (normalmente “Bank Account”).
​
details.currency
String
O código de moeda do país (p. ex., EUR para países da zona euro, GBP para Reino Unido).

​
Exemplos

​
IBAN alemão válido

Pedido: 
GET https://bankvalidation.cleariflow.com/v1/iban/?api_key=YOUR_API_KEY&iban=DE89370400440532013000
Resposta: 
{
  "iban": "DE89370400440532013000",
  "is_valid": true,
  "country_code": "DE",
  "country_name": "Germany",
  "bank_code": "37040044",
  "account_number": "0532013000",
  "length": 22,
  "expected_length": 22,
  "checksum_valid": true,
  "format_valid": true,
  "details": {
    "structure": "BBBB BBBB BBBB BBBB BB",
    "example": "DE89 3704 0044 0532 0130 00",
    "bank_name": "Bank information not available",
    "bank_bic": "BIC not available",
    "account_type": "Bank Account",
    "currency": "EUR"
  }
}

​
IBAN francés válido

Pedido: 
GET https://bankvalidation.cleariflow.com/v1/iban/?api_key=YOUR_API_KEY&iban=FR1420041010050500013M02606
Resposta: 
{
  "iban": "FR1420041010050500013M02606",
  "is_valid": true,
  "country_code": "FR",
  "country_name": "France",
  "bank_code": "2004101005",
  "account_number": "0500013M02606",
  "length": 27,
  "expected_length": 27,
  "checksum_valid": true,
  "format_valid": true,
  "details": {
    "structure": "BBBB BSSS SSCC CCCC CCCC CCC KK",
    "example": "FR14 2004 1010 0505 0001 3M02 606",
    "bank_name": "Bank information not available",
    "bank_bic": "BIC not available",
    "account_type": "Bank Account",
    "currency": "EUR"
  }
}

​
IBAN inválido

Pedido: 
GET https://bankvalidation.cleariflow.com/v1/iban/?api_key=YOUR_API_KEY&iban=INVALID
Resposta: 
{
  "iban": "",
  "is_valid": false,
  "country_code": "",
  "country_name": "",
  "bank_code": "",
  "account_number": "",
  "length": 7,
  "expected_length": 0,
  "checksum_valid": false,
  "format_valid": false,
  "details": {
    "structure": "",
    "example": ""
  }
}

​
Tratamento de erros

​
Parâmetro IBAN em falta

Pedido: 
GET https://bankvalidation.cleariflow.com/v1/iban/?api_key=YOUR_API_KEY
Resposta: 
{
  "error": {
    "message": "Missing iban",
    "code": "missing_iban"
  }
}

​
Chave API em falta

Pedido: 
GET https://bankvalidation.cleariflow.com/v1/iban/?iban=DE89370400440532013000
Resposta: 
{
  "error": {
    "message": "API key is required",
    "code": "missing_api_key"
  }
}

​
Estrutura do IBAN

O IBAN consiste em vários componentes:
  1. Código de país (2 caracteres): código de país ISO 3166-1 alpha-2
  2. Dígitos de controlo (2 caracteres): validação mediante algoritmo MOD-97
  3. Identificador bancário: código bancário específico do país
  4. Número de conta: identificador da conta do cliente

​
Formatos específicos por país

Os diferentes países têm estruturas de IBAN variáveis:
  • Alemanha (DE): 22 caracteres - BBBB BBBB BBBB BBBB BB
  • França (FR): 27 caracteres - BBBB BSSS SSCC CCCC CCCC CCC KK
  • Itália (IT): 27 caracteres - CAAA AABB BBSS CCCC CCCC CCX
  • Reino Unido (GB): 22 caracteres - BBBB SSSS SSCC CCCC CC
  • Espanha (ES): 24 caracteres - BBBB SSSS DDCC CCCC CCCC CC
Onde:
  • B = Código bancário
  • S = Código de sucursal
  • C = Número de conta do cliente
  • K = Dígito de controlo/chave
  • A = Tipo de conta
  • D = Dígito de controlo

​
Regras de validação

A API realiza uma validação abrangente que inclui:
  1. Validação de formato: verifica se o IBAN segue a estrutura esperada para o país
  2. Validação de comprimento: verifica se o comprimento do IBAN coincide com o padrão do país
  3. Validação de dígito de controlo: realiza a validação mediante algoritmo MOD-97
  4. Validação do código de país: garante que o código de país é suportado
  5. Validação de caracteres: verifica que os caracteres alfanuméricos são válidos

​
Países suportados

A API suporta validação de IBAN para mais de 50 países, incluindo:
  • Europa: Alemanha, França, Itália, Espanha, Países Baixos, Bélgica, Áustria, Suíça, Reino Unido, Polónia
  • Ásia: EAU, Barém, Israel, Jordânia, Cazaquistão, Kuwait
  • Américas: Brasil, Costa Rica, República Dominicana, Guatemala
  • África: Mauritânia, Maurícia, Tunísia
Para uma lista completa de países suportados, consulte a página Países suportados.