API לאימות קודי BIC \ SWIFT

איך לבצע אינטגרציה של ה-API לאימות BIC בתוכנה שלכם

1. מהו ה-API לאימות BIC?

בעת עיבוד העברות בנקאיות ועסקאות בהן מעורב IBAN, שימוש בקוד SWIFT \ BIC נכון הינו הכרחי להצלחת ההעברה או העסקה
חברתנו קיבלה רישיון גישה לארכיון ה-BIC הרשמי מאת SWIFT SCRL, על מנת שנוכל לספק פיתרון יעיל ופשות לאימות BIC באופן אוטומטי. שירות זה יאפשר לכם לבצע אינטגרציה של מנגנון החיפוש בארכיון ה-BIC בתוכנה שלכם לצורך שימוש פנימי

ה-API לאימות BIC מכיל בפנים מידע SWIFTREF. השימוש במידע BIC הינו באישור SWIFT SCRL. כל הזכוניו על בסיס הנתונים שמור לשימוש עתידיות 2019

2. מאפיינים

מאפייני מפתח של ה-API

  • שליפת מידע אודות הבנק לפי BIC.
  • חיפוש בארכיון ה-BIC לפי שם חלקי של הבנק ומדינה
  • חיפוש בארכיון עבור רשומות היסטוריות
  • API RESPONSE מלא ופשוט יותר עבור אינטגרציה קלה יותר.


3. שימוש ב-API

ה-API לאימות BIC הינו מבוסס REST ותומר בבקשות GET ו-POST פשוטות עפ"י פרוטוקול HTTP.

הפרמטרים המקובלים מפורטים בטבלה מטה:

שם שדה אורך סוג תיאור
BIC 11 מחרוזת קוד SWIFT \ BIC לחיפוש. יכול להיות באורך של 8 או 11 תווים
bank_name 256 מחרוזת שם של בנק, או חלק ממנו, על-פיו יבוצע החיפוש בארכיון.
country 2 מחרוזת שתי אותיות של קוד מדינה. חובה בעת חיפוש בנק לפי שם.
api_key 128 מחרוזת מפתח ה-API האישי שלך.
format 4 מחרוזת Required to specify the format of the returned data. Currently supported values: json, xml
limit מספר שלם אופציונלי: ניתן להשתמש בשדה זה על-מנת להגבילאת כמות התוצאות בעת חיפוש בנק לפי שם.
hist מספר שלם אופציונלי: ניתן להשתמש בשדה זה להצגת רשומות היסטוריות מבסיס הנתונים עבור חיפושי בנקים או BIC.
בפורטל המקוון שלכם, תוכלו למצוא את מפתח ה-API שלכם, וכן את ה-URL שמשמש כ-REQUEST ENDPOINT לצורך אבטחת פניות החיפוש.


4. מבנה XML של תשובת ה-API

באפשרותכם להוריד סכימת XSD של תשובת ה-API.
תיאור מפורט של השדות שחוזרים מופיע בטבפלה מטה

