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



Especificação de integração da API


1. O que é a API de Validação de IBAN Reverso?


O IBAN Reverso é um sistema online, que disponibiliza às empresas uma interface online, onde podem realizar a validação e identificação em tempo real do IBAN.

Estas funções surgem na forma de módulos addon, que expandem a funcionalidade do seu portal.

O Número Internacional de Conta Bancária, ou IBAN, é uma forma normalizada de explicar um número de conta bancária, que funciona entre fronteiras..

A sua estrutura é:

<Código de País ISO de Duas Letras > + <Soma de Controlo de Dois Dígitos] + <BBAN/NIB>


BBAN é o termo utilizado para descrever o formato de nível nacional dum número de conta bancária, que varia entre os países (e, por vezes, foi criado somente para obter conectividade IBAN!).
Repare que um BBAN poderá ter o seu próprio algoritmo de soma de controlo.

O IBAN fornece proteção básica, utilizando a soma de controlo, contra erros de transcrição (ex: cópia humana). Ele também fornece um registo dos países de destino válidos, e dos seus formatos BBAN.
Assim, quando pede ao módulo da API do IBAN para 'validar' um IBAN, isto garante que passa nestas verificações.
No entanto, não pode garantir que uma conta bancária realmente existe - o único que pode efetuar isto é o banco ou país emissor.



2. Características


A API de Validação de IBAN Reverso permite que faça o seguinte:




3. Aplicação da API


O sistema API permite-lhe automatizar a validação do IBAN através dum simples pedido HTTP GET ou POST.
Os parâmetros aceites estão listados na tabela abaixo:

Nome do campo Extensão Tipo Descrição
IBAN Max 100 String O IBAN que deseja validar.
api_key 128 String A sua chave API pessoal.

*Para obter uma chave de API, por favor contacte-nos através de contact@iban.com ou

EXEMPLO - Validar um IBAN
Abaixo poderá encontrar um exemplo do uso da API de Validação de IBAN com um pedido GET:
https://api.iban.com/clients/api/iban-api.php?apikey=BAPI_KEY&iban=IBAN

Onde:

Assim que for efetuado um pedido HTTP GET ou POST com a chave API correta, o sistema irá fornecer os resultados num formato XML. Pode encontrar uma resposta XML exemplo na próxima seção “Estrutura de Resposta XML de API”



4. Estrutura de Resposta XML de API


Pode ser encontrado um esquema XML de resposta de API no arquivo de documentação.
Pode ser visualizado na tabela abaixo, uma descrição detalhada dos campos entregues:
Nome do Campo Extensão Tipo Descrição
IBAN Max 100 String É exibido o IBAN que submeteu.
NOME_DO_BANCO 256 String Código bancário que identifica o banco que tem esse IBAN
SEPA 5 String Indicador se este IBAN suporta pagamentos SEPA. Os valores devolvidos são Verdadeiro ou Falso
PAÍS 32 String Nome completo do país de origem, ex: “Estados Unidos”
CÓDIGO_DO_PAÍS 2 String Abreviatura de duas letras do código de país, ex: US, UK, AU, FR . etc.
CIDADE 128 String O nome da cidade de localização do banco’s emissor.
MORADA 128 String A morada do banco emissor.
SWIFT 128 String O código SWIFT do banco emissor.
VÁLIDO 5 String Resultado de verdadeiro/falso, dependendo de as somas de controlo IBAN estão corretas, ou não.

O sistema API dá resultados no formato XML, que é fácil de analisar em várias linguagens e plataformas de programação.

A exemplo duma resposta XML da API para uma validação de IBAN seria:

<result>
<iban>DE08500700100094201100</iban>
<nome_do_banco>DEUTSCHE BANK AG</nome_do_banco>
<paísy>ALEMANHA</país>
<código_de_país>DE</código_de_país>
<cidade>60262 FRANKFURT</cidade>
<morada>TAUNUSANLAGE 12</morada>
<swift>DEUTDEFFXXX</swift>
<sepa>VERDADEIRO</sepa>
<válido>VERDADEIRO</válido>
</result>



5. Erros da API


No caso de ocorrer um erro na API de IBAN ela dá uma resposta XML que contém a mensagem de erro.

As XML tags <error></error> são entregues sem quaisquer outros campos na resposta XML.

Abaixo, pode ver uma descrição de todas as mensagens de erro possíveis que podem ser dadas:

<error>Subscrição Expirada</error>
<error>Chave API Inválida</error>
<error>Não especificou qualquer IBAN</error>