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

# POST /iban-validator

> Valide números IBAN e extraia metadados bancários incluindo país, dígitos verificadores e BBAN.

## Endpoint

```
POST https://api.bunny.build/api/v1/iban-validator
```

## Autenticação

| Header         | Obrigatório | Valor                        |
| -------------- | ----------- | ---------------------------- |
| `X-API-Key`    | Sim         | Sua chave de API (`bun_...`) |
| `Content-Type` | Sim         | `application/json`           |

## Visão geral

Valide Números de Conta Bancária Internacional (IBANs) conforme a especificação oficial de formato para todos os países participantes. Retorna metadados estruturais incluindo país, dígitos verificadores e o Número de Conta Bancária Básico (BBAN), para que você possa detectar entradas inválidas antes de iniciar uma transferência.

## Casos de uso

* Pré-validar IBANs antes de submeter transferências bancárias
* Extrair dados de país e roteamento bancário de IBANs informados pelo usuário
* Bloquear entradas de IBAN inválidas em formulários de pagamento em tempo real
* Verificações de conformidade para fluxos de pagamento internacionais

## Detalhes

Valida estrutura e dígitos verificadores para todos os países participantes do IBAN. A validade estrutural não garante que a conta exista; confirma apenas que o número está corretamente formado.

## Corpo da requisição

| Campo  | Tipo   | Obrigatório | Descrição                              |
| ------ | ------ | ----------- | -------------------------------------- |
| `iban` | string | Sim         | IBAN a validar (espaços são ignorados) |

### Exemplo

```json theme={null}
{
  "iban": "DE89370400440532013000"
}
```

## Resposta

### 200 OK

| Campo          | Tipo    | Descrição                          |
| -------------- | ------- | ---------------------------------- |
| `valid`        | boolean | Se o IBAN é estruturalmente válido |
| `iban`         | string  | IBAN normalizado (sem espaços)     |
| `country`      | string  | Código de país ISO                 |
| `check_digits` | string  | Os dois dígitos verificadores      |
| `bban`         | string  | Número de Conta Bancária Básico    |

**Exemplo**

```json theme={null}
{
  "valid": true,
  "iban": "DE89370400440532013000",
  "country": "DE",
  "check_digits": "89",
  "bban": "370400440532013000"
}
```

### 401 Unauthorized

```json theme={null}
{
  "detail": "Missing API key. Include X-API-Key header."
}
```

### 402 Payment Required

```json theme={null}
{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}
```

### 422 Unprocessable Entity

```json theme={null}
{
  "detail": "Invalid IBAN format or check digit mismatch"
}
```

### 429 Too Many Requests

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}
```

## Exemplo cURL

```bash theme={null}
curl -X POST https://api.bunny.build/api/v1/iban-validator \
  -H "X-API-Key: bun_sua_chave_api" \
  -H "Content-Type: application/json" \
  -d '{"iban": "DE89370400440532013000"}'
```