שם שדה סוג אורך תמיד קיים תיאור
MODIFICATION FLAG אלפביתי 1 כן בקבצי דלתא:
• A (תוספת)
• M (שינוי)
• D (מחיקה) בקבצים מלאים:
• A (תוספת)
CHANGED FIELD מספרי 186 לא רושם את השדה (או התג) ששונה כתוצאה משינוי רשומה או כתוצאה מאירוע חדש.
טור אחד או יותר מיוצגים כסדרת מספרים, כאשר כל מספר מייצג את הטור ששונה ברשומה הקודמת או האירוע הקודם.
דוגמה "6,7,8,9"
זה אומר שהשדות EVENT TYPE, EVENT DATE, BIC8, BRANCH BIC
שונו.
השדות הבאם לא נרשמים בשדה CHANGED FIELD:
• RECORD KEY
• CHANGED FIELD
• MODIFICATION FLAG
RECORD KEY אלפאנומרי 12 כן המפתח הייחודי של הרשומה בקובץ
כל רשומה מייצגת אירוע במחזור ה-BIC.
ערך זה לא משתנה לאחר שהוקצה
PREVIOUS RECORD KEY אלפאנומרי 12 לא ה-RECORD KEY של אירוע המקושר הקודם
כל האירועים הקשורים הינם מקושרים וניתנים לאיתור באמצעות המידע הנ"ל
NEXT RECORD KEY אלפאנומרי 12 לא ה-RECORD KEY של אירוע המקושר הבא
כל האירועים הקשורים הינם מקושרים וניתנים לאיתור באמצעות המידע הנ"ל
EVENT TYPE אלפביתי 32 כן תיאור האירוע או השינוי שקשור ב-BIC שנעשה בעבר, בהווה, או שיעשה בעתיד.
סוגי אירועים:
• BIC ISSUED
• BIC EXPIRED
• BIC ACTIVATED ON FIN
• BIC ACTIVATED ON FA
• BIC ACTIVATED ON IA
• BIC DEACTIVATED ON FIN
• BIC DEACTIVATED ON FA
• BIC DEACTIVATED ON IA
• BIC DEACTIVATED
• BIC SUSPENDED
• BIC REACTIVATED
• BIC PUBLISHED
• BIC LEGAL NAME CHANGED
• BIC INSTITUTION NAME CHANGED
• BIC ADDRESS CHANGED
• FIN SERVICE CODE CHANGED
תאריך העדכון האחרון הוא השורה האחרונה ברצץ ה-BIC (כלומר, הרשומה האחרונה ביותר).
כשאירוע חדש נוסף, העמודות MODIFICATION FLAG ו-CHANGED FIELD
יעודכנו באירוע המקושר החארון ביותר.
EVENT DATE אלפאנומרי 8 כן תאריך האירוע
BIC8 אלפאנומרי 8 כן BIC (מוסד, מדינה, וסיומת) שבו:
• תחילית מוסד (4 תווים)
• קוד מדינה (2 תווים)
• סיומת מוסד (2 תווים)
BRANCH BIC אלפאנומרי 3 כן מזהה ה-BIC של הסניף המקושר ל-BIC בן 8 תווים. אם לא קיים מזהה סניף, יופיע הכיתוב XXX.
BIC אלפאנומרי 11 כן ה-BIC המלא: 8 תווים ומזהה סניף
RECORD STATUS אלפביתי 1 כן מייצג את סטטוס הרשומה
• [C] = מצב נוכחי, מייצג את האירוע האחרון בשרשרת עד תאריך הפרסום, מלבד אירועים עתידיים [F].
• [H] = רשומות הסטוריות בשרשרת האירועים
• [F] = אירועים עתידיים שייקרו לאחר תאריך פרסום הארכיון. האירועים הנוכחיים הקיימים [C] יהיו עדכניים עד להגעת התאריך של האירוע העתידי [F].
עבור אירועים עתידיים, התאריך מייצג את התאריך שהחל ממנו השינוי יהיה אקטואלי.
OPERATIONALLY ACTIVE RECORD אלפביתי 1 כן קיימות מספר רשומות עבור אותו BIC. שדה זה מציג אילו מהרשומות עבור אותו BIC הינו פעיל ובו יש להשתמש.
• [Y] רשומה פעילה
• [N] רשומה לא פעילה
עבור כל BIC ייחודי, תתכן רק רשומה אחת פעילה [Y].
רשומות עם סטטוס היסטורי [H] תמיד יוצגו כ-[N].
רשומות נוכחיות [C] עשויות להיות מיוצגות כ-[Y] או [N].
רשומות עתידיות [F] תמיד יוצגו כ-[N].
SUBTYPE INDICATOR כל סוג 4 כן סוג העסק של היישות. אינדיקטור תת-סוס מסופק רק לרשומות עם BIC.
SWIFT FIN אלפביתי 1 כן מצב חיבור יישות ל-FIN:
• [Y] מחובר ל-FIN
• [N] לא מחובר
SWIFT FA אלפביתי 1 כן נגישות היישות דרך FILEACT:
• [Y] מחובר ל-FILEACT
• [N] לא מחובר
SWIFT IA Alpha 1 כן נגישות היישות דרך INTERACT:
• [Y] מחובר ל-INTERACT
• [N] לא מחובר
LEGAL NAME כל תו 105 לא שם חוקי של המוסד
INSTITUTION NAME כל תו 105 כן שם מסחרי של המוסד (שם שפורסם)
INSTITUTION TYPE אלפביתי 12 כן ארגון העוסק בהעברות פיננסיות ו\או שירותים פיננסיים משלימים
סוגי מוסדות
• פיננסי
• לא פיננסי
ENTITY TYPE אלפביתי 16 כן סוג היישות הפיננסית:
• יישות משפטית
• סניף
• תפעולית
RE STREET ADDRESS 1 כל תו 35 לא [רישום] שם רחוב
RE STREET ADDRESS 2 כל תו 35 לא [רישום] מספר רחוב
RE STREET ADDRESS 3 כל תו 35 לא [רישום] מספר בניין, שם בניין, קומה
RE STREET ADDRESS 4 כל תו 35 לא [רישום] אזור
RE CITY כל תו 35 לא [רישום] עיר המוסד\הסניף
RE CPS כל תו 90 לא [רישום] מדינה, מחוז, או אזור אדמיניסטרטיבי של המוסד\סניף
RE ZIP CODE כל תו 15 לא [רישום] מיקוד המוסד\הסניף
RE POB NUMBER כל תו 35 לא שדה מופרד בפסיקים עם מספר תא הדואר של המוסד\הסניף והמיקוד המתאים לתא דואר זה.
דוגמה:
"POB 103352, 40024"
זה יאפשר ללקוחות לקבל את כתובת תא הדואר המלאה:
POB 103352
40024, DUESSELDORF (CITY)
OP STREET ADDRESS 1 כל תו 35 לא [תפעולי] שם רחוב
OP STREET ADDRESS 2 כל תו 35 לא [תפעולי] מספר רחוב
OP STREET ADDRESS 3 כל תו 35 לא [תפעולי] בניין, שם בניין, קומה
OP STREET ADDRESS 4 כל תו 35 לא [תפעולי] אזור
OP CITY כל תו 35 לא [תפעולי] עיר המוסד\הסניף
OP CPS כל תו 90 לא [תפעולי] מדינה, מחוז, או אזור אדמיניסטרטיבי של הסניף\המוסד
OP ZIP CODE כל תו 15 לא [תפעולי] מיקוד של המוסד\הסניף
OP POB NUMBER כל תו 35 לא שדה מופרד בפסיקים עם מספר תא הדואר של המוסד\הסניף והמיקוד המתאים לתא דואר זה.
דוגמה:
"POB 103352, 40024"
זה יאפשר ללקוחות לקבל את כתובת תא הדואר המלאה:
POB 103352
40024, DUESSELDORF (CITY)
BR STREET ADDRESS 1 כל תו 35 לא [סניף] שם רחוב
BR STREET ADDRESS 2 כל תו 35 לא [סניף] מס' רחוב
BR STREET ADDRESS 3 כל תו 35 לא [סניף] בניין, שם בניין, קומה
BR STREET ADDRESS 4 כל תו 35 לא [סניף] אזור
BR CITY כל תו 35 לא [סניף] עיר הסניף\המוסד
BR CPS כל תו 90 לא [סניף] מדינה, מחוז, או אזור אדמיניסטרטיבי של הסניף\המוסד
BR ZIP CODE כל תו 15 לא [סניף] מיקוד של המוסד\הסניף
BR POB NUMBER כל תו 35 לא שדה מופרד בפסיקים עם מספר תא הדואר של המוסד\הסניף והמיקוד המתאים לתא דואר זה.
דוגמה:
"POB 103352, 40024"
זה יאפשר ללקוחות לקבל את כתובת תא הדואר המלאה:
POB 103352
40024, DUESSELDORF (CITY)
BRANCH INFORMATION כל תו 70 לא מידע אודות סניף
זהו תיאור בטקסט חופשי של הסניף, כפי שסופק ע"י המוסד הפיננסי אליו הסניף שייך. כרגע, מידע זה יסופק רק עבור יישויות בעלות BIC, ורק כאשר המוסד הפיננסי מעוניין לספק מידע נוסף זה. המידע מגיע מארכיון ה-BIC.
COUNTRY NAME כל תו 70 כן שם המדינה של המוסד\הסניף כפי שצויין בתקן ISO 3166
ISO COUNTRY CODE אלפביתי 2 כן קוד המדינה של המוסד\הסניף כפי שצויין בתקן ISO 3166-1 אלפא-2
LOCATION CODE כל סוג 1 כן מכיל את המיקום (בעבר, התו ה-7 ב-BIC על-פי התקן של שנת 2009)
דוגמאות:
• ב-FR, קודי BIC בפריז = P
• ב-BE, קודי BIC בבריסל = B
• ב-US, קודי BIC בחוף המזרחי = 3
FIN SERVICE CODES כל סוג 60 לא קודי שירות FIN (נקראים גם קודי ערך מוסף). קודי שירות מסופקים רק עבור רשומות עם BIC.
שדה זה מכיל עד 20 קודים בני שלושה תווים כל אחד בסדר אלפבתי
RECORD KEY BDP אלפאנומרי 12 לא המפתח הייחודי של רשומת ארכיון בנקאי פלוס בקובץ.
FIELD A כל תו 1 לא שמור לשימוש עתידי
FIELD B כל תו 64 לא שמור לשימוש עתידי
FIELD C כל תו 128 לא שמור לשימוש עתידי
FIELD D כל תו 256 לא שמור לשימוש עתידי
FIELD E כל תו 11 לא שמור לשימוש עתידי
FIELD F כל תו 12 לא שמור לשימוש עתידי
מערכת ה-API מחזירה תוצאות בפורמט XML, מה שמקל על הניתוח של התוצאות במגוון של שפות תכנות ופלטפורמות.

