Documentação da API de Cálculo de IBAN



Guia de integração da API


1. O que é a API de Cálculo IBAN?


O motor de Cálculo de IBAN (também conhecido por Conversão de IBAN) é um sistema de software que permite que os nossos clientes convertam o código do banco nacional e as combinações de números de conta nacionais em Números Internacionais de Contas Bancárias (IBAN) válidos.

O sistema permite que a interface manual dos nossos clientes, assim como uma API, integrem-se nos sistemas internos da sua empresa..

O sistema também identifica os bancos e instituições financeiras, e fornece dados aos nossos clientes.



2. Caraterísticas


Abaixo estão algumas das principais caraterísticas do nosso motor de Cálculo de IBAN:




3. Países Suportados


Atualmente a API de Cálculo de IBAN suporta os seguintes países e os seguintes campos de preenchimento obrigatório da nossa API para calcular um IBAN.

Código de País Nome de País Código de Banco Agência Conta Dígito de Controlo
AT Áustria SIM   SIM  
BE Bélgica SIM   SIM SIM
CH Suíça SIM   SIM  
DE Alemanha SIM   SIM  
EE Estónia     SIM  
ES Espanha SIM SIM SIM SIM
FI Finlândia     SIM SIM
FR França SIM SIM SIM SIM
GB Grã Bretanha SIM   SIM SIM
HU Hungria     SIM SIM
IE Irlanda SIM   SIM SIM
IT Itália SIM SIM SIM SIM
MC Mónaco SIM SIM SIM SIM
MR Mauritânia SIM SIM SIM  
MT Malta SIM   SIM  
NO Noruega     SIM SIM
PT Portugal SIM SIM SIM SIM
SE Suécia SIM   SIM  
SM São Marino SIM SIM SIM  
CZ República Checa SIM   SIM SIM
AL Albânia SIM   SIM  
SK Eslováquia SIM   SIM SIM
SI Eslovénia SIM   SIM SIM
PL Polónia SIM   SIM SIM
SE Suécia SIM   SIM SIM
NL Netherlandds SIM SIM
A coluna do Dígito de Controlo especifica se o país suporta a validação do do dígito de controlo número de conta e/ou código do banco.

A validação dos dígitos de controlo é uma camada de proteção adicional à integridade dos dados contra erros de digitação.



4. Entradas na API


A API aceita tanto pedidos HTTP GET e POST para dados de entrada.
Na tabela abaixo estão listados os parâmetros aceites:

Nome de Campo Tipo Descrição
api_key String A sua chave de API pessoal. Obtida na área de cliente.
formato String Formato de resposta de API ( xml ou json )
país String Código de país de 2 letras ( UK/US/DE/FR )
código_bancário String Um identificador de banco exclusivo. Diferente para cada país ( opcional ). Alguns países só requerem um número de conta.
agência String Um identificador exclusivo da agência local (opcional).
conta String Número de conta pessoal
cd Número Inteiro Dígitos de Controlo utilizados nalguns países.
prefixo Número Inteiro Atualmente só é necessário para a República Checa ( opcional )
O primeiro argumento é a chave API, esta é uma string exclusiva que ajuda o nosso sistema a identificá-lo como um utilizador, e permitir o acesso à API..

A API suporta múltiplos formatos de resposta, para proporcionar uma integração mais fácil. Atualmente, são suportados o XML e JSON.

Os Códigos de País devem consistir num código de país ISO de 2 letras tais como UK para Reino Unido, DE para a Alemanha, FR para a França ...
O Código do Banco tem um comprimento e estrutura diferentes para cada país.

O Código da Agência é um código opcional, e só é exigido para alguns países (ver exemplos).
O número de conta é necessário para todos os países, e nalguns casos, é o único parâmetro utilizado para calcular um IBAN.

Os dígitos de controlo são somente necessários para determinados países que incorporaram esses algoritmos de validação na sua estrutura de número de conta bancária nacional. (Ver Exemplos)

O prefixo é um campo opcionalmente necessário somente para o cálculo do IBAN na República Checa.



5. Exemplos de API


Na tabela abaixo pode encontrar o exemplo duma consulta GET à nossa API para cada país..

País Consulta exemplo (PEDIDO GET)
AT ?país=AT&format=json&código_de_banco=12000&conta=52700357958
BE ?país=BE&format=json&código_de_banco=250&conta=0135106&cd=70
CH ?país=CH&format=json&código_de_banco=0240&conta=240C08011570
DE ?país=DE&format=json&código_de_banco=BLZ37010050&conta=399509
EE ?país=EE&format=json&conta=55000005511439
ES ?país=ES&format=json&código_de_banco=0081&agência=1731&cd=91&conta=0006040912
FI ?país=FI&format=json&conta=52900261901092
FR ?país=FR&format=json&código_de_banco=30056&agência=00264&conta=02640016443
GB ?país=GB&format=json&código_sort=090127&conta=93496333
HU ?país=HU&format=json&conta=107000240416330551100005
IE ?país=IE&format=json&código_de_banco=905838&conta=71924374
IT ?país=IT&format=json&país=IT&código_de_banco=02008&agência=30545&conta=000103685854
MC ?país=MC&format=json&país=MC&código_de_banco=30002&agência=03260&conta=0000079112A
MR ?país=MR&format=json&código_de_banco=00012&agência=00001&conta=00000078326
MT ?país=MT&format=json&código_de_banco=07113&conta=199008240010
NO ?país=NO&format=json&conta=96803502045
PT ?país=PT&format=json&código_de_banco=0038&agência=0000&cd=81&conta=39551148771
SE ?país=SE&format=json&código_de_banco=9150&conta=0092395696
SM ?país=SM&format=json&país=SM&código_de_banco=03034&agência=09800&conta=000060164676
CZ ?país=CZ&format=json&prefixo=51&conta=1707230277&código_de_banco=0100
AL ?país=AL&format=json&código_de_banco=20511117&conta=374362CLPRCFEURC
SK ?país=SK&format=json&prefixo=&conta=4110053902&código_de_banco=3100
SI ?país=SI&format=json&código_de_banco=33000&conta=0000102423
PL ?país=PL&format=xml&código_de_banco=11402004&conta=0000360275244226
SE ?país=SE&format=json&código_de_banco=9300&conta=5913222524
NL ?country=NL&format=json&account=0006642318




