Dokumentacja API Kalkulacja IBAN

Ten API jest częścią naszego Pakietu IBAN usług

Przewodnik integracji API

1. Czym jest API Kalkulacja IBAN?

Silnik Kalkulacji IBAN ( LUB Konwersji IBAN ) jest systemem oprogramowania umożliwiającym naszym klientom konwertować kod banku krajowego do zweryfikowanych międzynarodowych numerów kont bankowych ( IBAN ).

System oferuje naszym klientom interfejs ręczny oraz także API w celu integracji z własnym wewnętrznym systemem firmy.

The system also identifies the banks and financial institutions and provides the details to our customers. Ten system również identyfikuje banki i instytucje finansowe, zapewniając naszym klientom jak najbardziej szczegółowe informacje.

2. Funkcje

Poniżej pare głównych funkcji naszego silnika Kalkulacji IBAN:

  • Sprawdź kod banku lokalnego / sumy kontrolne konta bankowego ( * sprawdź Obsługiwane Kraje )
  • Uzyskaj informacje o banku bazując na kodzie banku lokalnego/oddziału.
  • Automatycznie generuje ważny format IBAN dla dostarczonego kodu banku/oddziału oraz numeru konta
  • System obsługuje wiele formatów odpowiedzi ( JSON / XML )


3. Obsługiwane Kraje

API Kalkulacja IBAN obecnie obsługuje następujące kraje i pola wymagane przez nasze API do wyliczenia IBAN.

Kod Kraju Nazwa Kraju Kod Banku Oddział Konto Cyfra Kontrolna **
AT Austria YES   YES  
BE Belgia YES   YES YES
CH Szwajcaria YES   YES  
DE Niemcy YES   YES  
EE Estonia     YES  
ES Hiszpania YES YES YES YES
FI Finlandia     YES YES
FR Francja YES YES YES YES
GB Wielka Brytania YES   YES YES
HU Węgry     YES YES
IE Irlandia YES   YES YES
IT Włochy YES YES YES YES
MC Monako YES YES YES YES
MR Mauretania YES YES YES  
MT Malta YES   YES  
NO Norwegia     YES YES
PT Portugalia YES YES YES YES
SM San Marino YES YES YES  
CZ Czechy YES   YES YES
AL Albania YES   YES  
SK Słowacja YES   YES YES
SI Słowenia YES   YES YES
PL Polska YES   YES YES
PK Pakistan YES   YES  
SE Szwecja YES   YES YES
NL Holandia YES YES
Kolumna z Cyfrą Kontrolną określa czy kraj obsługuje numer konta i/lub walidację cyfry kontrolnej kodu banku.

Walidacja cyfr kontrolnych jest dodatkową warstwą zabezpieczenia kontroli i spójności danych w celu zapobiegania popełniania błędów podczas wpisywania.

4. Dane Wejściowe API

API akceptuje zapytania zarówno HTTP GET jak i POST w celu wprowadzenia danych.
Akceptowane parametry są wymienione w poniższej tabeli:

Nazwa Pola Typ Opis
api_key Ciąg Znaków Twój prywatny klucz API. Uzyskany w obszarze programu klienta.
format Ciąg Znaków Format odpowiedzi API ( xml lub json )
country Ciąg Znaków 2 literowy kod kraju ( UK/US/DE/FR )
bankcode Ciąg Znaków Unikalny identyfikator banku. Inny dla każdego kraju. ( opcjonalne ). Niektóre kraje wymagają tylko numeru konta.
branch Ciąg Znaków Unikalany identyfikator lokalnego oddziału ( opcjonalnie )
account Ciąg Znaków Osobisty numer konta
cd Liczba całkowita Cyfry Kontrolne używane w niektórych krajach.
prefix Liczba całkowita Obecnie wymagane tylko w Czechach ( opcjonalnie )
Pierwszy argument to klucz API, który jest unikalnym ciągiem znaków pomagający naszemu systemowi zidentyfikować Cię jako użytkownika i umożliwić Ci dostęp do API.

API obsługuje wiele formatów odpowiedźi w celu zapewnienia łatwiejszej integralności. Obecnie obsługiwane są XML i JSON.

Argumenty Kraju muszą składać się z dwóch liter Kodu Kraju ISO, przykładowo UK dla Wielkiej Brytanii, DE dla Niemiec, FR dla Francji …
Kod Banku dla każdego kraju ma różną długość i strukturę.

Kod Oddziału jest argumentem opcjonalnym i jest wymagany tylko w niektórych krajach ( zobacz w Przykładach )
Numer konta jest wymagany dla wszystkich krajów i w niektórych przypadkach jest jedynym parametrem potrzebnym do wyliczenia numeru IBAN.

Cyfry Kontrolne są wymagane tylko w niektórych krajach które zawarły takie algorytmy walidacji do struktury numerów krajowych kont bankowych. ( zobacz w Przykładach )

Przedrostek jest polem opcjonalnie wymaganym tylko dla kalkulacji IBAN w Czechach.

