> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Validação IBAN

> O endpoint `iban` valida International Bank Account Numbers com verificação abrangente específica por país, controlo de formato e informações estruturais detalhadas para aplicações financeiras.

## 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:

<ResponseExample>
  ```json theme={"system"}
  {
    "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"
    }
  }
  ```
</ResponseExample>

### Parâmetros de pedido

<ParamField query="api_key" type="String" required>
  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.
</ParamField>

<ParamField query="iban" type="String" required>
  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.
</ParamField>

### Parâmetros de resposta

A resposta da API é devolvida num [formato JSON](https://www.json.org/json-en.html) universal e leve.

<ResponseField name="iban" type="String">
  O IBAN normalizado sem espaços, devolvido em maiúsculas.
</ResponseField>

<ResponseField name="is_valid" type="Boolean">
  Resultado geral da validação que indica se o IBAN é válido de acordo com todas as regras de validação.
</ResponseField>

<ResponseField name="country_code" type="String">
  O código de país ISO de duas letras (p. ex., DE para Alemanha, FR para França).
</ResponseField>

<ResponseField name="country_name" type="String">
  O nome completo do país associado ao IBAN.
</ResponseField>

<ResponseField name="bank_code" type="String">
  O código identificador bancário extraído do IBAN conforme o formato específico do país.
</ResponseField>

<ResponseField name="account_number" type="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.
</ResponseField>

<ResponseField name="length" type="Integer">
  O comprimento real do IBAN fornecido.
</ResponseField>

<ResponseField name="expected_length" type="Integer">
  O comprimento esperado para IBAN do país específico segundo o padrão ISO 13616.
</ResponseField>

<ResponseField name="checksum_valid" type="Boolean">
  Se a validação do dígito de controlo do IBAN passou utilizando o algoritmo MOD-97.
</ResponseField>

<ResponseField name="format_valid" type="Boolean">
  Se o formato do IBAN coincide com a estrutura esperada para o país.
</ResponseField>

<ResponseField name="details" type="Object">
  Informação detalhada adicional sobre a estrutura e o formato do IBAN.
</ResponseField>

<ResponseField name="details.structure" type="String">
  Uma representação visual da estrutura do IBAN usando marcadores B (Banco), S (Sort), C (Cliente) e K (Chave).
</ResponseField>

<ResponseField name="details.example" type="String">
  Um exemplo corretamente formatado do IBAN com espaços para facilitar a leitura.
</ResponseField>

<ResponseField name="details.bank_name" type="String">
  O nome do banco (atualmente mostra "Bank information not available").
</ResponseField>

<ResponseField name="details.bank_bic" type="String">
  O código BIC do banco (atualmente mostra "BIC not available").
</ResponseField>

<ResponseField name="details.account_type" type="String">
  O tipo de conta (normalmente "Bank Account").
</ResponseField>

<ResponseField name="details.currency" type="String">
  O código de moeda do país (p. ex., EUR para países da zona euro, GBP para Reino Unido).
</ResponseField>

## Exemplos

### IBAN alemão válido

**Pedido:**

```
GET https://bankvalidation.cleariflow.com/v1/iban/?api_key=YOUR_API_KEY&iban=DE89370400440532013000
```

**Resposta:**

```json theme={"system"}
{
  "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:**

```json theme={"system"}
{
  "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:**

```json theme={"system"}
{
  "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:**

```json theme={"system"}
{
  "error": {
    "message": "Missing iban",
    "code": "missing_iban"
  }
}
```

### Chave API em falta

**Pedido:**

```
GET https://bankvalidation.cleariflow.com/v1/iban/?iban=DE89370400440532013000
```

**Resposta:**

```json theme={"system"}
{
  "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](/bank-validation/countries).