UA
Цей API є частиною нашої послуги Комплект IBAN
Інструкція з інтеграції API
1. Що таке API розрахунку IBAN?
Розрахунок IBAN ( так звана Конверсія IBAN ) - це система програмного забезпечення, що дозволяє нашим клієнтам конвертувати внутрішні банківські коди та комбінації номерів облікових записів у перевірені Міжнародні номери банківських рахунків ( IBAN ).Система дозволяє нашим клієнтам користуватися ручним інтерфейсом, а також надає API для інтеграції у внутрішні системи компанії.
Система також ідентифікує банки та фінансові установи та надає деталі нашим клієнтам.
2. Особливості
Нижче наведені деякі з ключових особливостей нашого механізму розрахунку IBAN:- Перевірка контрольних сум місцевого банківського коду / номера рахунку ( * див. Країни, що підтримуються )
- Отримання інформації про банк на основі коду місцевого банку / відділення.
- Автоматичне генерування дійсного формату IBAN для наданого коду банку / відділення та номера рахунку
- Система підтримує декілька форматів відповіді ( JSON / XML )
3. Країни, що підтримуються
API Розрахунку IBAN на даний момент підтримується у наступних країнах, також ничже наведено обов'язкові поля нашого API для розрахунку IBAN.| Код країни | Назва країни | Код банку | Відділення | Обліковий запис | Контрольна цифра ** |
|---|---|---|---|---|---|
| AT | Австрія | ТАК | ТАК | ||
| BE | Бельгія | ТАК | ТАК | ТАК | |
| CH | Швейцарія | ТАК | ТАК | ||
| DE | Німеччина | ТАК | ТАК | ||
| EE | Естонія | ТАК | |||
| ES | Іспанія | ТАК | ТАК | ТАК | ТАК |
| FI | Фінляндія | ТАК | ТАК | ||
| FR | Франція | ТАК | ТАК | ТАК | ТАК |
| GB | Великобританія | ТАК | ТАК | ТАК | |
| HU | Угорщина | ТАК | ТАК | ||
| IE | Ірландія | ТАК | ТАК | ТАК | |
| IT | Італія | ТАК | ТАК | ТАК | ТАК |
| MC | Монако | ТАК | ТАК | ТАК | ТАК |
| MR | Мавританія | ТАК | ТАК | ТАК | |
| MT | Мальта | ТАК | ТАК | ||
| NO | Норвегія | ТАК | ТАК | ||
| PT | Португалія | ТАК | ТАК | ТАК | ТАК |
| SM | Сан-Марино | ТАК | ТАК | ТАК | |
| CZ | Чеська Республіка | ТАК | ТАК | ТАК | |
| AL | Албанія | ТАК | ТАК | ||
| SK | Словацька Республіка | ТАК | ТАК | ТАК | |
| SI | Словенія | ТАК | ТАК | ТАК | |
| PL | Польща | ТАК | ТАК | ТАК | |
| PK | Пакістан | ТАК | ТАК | ||
| SE | Швеція | ТАК | ТАК | ТАК | |
| NL | Нідерланди | ТАК | ТАК |
Перевірка контрольних цифр є додатковим шаром захисту інтегрування даних від помилок під час введення.
4. Вхідні дані API
API допускає як HTTP GET, так і POST запити для вхідних даних.Допустимі параметри наведені в таблиці нижче:
| Назва поля | Вид | Опис |
|---|---|---|
| api_key | Рядок | Ваш персональний API ключ. Одержується в клиєнтській зоні. |
| формат | Рядок | Формат відповіді API ( xml або json ) |
| країна | Рядок | 2-літерний код країни ( UK/US/DE/FR ) |
| код банку | Рядок | Унікальний ідентифікатор банку. Видрізняється для кожної країни. ( необов'язково ). Деякі країни вимагають лише номер рахунку. |
| відділення | Рядок | Унікальний локальний іденьифікатор відділення ( необов'язково ) |
| обліковий запис | Рядок | Персональний номер облікового запису |
| cd | Ціле число | Контрольні цифри використовуються в деяких країнах. |
| префікс | Ціле число | В даний час потрібно тільки для Чеської Республіки ( необов'язково ) |
API підтримує декілька форматів відповіді для забезпечення легшої інтеграції. На даний момент підтримуються формати XML та JSON.
Показник Країна повинен мати 2 літери ISO коду країни, таких як UK для Сполученого Королівства, DE для Німеччини, FR для Франції …
Код Банку відрізняється за довжиною та структурою для різних країн.
Код Відділення є необов'язковим агрументов та потрібен тільки в деяких країнах ( дивіться Приклади )
Номер облікового запису є необхідним для всіх країн і в деяких випадках це єдиний параметр, що використовується для підрахунку IBAN.
Контрольні Цифри є необхідними тільки для визначених країн, які включили такі алгоритми перевірки у свої внутрішні структури номерів банківськіх облікових записів. ( дивіться Приклади )
Префікс - це необов'язкове поле, необхідне тільки для розрахунку IBAN Чеської Республіки.
5. Приклади API
У наведеній нижче таблиці ви можете знайти приклади робочого запиту GET до нашого API для кожної країни.| Країна | Пріклад запиту (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. XML Структура Відповіді API
Детальний опис можливих полів, що виводяться, можна побачити в таблиці нижче:| Назва поля | Вид | Опис |
|---|---|---|
| адреса | Рядок | Адреса відділення банку або головного офісу |
| банк | Рядок | Назва банку або фінансової установи |
| bic | Рядок | BIC ( Bank Identifier Code ) банку |
| відділення | Рядок | Назва відділення, визначена за кодом банку |
| місто | Рядок | Назва міста, в якому розташовано відділення. |
| країна | Рядок | Абревіатура з двох літер, що позначає код країни, такі як US, UK, AU, FR … тощо. |
| Рядок | Закріплена контактна адреса електронної пошти для банку або відділення | |
| факс | Рядок | Номер факсу банку / відділення |
| телефон | Рядок | Контактний телефон банку / відділення |
| область | Рядок | Область адреси банку / відділення |
| вебсайт | Рядок | Адреса вебсайту банку / відділення |
| поштовий індекс | Рядок | ZIP або поштовий код адреси відділення банку |
Зразок XML-відповіді з API для коду SORT Великобританії та пошуку номера рахунку буде:
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>
Відповідь на той самий запит, якщо користувач вказав форматування JSON, буде:
"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. Помилки API
У разі помилки API розрахунку IBAN повертає відповідь XML або JSON, що містить повідомлення про помилку.Теги XML <error></error> повертаються без будь-яких інших полів у відповіді XML.
Нижче наведено опис усіх можливих повідомлень про помилки, які можуть бути виведені:
<error>Контрольна сума номеру рахунку недійсна.</error>
<error>Account Номер (контрольна сума) неправильний.</error>
<error>Account Номер має містити 11 символів</error>
<error>Account Номер має містити 14 символів</error>
<error>Account Номер має містити 24 символів</error>
<error>Account Номер недійсний</error>
<error>Account Номер коду сортування недійсний</error>
<error>Account Префікс числа занадто довгий.</error>
<error>Account Номер занадто довгий.</error>
<error>Код/KIB (контрольна сума) Банку/Відділення неправильна.</error>
<error>Код банку / Код відділення / Номер облікового запису занадто довгий.</error>
<error>Код банку / Код відділення (контрольна сума) неправильна.</error>
<error>Код банку не дійсний</error>
<error>Код банку занадто довгий.</error>
<error>Банк не знайдено</error>
<error>Банк не визнано</error>
<error>BBAN / NIB (контрольна сума) неправильний.</error>
<error>BLZ/Код банку не дійсний</error>
<error>Відділення/Агенціюя не знайдено</error>
<error>Код відділення занадто довгий.</error>
<error>Відділення не знайдено</error>
<error>Контрольна цифра занадто довга.</error>
<error>Кліринговий номер/Номер облікового запису не дійсний. Контрольная цифра неправильна.</error>
<error>Кліринговий номер/Код банку неможливо ідентифікувати. IBAN не може бути розраховано.</error>
<error>Кліринговий номер або Номер облікового запису занадто довгий.</error>
<error>Codice ABI della Banca/Код банку не дійсний</error>
<error>Codice CAB della Filiale/Код відділення не дійсний</error>
<error>Код країни не дійсний</error>
<error>Країна або банк не підтримується</error>
<error>IBAN не дійсний</error>
<error>Kontonummer/Номер облікового запису не дійсний</error>
<error>Відсутні поля</error>
<error>Не FR IBAN</error>
<error>Не FR IBAN країна</error>
<error>Обов'язкове поле відсутнє. Введіть код банку та номер рахунку</error>
<error>Обов'язкові поля не заповнені.</error>
<error>RIB не дійсний</error>
<error>Код Сортування / Код банку не може бути ідентифіковано. IBAN не може бути розрахований.</error>
<error>Код Сортування не знайдено</error>