IBAN Калкулиране API Документация

Този приложно-програмен интерфейс (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 ключът, той е уникална редица от символи, благодарение на която системата ни идентифицира потребителя и му дава достъп до API.

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 … и т.н.
email String Уговорен имейл адрес за връзка с банката или клона
fax String Номер на факс на банката / клона
phone String Телефон за връзка с банката / клона
state String Адреса на банката / клона
website String Интернет страница на банката / клона
zip String Пощенски код на адреса на банковия клон
API системата връща резултати в XML или JSON формат, който е лесно да се анализира в различни програмни езици и платформи.

Примерен 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>