Documentação da API de validação de IBAN

A API REST do IBAN-Test verifica a estrutura e os dígitos de controlo dos IBAN, devolve dados bancários e BIC disponíveis, valida BIC e contas bancárias alemãs e gera IBAN a partir de dados bancários. Autentique-se com o token API do painel de controlo e integre as respostas JSON em formulários, processos de pagamento e sistemas internos.

Experimentar a verificação de IBAN online · Utilizar o gerador de IBAN · Ligar o servidor MCP

Autenticação

Utilize o token da secção API overview como token Bearer no cabeçalho HTTP:

Authorization: Bearer YOUR_API_TOKEN

Após iniciar sessão, encontra o token em API overview. Se ainda não tem conta, crie uma chave API.

URL de base

https://www.iban-test.eu/api

Endpoints

• GET /v2/iban/validate?iban=... – validar um IBAN
• GET /v2/iban/validate/{iban} – validar um IBAN indicado no caminho do URL
• POST /v2/iban/validate – validar um IBAN enviado no corpo do pedido
• GET /v2/bic/validate/{bic} – validar um BIC
• GET /v2/bank-account/validate?bankcode=...&accountnumber=... – validar uma conta bancária alemã
• GET /v2/iban/generate?countrycode=...&bankcode=...&accountnumber=... – gerar um IBAN

O que verifica a validação de IBAN

• Código do país, sequência de caracteres e comprimento do IBAN definido para cada país
• Dígitos de controlo do IBAN verificados pelo cálculo internacional MOD-97
• Dados disponíveis nos diretórios bancários, como o nome do banco, a localidade e o BIC

Uma resposta válida confirma a coerência formal do IBAN. Não comprova que a conta existe, pertence a uma determinada pessoa, está ativa ou pode receber pagamentos.

Exemplos de pedidos

Validar um IBAN

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://www.iban-test.eu/api/v2/iban/validate?iban=DE89%203704%200044%200532%200130%2000"

São permitidos espaços nos IBAN; estes são removidos automaticamente antes da validação.

Validar um BIC

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://www.iban-test.eu/api/v2/bic/validate/COBADEFFXXX"

Validar uma conta bancária

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://www.iban-test.eu/api/v2/bank-account/validate?bankcode=37040044&accountnumber=532013000"

Gerar um IBAN

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://www.iban-test.eu/api/v2/iban/generate?countrycode=DE&bankcode=37040044&accountnumber=532013000"

Formato das respostas e tratamento de erros

Todos os endpoints devolvem JSON. Antes de aceitar ou guardar dados bancários, analise a resposta HTTP e os campos error, code, message e o campo opcional details.

{
  "error": false,
  "code": 2100,
  "message": "IBAN is valid",
  "details": {}
}

Consulte a referência OpenAPI para obter os parâmetros e esquemas de resposta atuais. Um IBAN com dígitos de controlo válidos não confirma a titularidade da conta.

{
  "details": {
    "sepa": {
      "sddCore": {
        "status": "confirmed",
        "reason": "matched"
      },
      "sddB2b": {
        "status": "confirmed",
        "reason": "matched"
      },
      "sct": {
        "status": "confirmed",
        "reason": "matched"
      },
      "sctInst": {
        "status": "confirmed",
        "reason": "matched"
      }
    }
  }
}

MCP para clientes de IA

Além da API REST, o IBAN-Test disponibiliza um servidor Model Context Protocol para validação de IBAN. O MCP disponibiliza as mesmas funções bancárias como ferramentas estruturadas para clientes e agentes de IA compatíveis.

https://www.iban-test.eu/mcp

Authorization: Bearer YOUR_API_TOKEN

Ferramentas MCP disponíveis

• validate_iban – valida um IBAN
• validate_iban_batch – valida vários IBAN; cada IBAN conta como um pedido API
• generate_test_iban – gera um IBAN a partir do código do país, do código bancário e do número de conta
• ibantest_bank_account_validate – valida um código bancário e um número de conta alemães
• ibantest_bic_validate – valida um BIC e devolve os dados bancários disponíveis
• get_usage_info – Mostra a utilização da API sem consumir um pedido de validação.

As chamadas às ferramentas funcionais MCP são contabilizadas no limite da API IBAN-Test, tal como os pedidos REST.

Validar uma exportação CSV

Se precisa de verificar uma lista de IBAN e guardar os resultados, consulte o guia de validação de CSV com Python. O exemplo preserva a ordem das linhas, evita pedidos repetidos para o mesmo IBAN e explica como lidar com quotas e erros.

Notas

• A API REST e o MCP utilizam tokens Bearer.
• A API anterior, baseada num código de autenticação, não é abrangida por esta documentação.
• Os pedidos funcionais são contabilizados no limite de utilização atual da API.