IBAN aprēķināšanas API dokumentācija

Šī API veido daļu no mūsu pakalpojuma IBAN komplekts

API integrācijas pamācība

1. Kas ir IBAN aprēķināšanas API?

IBAN aprēķināšanas jeb IBAN konversijas dzinējs ir programmatūras sistēma, kas mūsu klientiem ļauj pārveidot vietējo banku kodu un kontu numuru kombinācijas validētos starptautiskajos banku kontu numuros (IBAN).

Sistēma mūsu klientiem nodrošina gan lietotāja saskarni, gan arī API, kas mūsu risinājumu ļauj integrēt klientu uzņēmumu iekšējās sistēmās.

Tāpat sistēma veic dotās bankas vai finanšu institūcijas identifikāciju un uzrāda šo informāciju klientam.

2. Raksturojums

Zemāk uzskaitītas dažas no galvenajām mūsu IBAN aprēķināšanas dzinēja funkcijām:

Vietējā bankas koda/konta numura kontrolsummu validācija (*skat. atbalstītās valstis)
Bankas informācijas izgūšana, balstoties uz vietējo bankas/filiāles kodu
Automātiska derīga IBAN formāta ģenerēšana dotajam bankas/filiāles kodam un konta numuram
Atbalsts vairākiem atbilžu formātiem (JSON/XML)

3. Atbalstītās valstis

IBAN aprēķināšanas API patlaban darbojas visās zemāk uzskaitītajās valstīs. Tabulā norādīti arī visi mūsu API ievadāmie lauki, kas nepieciešami IBAN aprēķināšanai.

Valsts kods	Valsts nosaukums	Bankas kods	Filiāle	Konts	Kontrolcipari **
AT	Austrija	JĀ		JĀ
BE	Beļģija	JĀ		JĀ	JĀ
CH	Šveice	JĀ		JĀ
DE	Vācija	JĀ		JĀ
EE	Igaunija			JĀ
ES	Spānija	JĀ	JĀ	JĀ	JĀ
FI	Somija			JĀ	JĀ
FR	Francija	JĀ	JĀ	JĀ	JĀ
GB	Lielbritānija	JĀ		JĀ	JĀ
HU	Ungārija			JĀ	JĀ
IE	Īrija	JĀ		JĀ	JĀ
IT	Itālija	JĀ	JĀ	JĀ	JĀ
MC	Monako	JĀ	JĀ	JĀ	JĀ
MR	Mauritānija	JĀ	JĀ	JĀ
MT	Malta	JĀ		JĀ
NĒ	Norvēģija			JĀ	JĀ
PT	Portugāle	JĀ	JĀ	JĀ	JĀ
SM	Sanmarīno	JĀ	JĀ	JĀ
CZ	Čehija	JĀ		JĀ	JĀ
AL	Albānija	JĀ		JĀ
SK	Slovākija	JĀ		JĀ	JĀ
SI	Slovēnija	JĀ		JĀ	JĀ
PL	Polija	JĀ		JĀ	JĀ
PK	Pakistāna	JĀ		JĀ
SE	Zviedrija	JĀ		JĀ	JĀ
NL	Nīderlande			JĀ	JĀ

Slejā "Kontrolcipari" norādīts, vai attiecīgā valsts atbalsta konta numura un/vai bankas koda kontrolciparu validāciju.

Kontrolciparu validācija ir papildu datu integritātes aizsardzības slānis pret drukas kļūdām.

4. API ievade

API pieņem gan HTTP GET, gan arī POST datu ievades pieprasījumus.
Zemāk redzamajā tabulā uzskaitīti iespējamie parametri:

Lauka nosaukums	Veids	Apraksts
api_key	Virkne	Jūsu personīgā API atslēga. To varat saņemt savā klienta zonā.
format	Virkne	API atbildes formāts (xml vai json).
country	Virkne	Divu burtu valsts kods (LV/UK/US/DE).
bankcode	Virkne	Unikāls bankas identifikators. Katrai valstij atšķirīgs; neobligāts. Dažām valstīm nepieciešams norādīt tikai konta numuru.
branch	Virkne	Unikāls vietējās filiāles identifikators (neobligāts).
account	Virkne	Personīgais konta numurs.
cd	Vesels skaitlis	Atsevišķās valstīs izmantotie kontrolcipari.
prefix	Vesels skaitlis	Patlaban nepieciešams tikai Čehijai (neobligāts).

Pirmais arguments ir API atslēga, t.i., unikāla virkne, kas palīdz mūsu sistēmai identificēt jūs kā lietotāju un atļaut piekļuvi API.

Lai nodrošinātu vienkāršāku integrāciju, API atbalsta vairākus atbilžu formātus. Patlaban tiek atbalstīti XML un JSON.

Valsts arguments sastāv no 2 burtu ISO valsts koda, piemēram, LV Latvijai, DE Vācijai, FR Francijai…
Bankas kodam katrā valstī ir atšķirīgs garums un struktūra.

