BG
Този приложно-програмен интерфейс (API) е част от нашите IBAN Suite услуги
Ръководство за употреба на API
1. Какво е API за IBAN Калкулиране?
IBAN калкулирането (също IBAN конвертиране) е софтуерна система, която позволява на нашите клиенти да конвертират кодове и банкови номера на местни банки в проверени международни номера на банкови сметки (IBAN).Системата предоставя на клиентите ни потребителски интерфейс, както и API, който позволява интеграция с вътрешните системи на компанията.
Системата също така идентифицира банките и финансовите институции, като предоставя информация за тях на нашите клиенти.
2. Характеристики
Долу са изложени някои ключови характеристики на нашата система за калкулиране на IBAN:- Проверява местния банков код/ номер на сметка ( * виж държавите, които поддържаме ).
- Извлича информация за банката въз основа на местния банков / филиалeн код.
- Автоматично генерира валиден 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 | String | Вашият личен API ключ. Намира се в клиентската зона. |
| format | String | Формат на API отговора ( xml или json ) |
| country | String | двубуквен код на държавата ( UK/US/DE/FR ) |
| bankcode | String | Уникален банков идентификатор. Различен за всяка държава. (по избор). За някои държави се изисква само номер на сметка. |
| branch | String | Уникален идентификатор на местния клон (по избор) |
| account | String | Личен номер на сметка |
| cd | Integer | Проверка на цифрите, използвани в някои държави. |
| prefix | Integer | Засега се изисква само за Чехия(по избор) |
API поддържа множество формати за отговор, с цел по-достъпна употреба. В момента се поддържат XML и JSON.
Поле Държава трябва да съдържа двубуквен ISO код на държавата като например UK за Обединеното кралство, DE за Германия, FR за Франция и т.н.
Банковият код на всяка държава има различна дължина и структура.
Кодът на клона е избираемо поле, задължителен e само за някои държави (вижте Примери).
Номерът на сметката е задължителен за всяка държава и в някои случаи е единственият параметър, използван за калкулация на IBAN.
Проверка на цифрите се изисква само за определени държави, които използват такива алгоритми за валидиране във вътрешните си струкури на банкови сметки.(вижте Примери)
Префиксът е поле по избор само за калкулацията на IBAN в Чехия.
5. API Примери
В таблицата по-долу можете да намерите примери за работа на GET заявка към нашия API за всяка държава.| Държава | Примерна заявка (GET заявка) |
|---|---|
| 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. API XML структура на отговорите
Подробно описание на възможните полета може да се види в таблицата по-долу:| Име на полето | Тип | Описание |
|---|---|---|
| address | String | Адрес на клона или централата на банката |
| bank | String | Име на банката или финансовата институция |
| bic | String | BIC ( Банков идентификационен код) на банката |
| branch | String | Име на клона, идентифициран с банковия код |
| city | String | Името на града, в който се намира клонът. |
| country | String | Двубуквено съкращение на кода на страната напр. US, UK, AU, FR … и т.н. |
| String | Уговорен имейл адрес за връзка с банката или клона | |
| fax | String | Номер на факс на банката / клона |
| phone | String | Телефон за връзка с банката / клона |
| state | String | Адреса на банката / клона |
| website | String | Интернет страница на банката / клона |
| zip | String | Пощенски код на адреса на банковия клон |
Примерен 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> Номерът на сметката (контролната сума) не е верен.</error>
<error>Номерът на сметката трябва да е с дължина 11 знака</error>
<error>Номерът на сметката трябва да е с дължина 14 знака</error>
<error>Номерът на сметката трябва да е с дължина 24 знака</error>
<error>Номерът е невалиден</error>
<error>Номерът на сорт кода е невалиден</error>
<error>Префиксният номер на сметката е твърде дълъг.</error>
<error>Номерът на сметката е твърде дълъг.</error>
<error>Банковият код / Кодът на клона / контролна сума не е верен.</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>Банковият код е невалиден</error>
<error>Кодът на клона е невалиден</error>
<error>Кодът на държавата е невалиден</error>
<error>Тази държава или банка не се поддържа</error>
<error>Невалиден IBAN</error>
<error>Невалидна банкова сметка</error>
<error>Липсват полета</error>
<error>IBAN не е FR.</error>
<error>Държавата не е с FR IBAN. </error>
<error>Липсва задължително поле. Моля, въведете банков код и номер на сметка.</error>
<error>Задължителните полета не са попълнени.</error>
<error>RIB е невалиден.</error>
<error>Сорт кодът / Банковият код не може да бъде идентифициран. IBAN не може да бъде калкулиран.</error>
<error>Сорт кодът не може да бъде намерен.</error>