6. Estrutura de Resposta XML da API


Na tabela abaixo pode ser visualizada uma descrição pormenorizada dos possíveis campos devolvidos:

Nome de Campo Tipo Descrição
morada String Morada da agência bancária ou sede
banco String Nome do banco ou da instituição financeira
bic String BIC (Bank Identifier Code) - Código de identificação do banco
agência String Nome da agência identificada pelo código bancário
cidade String O nome da cidade em que se situa a agência.
país String Abreviatura de 2 letras do código do país ex: US, UK, AU, FR … etc.
email String Endereço de email de contacto do banco ou da agência.
fax String Número de fax do banco/agência
telefone String Número de telefone de contacto do banco/agência
estado String Estado da morada do banco/agência
website String Endereço do website do banco/agência
código postal String Código postal ou ZIP da morada da agência bancária
O sistema da API devolve os resultados nos formatos XML ou JSON, que são fáceis de analisar em diversas linguagens de programação e plataformas.

Uma resposta XML exemplo da API para uma pesquisa dum código SORT, e Número de Conta do Reino Unido:

Consulta URL:

?api_key=9834hAHx78ba4g8habsdk&country=GB&format=json&bankcode=110377&account=10218962

<result>
<iban>GB20ULSB98006054100029</iban>
<conta>54100029</conta>
<código_sort>980060</código_sort>
<banco>ULSTER BANK LTD</banco>
<agência>ESCRITÓRIO 1 DA CIDADE DE BELFAST </agência>
<bic>ULSBGB2BXXX</bic>
<morada>CAIXA POSTAL 232 11-16 DONEGALL SQUARE EAST </morada>
<cidade>BT1 5UB</cidade>
<país>GB<país/>
<telefone>028 90244112</telefone>
</result>

A resposta para uma consulta igual, se o utilizador tiver especificado que desejava uma formatação JSON será:

"iban":"GB20ULSB98006054100029","conta":"54100029","código_sort":"980060","banco":"ULSTER BANK LTD","agência":"ESCRITÓRIO 1 DA CIDADE DE BELFAST ","bic":"ULSBGB2BXXX","morada":"CAIXA POSTAL 232 11-16 DONEGALL SQUARE EAST ","cidade":"BT1 5UB","país":"GB","telefone":"028 90244112"



7. Erros da API


No caso de ocorrer um erro, a API de Cálculo de IBAN entrega uma resposta XML ou JSON que contém a mensagem de erro.
Na resposta XML são devolvidas as tags XML <error></error> sem quaisquer outros campos.
Abaixo, pode encontrar uma descrição de todas as mensagens de erro possíveis que poderão ser devolvidas:

<error>A soma de controlo de Número de Conta não é válida.</error>
<error>O Número de Conta (soma de controlo) não está correto.</error>
<error>O Número de Conta tem que ter 11 caracteres.</error>
<error>O Número de Conta tem que ter 14 caracteres.</error>
<error>O Número de Conta tem que ter 24 caracteres.</error>
<error>O Número de Conta não é válido.</error>
<error>O Número de Conta do Código Sort não é válido.</error>
<error>O prefixo do Número de Conta é demasiado comprido.</error>
<error>O Número de Conta é demasiado comprido.</error>
<error>O Banco/Agência/Código KIB (soma de controlo) não está correto.</error>
<error>O Código de Banco/Agência/Código do Número de Conta é demasiado comprido.</error>
<error>O Código de Banco/Código de Agência (soma de controlo) não está correto.</error>
<error>O Código de Banco não é válido.</error>
<error> O Código de Banco é demasiado longo.</error>
<error>Banco Não Encontrado.</error>
<error>Banco Não Reconhecido</error>
<error>O BBAN/NIB (soma de controlo) não está correto.</error>
<error>O BLZ/Código de Banco não é válido.</error>
<error>O Ramo/Agência não foi encontrado.</error>
<error>O Código de Agência é demasiado comprido.</error>
<error>Agência Não Encontrada.</error>
<error>Dígito de Controlo demasiado comprido.</error>
<error> O Número de Compensação/Número de Conta não é válido. O dígito de controlo está incorreto.</error>
<error>Não é possível identificar o Número de Compensação/Número de Conta. Não é possível calcular o IBAN.</error>
<error>O Número de Compensação/Número de Conta é demasiado comprido.</error>
<error>O Codice ABI della Banca/Código de Banco não é válido</error>
<error>O Codice CAB della Filiale/Código de Agência não é válido.</error>
<error>O Código de País não é válido.</error>
<error>O País ou Banco Não é suportado.</error>
<error>O IBAN não é válido.</error>
<error>O Kontonummer/Número de Conta não é válido </error>
<error>Falta preencher campos</error>
<error>IBAN Não FR</error>
<error>País de IBAN Não FR</error>
<error>Falta preencher o campo obrigatório. Por favor, indique Código do Banco e o Número da Conta.</error>
<error>Os campos obrigatórios não foram submetidos..</error>
<error>O RIB não é válido</error>
<error>O Código Sort/Código de Banco não pode ser identificado. O IBAN não pode ser calculado.</error>
<error>Não foi possível encontrar o código Sort.</error>