Filiāles kods ir neobligāti norādāms arguments, kas nepieciešams tikai dažām valstīm (skat. piemērus).
Konta numurs jānorāda visām valstīm, un atsevišķos gadījumos tas ir vienīgais parametrs, kas tiek izmantots IBAN aprēķināšanai.

Kontrolcipari jānorāda tikai noteiktām valstīm, kuru vietējo banku kontu numuru struktūrā tiek izmantoti atbilstoši validācijas algoritmi (skat. piemērus).

Prefikss ir neobligāti aizpildāms lauks, kas nepieciešams tikai Čehijas IBAN aprēķināšanai.

5. API piemēri

Zemāk redzamajā tabulā apskatāms strādājošs GET vaicājuma piemērs darbam ar mūsu API katrai valstij.

Valsts	Vaicājuma piemērs (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
NĒ	?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 atbildes struktūra

Zemāk redzamajā tabulā detalizēti aprakstīti visi iespējamie API atbildes lauki:

Lauka nosaukums	Veids	Apraksts
address	Virkne	Bankas filiāles vai galvenās mītnes adrese
bank	Virkne	Bankas vai finanšu iestādes nosaukums
bic	Virkne	Bankas BIC (Bank Identifier Code)
branch	Virkne	Bankas kodam atbilstošās filiāles nosaukums
city	Virkne	Nosaukums pilsētai, kurā atrodas filiāle
country	Virkne	Divu burtu valsts koda saīsinājums, piem., LV, US, UK, FR … utt.
email	Virkne	E-pasta adrese saziņai ar banku vai filiāli
fax	Virkne	Bankas/filiāles faksa numurs
phone	Virkne	Bankas/filiāles kontakttālruņa numurs
state	Virkne	Bankas/filiāles štats
website	Virkne	Bankas/filiāles tīmekļa vietnes adrese
zip	Virkne	Bankas filiāles adreses pasta indekss

API sistēmas atbildi ir iespējams saņemt XML vai JSON formātā, kas ļauj to viegli analizēt dažādās programmēšanas valodās un platformās.

Zemāk sniegts XML atbildes piemērs no API Lielbritānijas SORT kodam un konta numura meklējumam:

Vaicājuma 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>

Ja lietotājs pieprasījis JSON formātu, uz to pašu vaicājumu tiktu saņemta šāda atbilde:

"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 kļūdas

Kļūdas gadījumā no IBAN aprēķināšanas API tiek saņemta XML vai JSON atbilde ar kļūdas paziņojumu.
XML tagi tiek saņemti bez jebkādiem citiem laukiem XML atbildē.
Zemāk atrodams apraksts visiem iespējamiem kļūdu paziņojumiem:

<error>Konta numurs (kontrolsumma) nav derīgs</error>
<error>Konta numurs (kontrolsumma) nav pareizs</error>
<error>Konta numuram jābūt 11 rakstzīmes garam</error>
<error>Konta numuram jābūt 14 rakstzīmes garam</error>
<error>Konta numuram jābūt 24 rakstzīmes garam</error>
<error>Konta numurs nav derīgs</error>
<error>Konta numurs vai Sort kods nav derīgs</error>
<error>Konta numura prefikss pārāk garš</error>
<error>Konta numurs pārāk garš</error>
<error>Bankas/filiāles kods/kontrolsumma nav pareiza</error>
<error>Bankas/filiāles kods/konta numurs pārāk garš</error>
<error>Bankas/filiāles kods/kontrolsumma nav pareiza</error>
<error>Bankas kods nav derīgs</error>
<error>Bankas kods pārāk garš</error>
<error>Banka nav atrasta</error>
<error>Banka nav atpazīta</error>
<error>BBAN/NIB (kontrolsumma) nav pareiza</error>
<error>BLZ/bankas kods nav derīgs</error>
<error>Filiāle/aģentūra nav atrasta</error>
<error>Filiāles kods pārāk garš</error>
<error>Filiāle nav atrasta</error>
<error>Kontrolskaitlis pārāk garš</error>
<error>Clearingnummer/konta numurs nav derīgs. Kontrolskaitlis nav pareizs</error>
<error>Clearingnummer/bankas kodu nav iespējams identificēt. Nevar aprēķināt IBAN</error>
<error>Clearingnummer vai konta numurs pārāk garš</error>
<error>Codice ABI della Banca/bankas kods nav derīgs</error>
<error>Codice CAB della Filiale/filiāles kods nav derīgs</error>
<error>Valsts kods nav derīgs</error>
<error>Valsts vai banka netiek atbalstīta</error>
<error>IBAN nav derīgs</error>
<error>Kontonummer/konta numurs nav derīgs</error>
<error>Trūkstoši lauki</error>
<error>IBAN nav FR IBAN</error>
<error>Valsts nav FR IBAN valsts</error>
<error>Nav aizpildīts obligātais lauks. Lūdzu, ievadiet bankas kodu un konta numuru</error>
<error>Obligātie lauki nav aizpildīti</error>
<error>RIB nav derīgs</error>
<error>Sort kodu/bankas kodu nevar identificēt. Nav iespējams aprēķināt IBAN</error>
<error>Sort kods nav atrasts</error>