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

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

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

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

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

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