PT
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 | |||
| EG | Egypt | YES | YES | YES | |
| 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 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) |
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. |
| 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 |
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>