IL
API זה הינו חלק משירות ה-IBAN Suite שלנו
מדריך אינטגרציית API
1. מהו ה-API לחישוב IBAN?
מנוע חישוב ה-IBAN (ידוע גם כהמרת IBAN) הינו מערכת תוכנה המאפשרת ללקוחותינו להמיר קוד בנק מקומי ומספר חשבון למספרי חשבון בנקאי בינלאומיים (INTERNATIONAL BANK ACCOUNT NUMBER - IBAN) מאומתים.המערכת מאפשרת ללקוחות שלנו שימוש בממשק ידני, וכן גם ב-API על-מנת לאפשר אינטגרציה עם מערכות החברה הפנימיות שלהם.
המערכת גם מזהה את הבנקים והמוסדות הפיננסיים ומספקת את הפרטים ללקוחותינו
2. מאפיינים
מטה מנויים חלק ממאפייני המפתח של מנוע חישוב ה-IBAN שלנו:- אימות CHECKSUMS קודי בנק \ ממספרי חשבון מקומיים ( * ראו מדינות שנתמכות)
- שליפת מידע אודות בנק על בסיס קוד בנק\סניף מקומי.
- ייצור אוטומטי של פורמט IBAN תקין עבור קוד הבנק\סניף ומספר החשבון שסופקו
- המערכת תומך בכמה פורמטי תשובה (JSON \ XML)
3. מדינות נתמכות
ה-API לחישוב IBAN כרגע תומך במדינות ובשדות הבאים הנדרשים לצורך חישוב IBAN על-ידי ה-API שלנו.| קוד מדינה | שם מדינה | קוד בנק | סניף | חשבון | סיפרת ביקורת ** |
|---|---|---|---|---|---|
| AT | אוסטריה | YES | YES | ||
| BE | בלגיה | YES | YES | YES | |
| CH | שוויץ | YES | YES | ||
| DE | גרמניה | YES | YES | ||
| EE | אסטוניה | YES | |||
| ES | ספרד | YES | YES | YES | YES |
| FI | פינלנד | YES | YES | ||
| FR | צרפת | YES | YES | YES | YES |
| GB | בריטניה | YES | YES | YES | |
| HU | הונגריה | YES | YES | ||
| IE | אירלנד | YES | YES | YES | |
| IT | איטליה | YES | YES | YES | YES |
| MC | מונאקו | YES | YES | YES | YES |
| MR | מאוריטניה | YES | YES | YES | |
| MT | מאלטה | YES | YES | ||
| NO | נורבגיה | YES | YES | ||
| PT | פורטוגל | YES | YES | YES | YES |
| SM | סאן מארינו | YES | YES | YES | |
| CZ | צכ'יה | YES | YES | YES | |
| AL | אלבניה | YES | YES | ||
| SK | הרפובליקה הסלובקית | YES | YES | YES | |
| SI | סלובניה | YES | YES | YES | |
| PL | פולין | YES | YES | YES | |
| PK | פקיסטן | YES | YES | ||
| SE | שוודיה | YES | YES | YES | |
| NL | הולנד | YES | YES |
אימות ספרת ביקורת הינה שכבה נוספת לשמירה על שלמות מידע מפני שגיאות הקלדה.
4. קלט API
ה-API מקבל פניות GET ו-POST של פרוטוקול HTTP עבור קלט מידע.הפרמטרים המקובלים מפורטים בטבלה מטה:
| שם שדה | סוג | תיאור |
|---|---|---|
| api_key | מחרוזת | מפתח ה-API האישי שלכם. ניתן למצוא באזור הלקוחות |
| format | מחרוזת | פורמט תשובת ה-API (ב-XML או JSON) |
| country | מחרוזת | 2 אותיות של קוד המדינה ( UK/US/DE/FR ) |
| bankcode | מחרוזת | מזהה בנקאי ייחודי. משתנה ממדינה למדינה. (אופציונלי - בחלק מהמדינות נדרש מספר חשבון בלבד). |
| branch | מחרוזת | מזהה ייחודי מקומי של של סניף (אופציאונלי) |
| account | מחרוזת | מספר חשבון אישי |
| cd | Integer | ספרות ביקורת המשומשות בחלק מהמדינות. |
| prefix | Integer | כרגע נדרש רק בצ'כיה (אופציאונלי) |
ה-API תומך באפשרות להחזיר תשובה בכמה פורמטים על-מנת להקל על האינטגרציה. כרגע, נתמכים הפורמטים XML ו-JSON.
נתון המדינה חייב להכיל את 2 התווים של קוד המדינה לפי ISO, כגון UK עבור בריטניה, DE עבור גרמניה, FR עבור צרפת וכו'...
קוד בנק הינו בעל אורך ומבנה שונה עבור כל מדינה.
קוד סניף הינו נתון אופציונלי שנדרש רק במדינות מסויימות (ראו דוגמאות)
מספר חשבון הינו נתון חובה בכל המדינות. בחלק מהמקרים, זהו הפרמטר היחיד לחישוב של 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. מבנה ה-XML של תשובת ה-API
תאור מפורט של כל השדות האפשריים שיכולים להיכלל בתשובה מופיע בטבלה מטה:| שם שדה | סוג | תיאור |
|---|---|---|
| address | מחרוזת | כתובת סניף הבנק או המוסד |
| bank | מחרוזת | שם הבנק או המוסד הפיננסי |
| bic | מחרוזת | BIC של הבנק\המוסד |
| branch | מחרוזת | שם הסניף לפי הקוד הבנקאי |
| city | מחרוזת | שם העיר שבה נמצא הסניף |
| country | מחרוזת | שתי אותיות המייצגות את קוד המדינה, דוגמת US, UK, AU, FR, וכדומה. |
| מחרוזת | כתובת הדואר האלקרטרוני ליצירת קשר שפרסם הסניף | |
| fax | מחרוזת | מספר הפקס של הבנק\הסניף |
| phone | מחרוזת | מספר הטלפון של הבנק\הסניף |
| state | מחרוזת | מדינה\מחוז בו נמצא הבנק\הסניף |
| website | מחרוזת | כתובת האתר של הבנק\הסניף |
| zip | מחרוזת | מיקוד של כתובת סניף הבנק |
כך, לדוגמה, תיראה תשובת ה-API בפורמט XML עבור חיפוש לפי קוד 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>מספר החשבון (CHECKSUM) אינו תקין.</error>
<error>מספר חשבון חייב להיות באורך של 11 תווים.</error>
<error>מספר חשבון חייב להיות באורך של 14 תווים.g</error>
<error>מספר חשבון חייב להיות באורך של 24 תווים.</error>
<error>מספר חשבון לא תקין.</error>
<error>מספר חשבון או קוד SORT אינו תקין</error>
<error>קידומת מספר חשבון ארוכה מדי.</error>
<error>מספר חשבון ארוך מדי</error>
<error>קוד בנק\סניף\KIB (CHECKSUM) אינו תקין.</error>
<error>קוד בנק\קוד סניף\מספר חשבון ארון מדי.</error>
<error>קוד בנק \ קוד סניף (CHECKSUM) אינו תקין.</error>
<error>קוד בנק אינו תקין.</error>
<error>קוד בנק ארוף מדי.</error>
<error>בנק לא נמצא.</error>
<error>בנק לא מזוהה.</error>
<error>קוד BBAN\NIB (CHECKSUM) אינו תקין..</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>קוד IBAN של מדינה שאינה FR.</error>
<error>שדה חובה לא מולא. אנא הזינו קוד בנק וקוד חשבון.</error>
<error>שדות חובה לא נשלחו.</error>
<error>קוד RIB אינו תקין.</error>
<error>קוד סידורי \ קוד בנק לא זוהה. לא ניתן לחשב IBAN..</error>
<error>לא ניתן לאתר קוד סידורי.</error>