5. Przykłady API

W poniższej tabeli możesz zsnaleźć przykład działającego zapytania GET przesłanego do naszej aplikacji API w zależności od danego kraju.

Kraj EPrzykłąd zapytania (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
NO ?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. Struktura Odpowiedzi API XML

Szczegółowy opis możliwych zwracanych pól można zobaczyć w tabeli poniżej:

Nazwa Pola Typ Opis
address Ciąg Znaków Adres oddziału lub siedziby głównej banku
bank Ciąg Znaków Nazwa banku lub instytucji finansowej
bic Ciąg Znaków BIC ( Bank Identifier Code / Kod Identyfikujący Banku)
branch Ciąg Znaków Nazwa zidentyfikowanego oddziału poprzez kod banku
city Ciąg Znaków Nazwa miasta w którym mieści się oddział.
country Ciąg Znaków Dwuliterowy skrót kodu kraju, np. USA, UK, AU, FR… itd.
email Ciąg Znaków Wyznaczony adres e-mail do kontaktu dla banku lub oddziału
fax Ciąg Znaków Numer faksu banku/oddziału
phone Ciąg Znaków Numer telefonu do kontaktu z bankiem / oddziałem
state Ciąg Znaków Stan adresu banku/oddziału
website Ciąg Znaków Adres Strony banku / oddziału
zip Ciąg Znaków Kod pocztowy adresu oddziału banku
System API zwraca wyniki w formacie XML lub JSON, które są łatwe do przetworzenia przez różne platformy i języki programowania.

Przykładowa odpowiedź XML z API dla wyszukania SORT Code i Numeru Konta z Wielkiej Brytanii będzie wyglądać następująco:

Zapytanie URL:

?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>

Odpowiedź dla tego samego zapytania w przypadku kiedy użytkownik wybierze formatowanie JSON będzie wyglądać następująco:

"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. Błędy API

W przypadku błędu, API Kalkulacji IBAN zwraca odpowiedź XML lub JSON zawierającą wiadomość dotycząca błędu.
Tagi XML <error></error> są zwracane bez żadnych dodatkowych pół w odpowiedźi XML.
Poniżej możesz znaleźć opis wszystkich możliwych odpowiedzi odnośnie błędów, które mogą być zwrócone:

<error>Suma kontrolna Numeru Konta jest nieprawidłowa.</error>
<error>Numer Konta (suma kontrolna) jest niewłaściwy.</error>
<error>Numer Konta musi mieć 11 znaków długości</error>
<error>Numer Konta musi mieć 14 znaków długości</error>
<error>Numer Konta musi mieć 24 znaki długości</error>
<error>Numer Konta jest niewłaściwy</error>
<error>Numer Konta lub Sort Code nie jest prawidłowy</error>
<error>Przyrostek Numeru Konta jest za długi.</error>
<error>Numer Konta jest za długi.</error>
<error>Bank/Kod Oddziału / KIB (suma kontrolna)jest nieprawidłowa.</error>
<error>Kod Banku/ Kod Oddziału/ Numer Konta jest za długi.</error>
<error>Kod Banku/ Kod Oddziału (suma kontrolna) jest nieprawidłowy.</error>
<error>Kod Banku jest niewłaściwy</error>
<error>Kod Banku jest za długi.</error>
<error>Bank Nieznaleziony</error>
<error>Bank Nierozpoznany</error>
<error>BBAN / NIB (suma kontrolna) jest nieprawidłowa.</error>
<error>BLZ/Kod Banku niewłaściwy</error>
<error>Oddział/Agencia nie znaleziony</error>
<error>Kod Oddziału jest za długi.</error>
<error>Oddział nie znaleziony</error>
<error>Cyfra Kontrolna jest za długa.</error>
<error>Clearingnummer/Numer Konta jest nieprawidłowy. Sprawdź nieprawidłową cyfrę.</error>
<error>Clearingnummer / Kod Banku nie może być zidentyfikowany. IBAN nie może być wyliczony.</error>
<error>Clearingnummer lub Numer Konta jest za długi.</error>
<error>Codice ABI della Banca/Kod Banku jest nieprawidłowy</error>
<error>Codice CAB della Filiale/Kod Oddziału jest nieprawidłowy</error>
<error>Kod kraju jest nieprawidłowy</error>
<error>Kraj lub Bank jest nieobsługiwany</error>
<error>IBAN jest niewłaściwy</error>
<error>Kontonummer/Numer Konta jest niewłaściwy</error>
<error>Brakujące pola</error>
<error>Non FR IBAN</error>
<error>Non FR IBAN country</error>
<error>Wymagane pole jest brakujące. Prosze podać Kod Banku i Numer Konta</error>
<error>Wymagane pola nie zostały przesłane.</error>
<error>RIB jest niewłaściwy</error>
<error>SortCode / KodBanku nie może być zidentyfikowany. IBAN nie może być wyliczony.</error>
<error>Sort code nie może być znaleziony</error>