מה זה API של מרכזייה?
API (Application Programming Interface — "ממשק תכנות יישומים") הוא ממשק שמאפשר למערכות אחרות לדבר עם המרכזייה: לקרוא שיחות והיסטוריה, להוריד הקלטות, לשלוח SMS ולחייג — בקוד, בלי לגעת בלוח הבקרה.
מה זה API, במילים פשוטות
API הם ראשי התיבות של Application Programming Interface — "ממשק תכנות יישומים". זו דלת שדרכה תוכנה אחת מבקשת דברים מתוכנה אחרת, לפי כללים מוסכמים. לוח הבקרה הוא הדלת של בני אדם: לוחצים, בוחרים, שומרים. ה-API הוא הדלת של מחשבים: שולחים בקשה מסודרת, ומקבלים תשובה מסודרת.
דימוי מוכר הוא מלצר במסעדה. אתם לא נכנסים למטבח ולא מבשלים בעצמכם. אתם מזמינים מהתפריט, המלצר מעביר את ההזמנה, ומביא לכם את המנה. ה-API הוא המלצר, התפריט הוא רשימת הפעולות שמותר לבקש, והמטבח הוא המרכזייה.
למה זה חשוב? כי הטלפון הוא לא איבר מבודד בארגון. יש אתר, מערכת הזמנות, תוכנת הנהלת חשבונות, מערכת CRM. API מאפשר לחבר ביניהם לבין המרכזייה, כך שמידע עובר לבד ופעולות קורות בלי שמישהו יעתיק מספרים ממסך למסך.
המונח REST, שמופיע הרבה ליד המילה API, מתאר סגנון נפוץ של ממשקים: כל פעולה היא כתובת אינטרנט, והתשובה חוזרת בפורמט טקסט מובנה שקל לתוכנה לקרוא.
איך בקשת API עובדת
- המערכת שלכם שולחת בקשה — למשל "תן לי את השיחות של אתמול" או "שלח SMS למספר הזה". הבקשה נשלחת לכתובת של הממשק, בשיטת GET (בדרך כלל לקריאת מידע) או POST (בדרך כלל לביצוע פעולה).
- הבקשה נושאת טוקן — מחרוזת סודית שמזהה מי שולח. זה כמו כרטיס עובד: בלי כרטיס לא נכנסים.
- הממשק בודק הרשאות — האם למשתמש הזה מותר לבצע את הפעולה הזו.
- המרכזייה מבצעת — שולפת את הנתונים או מבצעת את הפעולה.
- חוזרת תשובה — הנתונים עצמם, או אישור שהפעולה בוצעה (או הודעת שגיאה שמסבירה למה לא).
כל זה קורה בשבריר שנייה, ואפשר לחזור עליו אלפי פעמים ביום בלי שאף אדם יגע במקלדת.
מה אפשר לעשות עם API של מרכזייה
ממשק API של מרכזייה נוגע בדרך כלל בכמה תחומים:
- שיחות — אילו שיחות פעילות עכשיו, מי ממתין בתור, והיסטוריית השיחות מתוך יומן השיחות.
- הקלטות — שליפת קובץ ההקלטה של שיחה מסוימת, כדי לשמור אותו במערכת אחרת או לנתח אותו.
- SMS — שליחת הודעה מהמספר של העסק מתוך תוכנה.
- חיוג — יצירת שיחה: המרכזייה מחייגת לנציג, וכשהוא עונה, מחייגת ללקוח.
- רכיבי המרכזייה — קריאה ושינוי של הגדרות, כמו שלוחות, תורים ומספרים.
דוגמאות מהחיים
- אתר שמראה כמה ממתינים — מוקד שירות מציג בעמוד "צור קשר" כמה אנשים ממתינים בתור כרגע. הלקוח מחליט אם להתקשר עכשיו או מאוחר יותר.
- מערכת הזמנות ששולחת SMS — מרפאה או משרד קובעים תור במערכת שלהם, והמערכת שולחת ללקוח אישור ותזכורת ב-SMS מהמספר של העסק.
- דוח חודשי אוטומטי — בכל ראשון לחודש נשלף יומן השיחות, והנהלת העמותה מקבלת דוח: כמה שיחות, כמה נענו, מה זמני ההמתנה.
- כפתור "התקשרו אליי" — לקוח לוחץ באתר, והמרכזייה מחייגת לנציג פנוי ואז ללקוח. הלקוח לא מחכה על הקו.
- חיוג מכרטיס לקוח — ב-CRM לוחצים על מספר והשיחה יוצאת, בלי להקליד.
המשותף לכל הדוגמאות: משהו שהיה נעשה ביד, או לא נעשה בכלל, קורה לבד ובזמן.
API מול Webhook
API ו-Webhook נשמעים דומים, אבל הכיוון הפוך. ב-API המערכת שלכם שואלת את המרכזייה: "מה המצב?" ב-Webhook המרכזייה מודיעה למערכת שלכם ברגע שמשהו קרה: "נכנסה עכשיו שיחה ממספר כזה".
| נושא | API | Webhook |
|---|---|---|
| מי יוזם | המערכת שלכם | המרכזייה |
| מתי | כשאתם שואלים | ברגע שהאירוע קורה |
| מתאים ל | שליפת נתונים, ביצוע פעולה | תגובה מיידית לאירוע |
| דוגמה | דוח שיחות, שליחת SMS | פתיחת כרטיס לקוח כשהטלפון מצלצל |
ברוב החיבורים הטובים משתמשים בשניהם: Webhook מודיע שנכנסה שיחה, וה-API משמש לשלוף את הפרטים המלאים או לבצע פעולה בתגובה.
אבטחה: טוקן, הרשאות ואימות דו-שלבי
API פותח דלת למרכזייה, ולכן חשוב מי מחזיק במפתח. שלושה עקרונות מקובלים:
- טוקן מאובטח — במקום שם משתמש וסיסמה בכל בקשה, המערכת מקבלת מחרוזת סודית ארוכה. אפשר לבטל אותה ולהנפיק חדשה בלי לשנות את הסיסמה של אף אחד.
- הרשאות לפי המשתמש — הטוקן יורש את ההרשאות של המשתמש שהוא שייך אליו. משתמש שמותר לו רק לקרוא יומן שיחות לא יוכל דרך ה-API לשנות שלוחות או לחייג לחו"ל.
- אימות דו-שלבי — שכבת הגנה נוספת: בנוסף לסיסמה, קוד חד פעמי שנשלח או נוצר במכשיר נפרד.
טעויות נפוצות: לשים את הטוקן בקוד של דף אינטרנט שכל גולש יכול לראות, לשלוח אותו במייל או בקבוצה, או לתת לחיבור של אתר הרשאות מלאות כשהוא צריך רק לקרוא נתון אחד. הכלל פשוט: הטוקן יושב בשרת, לא בדפדפן, ולכל חיבור רק ההרשאות שהוא באמת צריך.
מה לבדוק לפני שמתחילים
- מה בדיוק אתם רוצים שיקרה — לתאר את התהליך במילים לפני שכותבים שורת קוד: "כשנקבע תור, יישלח SMS".
- מי יכתוב את החיבור — מתכנת בארגון, ספק מערכת ה-CRM, או מישהו מבחוץ.
- משתמש ייעודי — לפתוח לחיבור משתמש נפרד עם הרשאות מצומצמות, ולא להשתמש בחשבון של המנהל.
- מה קורה בתקלה — אם המרכזייה לא ענתה או החזירה שגיאה, מה המערכת שלכם עושה? מנסה שוב? מתריעה?
- לא להעמיס — לא לשאול את הממשק כל שנייה על נתון שמשתנה פעם בשעה.
שלוש בקשות, במילים: מה נשלח ומה חוזר
כדי להבין API לא צריך לקרוא קוד. מספיק לראות מה המערכת שלכם אומרת למרכזייה, ומה המרכזייה עונה. שלוש דוגמאות, מתורגמות לעברית פשוטה. השמות של השדות הם להמחשה — הפורמט המדויק נקבע בתיעוד של הממשק.
1. "תן לי את השיחות של אתמול" (GET). המערכת שולחת בקשה לכתובת של יומן השיחות, ובה: הטוקן שלה, תאריך התחלה, תאריך סיום, ואולי סינון — רק שיחות נכנסות, רק לתור המכירות. התשובה היא רשימה. לכל שיחה ברשימה: מזהה ייחודי, שעה, המספר שהתקשר, המספר שאליו חייג, מי ענה, כמה זמן המתין, כמה זמן דיברו, והאם יש הקלטה. המערכת שלכם עוברת על הרשימה ומכניסה כל שורה לדוח או לכרטיס הלקוח. 400 שיחות חוזרות בבת אחת, בשבריר שנייה.
2. "שלח SMS למספר הזה" (POST). הבקשה נושאת: טוקן, מספר הנמען, טקסט ההודעה, ולפעמים המספר העסקי שממנו לשלוח. התשובה קצרה: "התקבל" ומזהה של ההודעה, או שגיאה עם סיבה — מספר לא תקין, אין הרשאה לשלוח. את המזהה שומרים, כדי לדעת אחר כך על איזו הודעה מדובר.
3. "חייג ללקוח בשבילי" (POST). נציג לוחץ על מספר בכרטיס לקוח. המערכת שולחת: טוקן, שלוחת הנציג, מספר הלקוח. התשובה: מזהה השיחה שנוצרה. מה שקורה אחר כך כבר לא ב-API אלא במרכזייה: הטלפון של הנציג מצלצל, הוא מרים, ורק אז המרכזייה מחייגת ללקוח. הנציג שומע צלצול ואז "הלו". אם הלקוח לא ענה — השיחה נרשמת ביומן כלא נענתה, ואפשר לשלוף אותה בבקשה מספר 1 למחרת.
שימו לב לדפוס שחוזר בשלושתן: בקשה קצרה עם טוקן, תשובה מסודרת עם מזהה, והמערכת שלכם שומרת את המזהה כדי לחבר בין הפעולות. זה כל הסוד.
הרשאות וטוקנים: איך מסדרים את זה נכון
- משתמש לכל חיבור. לאתר — משתמש "אתר"; ל-CRM — משתמש "CRM". לא לשתף, ולא להשתמש במשתמש של המנהל.
- הרשאות מינימום. משתמש שרק מציג כמה ממתינים בתור לא צריך לשלוח SMS ולא לשנות שלוחות. אם הטוקן שלו ידלוף — הנזק קטן.
- טוקן במקום מוגן. בקובץ הגדרות בשרת, לא בקוד של הדף ולא במייל. מי שרואה את הדף בדפדפן רואה כל מה שיש בו.
- החלפה תקופתית. פעם בכמה חודשים מנפיקים טוקן חדש ומבטלים את הישן. גם כשמתכנת או ספק מסיימים את העבודה.
- אימות דו-שלבי למשתמשים אנושיים. לחשבונות שאנשים נכנסים אליהם — קוד נוסף מעבר לסיסמה. לחיבור אוטומטי — הטוקן הוא ההגנה, ולכן חשוב לשמור עליו.
- יומן. לדעת איזה חיבור עשה מה ומתי. כשמשהו מוזר קורה, זה המקום הראשון להסתכל.
לשאול או לחכות שיודיעו: איך בוחרים
השאלה שקובעת היא כמה מהר צריך לדעת. אם התשובה "ברגע שזה קורה" — Webhook. אם "פעם ביום" או "כשמישהו פותח את הדוח" — בקשת API כשצריך. שלושה מקרים:
- כרטיס לקוח שקופץ כשהטלפון מצלצל — חייב Webhook. בקשה כל חמש שניות "יש שיחה חדשה?" תעמיס על הממשק ועדיין תאחר.
- דוח שיחות חודשי — API בלבד. אין טעם לקבל הודעה על כל שיחה כדי לספור אותן בסוף החודש.
- מונה תרומות על מסך — אפשר בשתי הדרכים: Webhook על כל שיחה, או בקשת API כל דקה. ההבדל הוא דקה של איחור מול הצורך בשרת שמקשיב.
כלל אצבע: אירוע → Webhook; שאלה → API; ואם צריך גם וגם — Webhook שמודיע, ו-API שמשלים את הפרטים.
כשמשהו לא עובד: קריאת השגיאה
הממשק לא מחזיר רק "נכשל". הוא אומר למה, וכדאי לדעת לקרוא את זה:
- "לא מזוהה" — הטוקן חסר, שגוי או בוטל. לבדוק שהוא נשלח ושהוא עדיין בתוקף.
- "אין הרשאה" — הטוקן תקין, אבל למשתמש שלו אסור לבצע את הפעולה הזאת. להרחיב את ההרשאה, או להשתמש במשתמש אחר.
- "לא נמצא" — מזהה שיחה או שלוחה שלא קיימים. לרוב טעות בהעתקה.
- "יותר מדי בקשות" — המערכת שלכם שואלת בקצב גבוה מדי. להאט, ולשקול Webhook.
- "שגיאת שרת" — משהו בצד המרכזייה. לנסות שוב אחרי כמה שניות; אם חוזר — לפנות לתמיכה עם השעה ומזהה הבקשה.
איך זה עובד אצלנו בקשר
בקשר אנחנו נמצאים בהקמה של ממשק API למרכזייה. הממשק מיועד לשיחות, להקלטות, ל-SMS, לחיוג ולשליטה ברכיבי המרכזייה, ועובד בבקשות GET או POST.
ההרשאות בממשק הן לפי המשתמש: כל חיבור מקבל בדיוק את מה שמותר למשתמש שלו, ולא יותר. הגישה נעשית עם טוקן מאובטח, ואפשר להוסיף אימות דו-שלבי כשכבת הגנה נוספת.
אנחנו כבר משתמשים ב-API של המרכזייה בעצמנו: מערכת ה-CRM שבנינו שולפת דרכו את היסטוריית השיחות וההקלטות, מזהה את הלקוח לפי המספר, ומאפשרת חיוג ו-SMS מכרטיס הלקוח.
יש לכם רעיון לחיבור — אתר, מערכת הזמנות, דוח אוטומטי? דברו איתנו. נבדוק יחד מה אפשר לעשות כבר היום ומה יתאפשר כשהממשק ייפתח ללקוחות.
שאלות נפוצות
מה ההבדל בין API ל-Webhook?
ב-API המערכת שלכם פונה למרכזייה ושואלת או מבקשת פעולה. ב-Webhook המרכזייה פונה למערכת שלכם ברגע שקרה אירוע.
צריך מתכנת כדי להשתמש ב-API?
בדרך כלל כן, או ספק של מערכת שכבר יודעת להתחבר. ה-API מיועד לתוכנות, לא לשימוש ידני.
זה בטוח לפתוח API למרכזייה?
כשעובדים נכון — כן: טוקן סודי שנשמר בשרת, הרשאות מצומצמות לכל חיבור, ואימות דו-שלבי אם צריך.
מה ההבדל בין GET ל-POST?
בדרך כלל GET משמש לקריאת מידע ו-POST לביצוע פעולה או לשליחת נתונים, כמו שליחת SMS.
ה-API של קשר זמין כבר?
הממשק נמצא בהקמה. דברו איתנו כדי לבדוק מה אפשר לחבר כבר היום לצרכים שלכם.
איך בודקים שהחיבור עובד לפני שמפעילים אותו?
מתחילים בבקשת קריאה פשוטה, כמו שליפת השיחות של אתמול, ורק אחרי שהיא חוזרת נכון עוברים לפעולות כמו שליחת SMS או חיוג.
מה עושים כשהטוקן דלף?
מבטלים אותו מיד ומנפיקים חדש. בגלל זה חשוב טוקן נפרד לכל חיבור — מבטלים אחד בלי לעצור את השאר.
האם ה-API מחליף את לוח הבקרה?
לא. לוח הבקרה נשאר לאנשים, ה-API למערכות. שניהם עושים את אותן פעולות, בדלתות שונות.
מה ההבדל בין טוקן לסיסמה?
סיסמה מזהה אדם ונשארת אותו דבר בכל מקום. טוקן הוא מחרוזת ארוכה שמונפקת לחיבור אחד, אפשר לבטל אותו לבד בלי לפגוע בשאר, ולכן הוא מתאים למערכות ולא לאנשים.