Voicenter אל תתקשר אלי - מדריך לחברות - כיצד להתממשק למאגר בAPI
לקראת השקת השירות שהחל ב1.1.2023, ואכיפת החוק שתחל ב22.1.2023 - פנו אלינו שותפים רבים עם שאלות וטיפים בנושא מאגר "אל תתקשר אלי".
ישנן מספר סיבות שיכולות להפוך את ביצוע הממשק למסורבל עד בלתי אפשרי, ואנחנו שמחים לשתף מניסיוננו על מנת שגורמים נוספים במשק הישראלי יוכלו להתחבר למאגר בקלות יחסית.
במאמר זה אפרט את השלבים לביצוע הממשק, לפי הנושאים הבאים:
1. רישום למערכת האימות הלאומית של my.gov.il על ידי דירקטור/מורשה בארגון.
2. מתן הרשאות לגורם אחר בארגון (בד"כ, גדול על הדירקטור שלכם להוציא ACCESS TOKEN בעצמו, ותעדיפו לתת הרשאות לביצוע הפעולה לאדם אחר שיותר פנוי לנושא לכל צורך בהמשך).
3. כניסה לפורטל החברות של הרשות להגנת הצרכן באמצעות מערכת הזיהוי הלאומי - ע"י אזרח שקיבל הרשאה בשם הארגון לבצע פעולות מול המאגר (הדירקטור או זה שקיבל הרשאה).
4. הנפקת הטוקן (token) והמזהה (user)
5. מימוש האימות מול הAPI שלהם (רמז מקדים: הדוקומנטציה נכון להיום שגויה, ונפרט כאן כיצד באמת הם מצפים לקבל את הטוקן).
6. דגשים ונקודות מאתגרות במימוש הAPI.
7. נקודות נוספות שהעלנו מול הרשות.
חברתנו דוגלת בהוגנות צרכנית כאחד מערכי היסוד ואנו שמחים וגאים להנגיש שירות חשוב זה לחברות ולמשק הישראלי.
נזכיר כי כל לקוחות Voicenter כבר נהנים מהגנה מלאה ואינטגרציה בזמן אמת למאגר כחלק מהשירותים של כלל לקוחות הענן שלנו, ונשמח להציע את השירותים לכל ארגון המעוניין בכך - הגנה מלאה - ללא הצורך בביצוע החיבור בעצמו - כחלק מהשירות: "מאגר אל תתקשר אלי - Voicenter - תיאור השירות".
1. רישום למערכת האימות הלאומית של my.gov.il על ידי דירקטור/מורשה בארגון.
רוב הדירקטורים כבר זכו לכבוד להירשם "ולהתחייל" למערכת האימות הלאומית של my.gov.il עבור צרכים אדמיניסטרטיביים שונים המונגשים על ידי משרדי הממשלה השונים כבר יותר משנה, ועושה רושם שהיד עוד נטויה לגבי תוכניות הממשלה - ובסופו של דבר - כל אזרח בישראל יבצע רישום למערכת עבור פעולות אזרחיות שונות.
לינק לממשק: https://my.gov.il/landing
לחץ על "להזדהות וכניסה" (ממליצים לסמן את הV למטה).
לינק להרשמה למערכת: https://account.gov.il/sspr/public/newuser
וודאו שאתם זמינים לנייד ולדוא"ל שלכם במהלך ההרשמה, כי מתבצעת אימות דו ספרתית של אימותי 2FA בתהליך.
2. מתן הרשאות לגורם אחר בארגון
בד"כ, גדול על הדירקטור שלכם להוציא ACCESS TOKEN בעצמו, ותעדיפו לתת הרשאות לביצוע הפעולה לאדם אחר שיותר פנוי לנושא לכל צורך בהמשך.
על מנת לבצע את הפעולה יש:
א. להיכנס לעמוד החברה בפורטל הממשלתי
- https://my.gov.il/sec/Business/home
שימו לב כי בפינה ימין למעלה החלפתם את החיבור לרמת החברה ולא האזרח.
ב. ללחוץ על "ניהול הרשאות" בתפריט בצד ימין למעלה.
ג. ללחוץ "+" בפינה השמאלית למעלה על "הוספת מורשה".
ד. נזין את פרטיו של המורשה החדש: אזרח ישראלי אחר שיקבל הרשאות לביצוע פעולות בארגון.
ה. נבחר את הרשאת "אל תתקשר אלי" ברשימת ההרשאות ונאשר סופית.
מורשה זה יקבל דוא"ל ויעקוב אחר ההוראות לביצוע (שהן כמו סעיף 1 - רישום למערכת ההזדהות הלאומית).
לאחר השלמת האימות, בעל ההרשאה או הדירקטור יכולים להתקדם ליצירת הטוקן.
הטוקן רשום על הארגון, חשוב שהאדם שמקבל הרשאות לבצע זאת יהיה מנהל בכיר בארגון שצפוי להישאר זמין בטווח הקרוב לשינויים ופעולות מזדמנות שייתכן ויידרשו בהמשך - כגון הנפקת טוקן חדש לאחר פקיעת תוקפו.
בנושא תוקף הטוקן - הרשות ציינה כי תוקפו אין סופי וניתן לבטלו דרך הממשק בו מוסיפים אותו.
אציין כי הטוקן הינו קוד JWT המונפק על ידי פורטל החברות - ובטוקנים מסוג זה ישנו תוקף בנוי כחלק מהמבנה שלו (exp בעל ערך מסוג חותמת זמן ב-EPOCH). כרגע הרשות מנפיקה את הטוקן עם תוקף של שבוע קדימה בלבד (!).
גורמים טכניים ברשות אישרו לי שבשלב זה לא מתבצע כל אימות לגבי תוקף הטוקן, כך שהמערכת כולה תתמוך בפניה גם של טוקנים שפג תוקפם, וכי אין לדעת אם הדבר ישתנה בעתיד הקרוב.
HEADS UP מאיתנו - אל תופתעו אם פתאום ייפול הממשק מול בגלל שהתוקף פג ולא ידעתם, ואל תופתעו שהרשות מקבלת ממכם טוקן שאינו בר תוקף ובכל זאת מקבלת אותו.
3. כניסה לפורטל החברות של הרשות להגנת הצרכן באמצעות מערכת הזיהוי הלאומי.
לינק לפורטל החברות: https://dnc.fta.gov.il/business-homepage/
הגישה מתאפשרת רק לאזרח שקיבל הרשאה בשם הארגון לבצע פעולות מול המאגר (הדירקטור או זה שקיבל הרשאה, כפי שהסברנו בסעיף הקודם).
יש לענות על הטופס של סוג העסק (לבחור בשם מי נכנסים לפורטל)
4. הנפקת הטוקן (token) והמזהה (user)
לאחר הכניסה לפורטל יש ללחוץ בתפריט למעלה על "ניהול חשבון ושאילתות" - ניהול Access Token.
לקבוע לטוקן שם וללחוץ על צור Access token
יתקבלו 2 קודים - להעתיק אותם לשימוש בהמשך.
5. מימוש האימות מול הAPI שלהם
לינק לדוקומנטציה:
https://www.gov.il/he/departments/news/cpfta_dncapi
לינק עם Collection לדוגמה:
https://www.getpostman.com/collections/b17ac1a8a24a1188a655
שימו לב! מסמך ה-API רושם שיש לשלוח אליהם את הtoken כחלק מה-Authorazation Header. הדבר אינו נכון.
ההסבר הפשוט שלנו במקום:
בפורטל החברות הנפקתם שני stringים:
את העליון, הטוקן, יש לשלוח בערך של Header שנקרא: token.
את התחתון, הidentifier - יש לשלוח בערך של Header שנקרא: name.
להלן דוגמת curl פשוטה:
החלפו כמובן את הערכים תחת name ותחת token לערכים שלכם - ותקבלו תגובה תקינה מהמאגר:
curl –location –request POST ‘https://pverification.fta.gov.il/restricted/phone-list-verification’ \
--header ‘name: 111111111111_123456789’ \
--header ‘token: eyxxxxxxxxxxx-voicenter-copyrights-xxxxxxxxxxxxxx’ \
--header ‘Content-Type: application/json’ \
--data-raw ‘{
“data”:[“526868778”,”546868778”,”0546868778”,”123”,”526868778”]
}
- דגשים ונקודות מאתגרות במימוש הAPI.
- לא ניתן לחפש לפי תאריך הוספה למאגר.
מברור מול הרשות - הדרך היחידה לבדיקה הינה לבדוק פר מספר, כך שאין אפשרות לאגור אצלכם באופן מקומי את המאגר ולבצע שאילתות יומיות על ההפרשים היומיים שיצטברו בו.
כלומר, הדרך היחידה להבטיח בדיקת המספרים לפני החיוג היא לבצע את הבדיקה ממש לפני שמחליטים לחייג.
- שימו לב כי ה-API מבקש לקבל את המספרים ללא הספרה 0 ומחזיר את התוצאה עם 0 בתחילת המספר.
שימו לב כי מבנה התשובה (response) שמתקבלת משתנה:
-
- אם המספר קיים במאגר הוא לא יוחזר בתשובה.
- אם נמצא המאגר יוחזר כ-string עם "0" בהתחלה.
- אם המספר אינו תקין הוא יחזור בתור אובייקט עם קוד שגיאה מתאים.
כפי שניתן לראות צריך לכתוב קוד שמטפל בכל אחד מהמקרים שצוינו לעיל בהתאמה.
כאן בדיוק הפתרון שלנו בVoicenter נכנס לתמונה ועושה את זה באופן שקוף והרמטי למשתמש גם אם המספר כלל לא חויג מתוך מערכת המידע של הארגון אלא ידנית ממכשיר הטלפון - ללא כל צורך בפיתוח מצד לקוחותינו!
