PL
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 |
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 ) |
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. |
| 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 |
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>