RU
Данный API-интерфейс является частью услуги IBAN Suite
Руководство по интеграции API
1. Что представляет собой API для расчета IBAN?
Система расчета IBAN (перевод IBAN) позволяет трансформировать реквизиты банка для внутреннего рынка в международный формат IBAN.Наше решение позволяет интегрировать систему проверки прямо в ваше программное обеспечение, и использовать его для решения внутренних проблем и вопросов.
Кроме того, система позволяет выполнить проверку банков и финансовых учреждений, предоставляя подробную информацию для наших клиентов.
2. Основные функции
Ниже представлена информация об основных функция системы расчета IBAN:- Подтверждение местного БИК и номера счета (* см. список стран, в которых доступна данная услуга)
- Получние информации о банке на основе местного БИКа или кода отделения.
- Автоматический перевод информации в формат IBAN (БИК и номер счета)
- Система поддерживает несколько форматов предоставления данных ( JSON / XML )
3. Поддерживаемые страны
Система расчета IBAN работает в странах, указанных ниже. Кроме того, вы должны указать следующие данные для расчета IBAN.| Код страны | Наименование страны | Код банка | Отделение | Счет | Проверочное значение ** |
|---|---|---|---|---|---|
| AT | Австрия | Да | Да | ||
| BE | Бельгия | Да | Да | Да | |
| CH | Швейцария | Да | Да | ||
| DE | Германия | Да | Да | ||
| EE | Эстония | Да | |||
| ES | Испания | Да | Да | Да | Да |
| FI | Финляндия | Да | Да | ||
| FR | Франция | Да | Да | Да | Да |
| GB | Великобритания | Да | Да | Да | |
| HU | Венгрия | Да | Да | ||
| IE | Ирландия | Да | Да | Да | |
| IT | Италия | Да | Да | Да | Да |
| MC | Монако | Да | Да | Да | Да |
| MR | Мавритания | Да | Да | Да | |
| MT | Мальта | Да | Да | ||
| Нет | Норвегия | Да | Да | ||
| PT | Португалия | Да | Да | Да | Да |
| SM | Сан-Марино | Да | Да | Да | |
| CZ | Чехия | Да | Да | Да | |
| AL | Албания | Да | Да | ||
| SK | Словакия | Да | Да | Да | |
| SI | Словения | Да | Да | Да | |
| PL | Польша | Да | Да | Да | |
| PK | Пакистан | Да | Да | ||
| SE | Швеция | Да | Да | Да | |
| NL | Голландия | Да | Да |
Проверочные символы позволяют создать дополнительный уровень проверки правильности введенных данных.
4. Данные API
API-интерфейс принимает запросы HTTP GET и POST.Доступные параметры представлены в таблице ниже:
| Поле | Тип | Описание |
|---|---|---|
| api_key | Строка | Ваш личный API-ключ. Вы можете получить его в клиентском разделе. |
| format | Строка | Формат ответа API (xml или json ) |
| country | Строка | 2-значный код страны ( UK/US/DE/FR ) |
| bankcode | Строка | Уникальный номер банка. Отличается для каждой страны. (опциональное поле). Для некоторых стран достаточно указать только номер счета. |
| branch | Строка | Уникальный номер отделения (опционально) |
| account | Строка | Индивидуальный номер счета |
| cd | Целое число | Проверочные символы, которые используются в некоторых странах. |
| prefix | Целое число | В настоящее время используется только в Чехии (опционально) |
API-интерфейс поддерживает несколько форматов ответа, что гарантирует простую интеграци. В настоящее время мы поддерживаем XML и JSON.
Значение поля Country включает в себя двухзначный код страны: UK для Великобритании, DE для Германии, FR для Франции…
Поле Bank Code имеет разную длину для каждой страны.
Поле Branch Code является дополнительным, и используется только в некоторых странах (см. примеры)
Поле Account number является единственным параметром, который нужно указать в ряде стран для расчета IBAN.
Поле Check Digits требуется только для стран, в которых используется такая система проверки правильности введенных данных (см. примеры)
Поле Prefix в настоящее время используется только для расчета 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 |
| Нет | ?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. Структура ответа API XML
Ниже представлено подробное описание каждого из полей ответа API-интерфейса:| Поле | Тип | Описание |
|---|---|---|
| address | Строка | Адрес отделения или центрального офиса |
| bank | Строка | Наименование банка или финансовой организации |
| bic | Строка | BIC (БИК) банка |
| branch | Строка | Наименование отделения, соответствующее коду |
| city | Строка | Наименование города, в котором расположено отделение. |
| country | Строка | Двухзначное обозначение страны: US, UK, AU, FR и так далее. |
| Строка | Контактный электронный адрес банка или отделения | |
| fax | Строка | Номер факса банка или отделения |
| phone | Строка | Номер телефона банка или отделения |
| state | Строка | Страна банка или отделения |
| website | Строка | Сайт банка или отделения |
| zip | Строка | Индекс банка или отделения |
Ниже представлен пример XML-ответа для Великобритании. Необходимо указать следующие данные:
Ссылка запроса:
?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
При возникновении ошибки в расчете IBAN, система возвращает XML или JSON ответ с текстом ошибки.Ответ содержит в себе только код ошибки, и не содержит других полей XML.
Ниже представлен перечень возможных ошибок:
<error>Account Number checksum is invalid.</error>
<error>Account Number (checksum) is not correct.</error>
<error>Account Number has to be 11 characters long</error>
<error>Account Number has to be 14 characters long</error>
<error>Account Number has to be 24 characters long</error>
<error>Account Number is not valid</error>
<error>Account Number of Sort Code is not valid</error>
<error>Account Number prefix too long.</error>
<error>Account Number too long.</error>
<error>Bank/Branch Code / KIB (checksum) is not correct.</error>
<error>Bank Code/ Branch Code/ Account Number too long.</error>
<error>Bank Code/ Branch Code (checksum) is not correct.</error>
<error>Bank Code not valid</error>
<error>Bank Code too long.</error>
<error>Bank Not Found</error>
<error>Bank Not Recognized</error>
<error>BBAN / NIB (checksum) is not correct.</error>
<error>BLZ/Bank Code not valid</error>
<error>Branch/Agencia not found</error>
<error>Branch Code too long.</error>
<error>Branch not found</error>
<error>Check Digit too long.</error>
<error>Clearingnummer/Account Number is not valid. Check digit incorrect.</error>
<error>Clearingnummer / BankCode can not be identified. IBAN can not be calculated.</error>
<error>Clearingnummer or Account Number too long.</error>
<error>Codice ABI della Banca/Bank Code not valid</error>
<error>Codice CAB della Filiale/Branch Code not valid</error>
<error>Country code is not valid</error>
<error>Country or Bank not supported</error>
<error>IBAN is not valid</error>
<error>Kontonummer/Account Number is not valid</error>
<error>Missing fields</error>
<error>Non FR IBAN</error>
<error>Non FR IBAN country</error>
<error>Required field is missing. Please enter Bank Code and Account Number</error>
<error>Required fields not submitted.</error>
<error>RIB is not valid</error>
<error>SortCode / BankCode can not be identified. IBAN can not be calculated.</error>
<error>Sort code cannot be found</error>