Documentação da API de cálculo do IBAN

Esta API é parte do nossa Suíte IBAN

Guia de integração de API

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

O mecanismo IBAN Calculation (AKA IBAN Conversion) é um sistema de software que permite aos nossos clientes converter as combinações nacionais de códigos bancários e números de conta em Números de Conta Bancária Internacional (IBAN) validados.

O sistema permite a interface manual de nossos clientes, bem como uma API para permitir a integração nos sistemas internos da empresa.

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

2. Recursos

Abaixo estão alguns dos principais recursos do nosso mecanismo de cálculo do IBAN:

  • Validar as somas de verificação do código do banco local / número da conta (* consulte Países suportados)
  • Recuperar informações sobre o banco com base no código do banco / agência local.
  • Gera automaticamente um formato IBAN válido para o código do banco / agência fornecido e o número da conta
  • Sistema suporta formatação de múltiplas respostas (JSON / XML)


3. Países Suportados

A API de cálculo do IBAN atualmente suporta os seguintes países e os campos exigidos pela nossa API para calcular um IBAN.

Código do país Nome do país código do banco Agência Conta Dígito de verificação **
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  
NÃO Noruega     SIM SIM
PT Portugal SIM SIM SIM SIM
SM San Marino SIM SIM SIM  
CZ República Checa SIM   SIM SIM
AL Albânia SIM   SIM  
SK República Eslovaca SIM   SIM SIM
SI Eslovênia SIM   SIM SIM
PL Polônia SIM   SIM SIM
PK Paquistão SIM   SIM  
SE Suécia SIM   SIM SIM
NL Holanda SIM SIM
A coluna Dígito de verificação especifica se o país suporta o número da conta e / ou a validação do dígito de verificação do código do banco.

A validação de dígitos de verificação é uma camada extra de proteção de integridade de dados contra erros de digitação.

4. Entradas API

A API aceita solicitações HTTP GET e POST para dados de entrada.
Os parâmetros aceitos estão listados na tabela abaixo:

Nome do Campo Tipo Descrição
api_key String Sua chave de API pessoal. Obtido na área do cliente.
format String Formato de resposta da API (xml ou json)
país String Código do país de 2 letras (UK / US / DE / FR)
bankcode String Um identificador único de banco. Diferente para cada país. (opcional). Alguns países exigem apenas o número da conta.
Agência String Um identificador de agência local exclusivo (opcional)
conta String Número da conta pessoal
cd Integer Verifique os dígitos usados ​​em alguns países.
prefixo Integer Atualmente necessário somente para a República Tcheca (opcional)
O primeiro argumento é a chave da API, essa é uma string única que ajuda nosso sistema a identificá-lo como usuário e permitir o acesso à API.

A API suporta vários formatos de resposta para facilitar a integração. Atualmente, XML e JSON são suportados.

Os argumentos do país devem consistir de um código de país ISO de 2 letras, como Reino Unido para o Reino Unido, DE para a Alemanha, FR para a França…
O Código do Banco tem um tamanho e estrutura diferentes para cada país.

O Código de Filial é um argumento opcional é necessário apenas para alguns países (consulte Exemplos)
O número da conta é obrigatório para todos os países e, em alguns casos, é o único parâmetro usado para calcular um IBAN.

Os dígitos de verificação são necessários apenas para determinados países que incorporaram esses algoritmos de validação em sua estrutura interna de números de contas bancárias. (consulte os Exemplos)

O prefixo é um campo opcionalmente obrigatório apenas para o cálculo do IBAN da República Checa.

5. Exemplos de API

Na tabela abaixo, você pode encontrar o exemplo de consulta GET de trabalho para nossa API para cada país.

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

6. Estrutura de Resposta XML da API

Uma descrição detalhada dos campos possíveis retornados pode ser vista na tabela abaixo:

Nome do Campo Tipo Descrição
endereço String Endereço da agência bancária ou sede
banco String Nome do banco ou instituição financeira
bic String BIC (Código de identificação bancária) do banco
Agência String Nome da agência identificada pelo código do banco
cidade String O nome da cidade na qual a filial está localizada.
país String Abreviação de duas letras do código do país, por exemplo, EUA, Reino Unido, AU, FR, etc.
email String Endereço de e-mail de contato designado para o banco ou filial
fax String Número de fax do banco / agência
telefone String Telefone de contato do banco / agência
Estado String Estado do banco / endereço de filial
website String Endereço do site do banco / agência
cep String CEP ou código postal do endereço da agência bancária
O sistema da API retorna resultados em formato XML ou JSON, que é fácil de analisar em uma variedade de linguagens e plataformas de programação.

Uma amostra de resposta XML da API para uma pesquisa de código de conta e número de conta do Reino Unido seria:

URL de consulta:

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

<result>
<iban>GB20ULSB98006054100029</iban>
<account>54100029</account>
<sort_code>980060</sort_code>
<bank>ULSTER BANK LTD</bank>
<branch>BELFAST CITY OFFICE 1</branch>
<bic>ULSBGB2BXXX</bic>
<address>PO BOX 232 11-16 DONEGALL SQUARE EAST </address>
<city>BT1 5UB</city>
<country>GB<country/>
<phone>028 90244112</phone>
</result>

A resposta para a mesma consulta, se o usuário especificou um formato JSON, será:

"iban":"GB20ULSB98006054100029","account":"54100029","sort_code":"980060","bank":"ULSTER BANK LTD","branch":"BELFAST CITY OFFICE 1","bic":"ULSBGB2BXXX","address":"PO BOX 232 11-16 DONEGALL SQUARE EAST ","city":"BT1 5UB","country":"GB","phone":"028 90244112"

7. Erros da API

Em caso de erro, a API de cálculo do IBAN retorna uma resposta XML ou JSON contendo a mensagem de erro.
As tags <error></error> de XML são retornadas sem nenhum outro campo na resposta XML.
Abaixo você pode encontrar uma descrição de todas as mensagens de erro possíveis que podem ser retornadas:

<error>A soma de verificação do número da conta é inválida.</error>
<error>Número da conta (soma de verificação) não está correto.</error>
<error>O número da conta deve ter 11 caracteres</error>
<error>O número da conta deve ter 14 caracteres</error>
<error>O número da conta deve ter 24 caracteres</error>
<error>Número da conta não é válido</error>
<error>Número da conta do código de classificação não é válido</error>
<error>Prefixo de número de conta muito longo.</error>
<error>Número de conta muito longo.</error>
<error>Banco / Código de Filial / KIB (checksum) não está correto.</error>
<error>Código do banco / Código da filial / Número da conta muito longo.</error>
<error>Código do banco / código de ramificação (soma de verificação) não está correto.</error>
<error>Código bancário não válido</error>
<error>Código do banco por muito tempo.</error>
<error>Banco não encontrado</error>
<error>Banco não reconhecido</error>
<error>BBAN / NIB (soma de verificação) não está correto.</error>
<error>BLZ/Código bancário não válido</error>
<error>Agência não encontrada</error>
<error>Código de Agência muito longo.</error>
<error>Filial não encontrada</error>
<error>Dígito de verificação muito longo.</error>
<error>Clearingnummer/Número da conta não é válido. Dígito de verificação incorreto.</error>
<error>Clearingnummer / BankCode não pode ser identificado. IBAN não pode ser calculado.</error>
<error>Clearingnummer ou número de conta muito longo.</error>
<error>Codice ABI della Banca/Código bancário não válido</error>
<error>Codice CAB della Filiale/Código de Ramificação inválido</error>
<error>O código do país não é válido</error>
<error>País ou banco não suportado</error>
<error>IBAN não é válido</error>
<error>Kontonummer/Número da conta não é válido</error>
<error>Campos ausentes</error>
<error>Non FR IBAN</error>
<error>Non FR IBAN país</error>
<error>Campo obrigatório está faltando. Por favor insira o código do banco e o número da conta</error>
<error>Campos obrigatórios não enviados.</error>
<error>RIB não é válido</error>
<error>SortCode / BankCode não pode ser identificado. IBAN não pode ser calculado.</error>
<error>O código de classificação não pode ser encontrado</error>