דוגמה לתשובת XML מה-API עבור חיפוש BIC תיראה כך:


<result>
<bicdata>
<row>
<modification_flag>A</modification_flag>
<changed_field>34</changed_field>
<record_key>BP0000004OQQ</record_key>
<previous_record_key>BP00000030XZ</previous_record_key>
<next_record_key/>
<event_type>BIC ADDRESS CHANGED</event_type>
<event_date>20150606</event_date>
<bic8>BARCGB22</bic8>
<branch_bic>XXX</branch_bic>
<bic>BARCGB22XXX</bic>
<record_status>C</record_status>
<operationally_active_record>Y</operationally_active_record>
<subtype_indicator>SUPE</subtype_indicator>
<swift_fin>Y</swift_fin>
<swift_fa>N</swift_fa>
<swift_ia>N</swift_ia>
<legal_name>BARCLAYS BANK PLC</legal_name>
<institution_name>BARCLAYS BANK PLC</institution_name>
<institution_type>FINANCIAL</institution_type>
<entity_type>Legal Entity</entity_type>
<re_street_address_1>1, CHURCHILL PLACE</re_street_address_1>
<re_street_address_2/>
<re_street_address_3/>
<re_street_address_4/>
<re_city>LONDON</re_city>
<re_cps/>
<re_zip_code>E14 5HP</re_zip_code>
<re_pob_number/>
<op_street_address_1>1 CHURCHILL PLACE</op_street_address_1>
<op_street_address_2/>
<op_street_address_3/>
<op_street_address_4/>
<op_city>LONDON</op_city>
<op_cps>LONDON E14 5HP</op_cps>
<op_zip_code/>
<op_pob_number/>
<br_street_address_1/>
<br_street_address_2/>
<br_street_address_3/>
<br_street_address_4/>
<br_city/>
<br_cps/>
<br_zip_code/>
<br_pob_number/>
<branch_information>(ALL U.K. OFFICES)</branch_information>
<country_name>UNITED KINGDOM</country_name>
<iso_country_code>GB</iso_country_code>
<location_code>2</location_code>
<fin_service_codes>EBAERPFINSCOSTGTGT</fin_service_codes>
<record_key_bdp>BD00000006FO</record_key_bdp>
<field_a/>
<field_b/>
<field_c/>
<field_d/>
<field_e/>
<field_f></field_f>
</row>
</bicdata>
<errors/>
</result>




5. שגיאות API

במקרה של שגיאה, ה-API יחזיר תשובת XML שמכילה את הודעת השגיאה.

תגי ה-XML יוחזרו כתשובה ללא שדות אחרים ב-XML התשובה.

פירוט של כל השגיאות האפשריות מופיע מטה:

קוד שגיאה סוג תיאור
301 שגיאת חשבון מפתח API שגוי
302 שגיאת חשבון רישום פג תוקף
303 שגיאת חשבון אין שאילתות זמינות
304 שגיאת חשבון אין לכם גישה ל-API זה
401 שגיאת קלט קוד SWIFT מקובל חייב להיות 8 או 11 תווים באורך
402 שגיאת קלט שם בנק לא תקין! חיפוש בנק צריך להכיל לפחות 4 תווים.
התווים המורשים הם a-z, A-Z, 0-9, ורווח בלבד!
403 שגיאת קלט קוד מדינה שגוי! קוד מדינה חייב להיות עד 2 תווים בלבד. דוגמאות: UK, DE, FR