חוקי API
קפיצה לניווט
קפיצה לחיפוש
מערכת ה CRM מאפשרת לקבל לקוחות למאגרים קיימים על-ידי API וכך לקבל את הלידים שמגיעים מפרסומים ישירות למאגר הלקוחות במערכת.
איך מגיעים: בתפריט הראשי "פרוייקטים" ← "ניהול" ← "חוקי API".
רשימת חוקי ה-API
- בחר פרויקט ובחירת מאגרים ואז החל - סינון הרשימה. משתמש מתחת להרשאת מנהל אתר רואה רק את הפרויקט שלו.
- העמודות: מזהה, שם פרויקט, שם, מפתח API, סטטוס (הסטטוס שהחוק קובע ללקוח), סוג, שם מאגר, שדות (* = שדה חובה), מגבלות הבקשות, להחליף נתוני לקוחות?, כפילות בימים, כתובות IP, בעלים, פעיל ותאריך יצירה.
- חץ ירוק או אדום לפני שם החוק: מקור אורגני או לא אורגני.
- המתג פעיל משפיע מיד, בלי אישור. חוק לא פעיל מחזיר קוד 10.
- הכפתור + ("הוספת חוק API חדש") פותח את אשף היצירה.
- גלגל השיניים נהל חוקי API לפרויקט (כשנבחר פרויקט אחד בלבד) - API של הפרויקט: כתובת אחת לכל הפרויקט, שמנתבת כל בקשה לחוק המתאים לפי ערך של שדה. השגיאות שלו הן קודים 17, 18 ו-19.
יצירת חוק API
לוחצים על +. נפתח האשף "יצירת חוק API חדש" עם ארבעה שלבים והכפתורים "הקודם", "הבא" ו"אשר":
- בחירת שדות: מעבירים את השדות שה-API ימלא משדות זמינים לשדות נבחרים (גרירה או לחיצה כפולה). הסדר ברשימה קובע את שמות הפרמטרים f1, f2 וכן הלאה, וכתובת URL סופית מתעדכנת בהתאם. שדות חובה מסומנים ב-*. צריך לבחור לפחות שדה אחד מקבוצה ייחודית (השדות שלפיהם מזהים לקוח כפול), אחרת מופיעה ההודעה "לא נבחר שדה קבוצה ייחודי". בזמן קבלת בקשה ה-API בודק רק ששדות הטלפון שמסומנים כחובה מולאו.
- הגדרות API:
- שם החוק (חובה).
- שיטת גישה לחוק API: "כל שיטה" (ברירת המחדל), GET, POST או PUT. בקשה בשיטה אחרת מקבלת קוד 14.
- הגבל את סך הבקשות בפרק זמן מסוים: "הגבל אם התקבלו N בקשות בתוך T שניות". כל הבקשות נספרות, גם כאלה שנדחו. מעבר למגבלה הבקשה נדחית עם קוד 20. ריק או 0 = בלי הגבלה (עוזר למניעת ספאם).
- הגבל את מספר הבקשות שנכשלו בפרק זמן מסוים: לא חוסם בקשות. כשמספר הבקשות שנכשלו או נדחו ככפולות מגיע למגבלה, התשובה לבקשה שנכשלה כוללת גם את קוד 21.
- הגדרות API:
- אורגני / לא אורגני: האם החוק מקבל לידים ממקור אורגני (ראו לקוח שכבר קיים במערכת).
- אפשר החלפת מופעים קיימים לאחר X ימים: כמה ימים ליד חוזר ייחשב כפול.
- החלף נתוני מופע אם המופע כבר קיים במערכת: "כן" (ברירת המחדל): כשליד חוזר מתקבל, פרטי הלקוח מתעדכנים לפי הבקשה. שדה שנשלח ריק לא מוחק ערך קיים.
- שדות בחירה מרובי ערכים: "החלף את הערכים" או "הוסף לערכים הקיימים". מופיע כשהחלפת הנתונים מופעלת.
- מיזוג יעד כפילויות: "מאגר API" (הלקוח עובר למאגר של החוק) או "מאגר קיים" (הלקוח נשאר במאגר שלו).
- יחסי API:
- מאגר (חובה): המאגר שהלקוחות ייכנסו אליו.
- סטטוס לקוח: "ללא שינוי" (ברירת המחדל), "ללא סטטוס" (מנקה את הסטטוס) או סטטוס מסוים. לקוח שיש לו כבר סטטוס שמוגדר כ"מצב סופי" (ראו ניהול סטטוסים) לא יקבל את הסטטוס. חוקי סטטוס לא מופעלים על סטטוס שנקבע דרך API.
- רשומה: קישור של כל לקוח שמגיע לרשומות שנבחרו באובייקטים אחרים ("הוספת רשומה חדשה").
- בחירת מגבלות IP: בוחרים מ"רשימת IP" את הכתובות שמותר להן לשלוח בקשות (לפחות אחת). כתובת חדשה מוסיפים ב"קבל IP נוכחי", ב"קבל IP מ-URL" (לפי דומיין), או ב"כתובת IP" ו"שם IP" ואז "IP חדש". השורה "אפשר מכל מקום" (*) מבטלת את בדיקת ה-IP, ומופיעה למנהל פרויקט ומעלה. ה-API משווה כתובת IPv4 מלאה בלבד: כתובת עם כוכבית כמו 1.2.3.* לא תעבוד. יש לבדוק את הגבלות ה IP של הממשק אליו אתם מתחברים. לדוגמא, integromat (make) מצריך אישור כתובת IP לפי המסמך באתר שלהם.
בסיום התהליך יש ללחוץ על "אשר" וייווצר חוק API חדש, המשויך למאגר שהגדרנו.
לקוח שכבר קיים במערכת
המערכת מזהה לקוח קיים לפי השדות של הקבוצות הייחודיות, בפרויקטים שקשורים למאגר של החוק. אם הלקוח קיים רק בפרויקט שלא קשור, הוא פשוט נוסף למאגר.
כשהלקוח קיים, המערכת בודקת את הבקשה המוצלחת האחרונה שהביאה אותו דרך API:
- הלקוח לא הגיע קודם דרך API (נוסף ידנית או בייבוא): הבקשה מתקבלת.
- הליד הקודם לא אורגני והחוק הנוכחי אורגני: הבקשה מתקבלת תמיד. מקור אורגני מקבל עדיפות.
- בכל מצב אחר: הבקשה נדחית ככפולה (קוד 40) עד שעובר מספר הימים שבשדה "אפשר החלפת מופעים קיימים לאחר X ימים" של החוק שקיבל את הליד הקודם. הימים נספרים לפי תאריך: 1 = רק באותו יום. 0 או ריק = הבקשה אף פעם לא נחשבת כפולה.
כשהבקשה מתקבלת ללקוח קיים, הלקוח משויך למאגר של החוק לפי "מיזוג יעד כפילויות" ומקבל את הסטטוס. הפרטים שלו מתעדכנים רק אם "החלף נתוני מופע" = "כן".
עריכת חוק API קיים
קיימת אפשרות לערוך חוק API קיים על-ידי לחיצה ימנית בעכבר על חוק ה API אותו נרצה לשנות (בטלפון: לחיצה כפולה).
לאחר הלחיצה יפתחו מספר אפשרויות:
- הצגת קישור: מציג את הקישור של ה API, בתצורה
https://<האתר שלכם>/api/rule<מספר החוק>_api.php?auth_key=<המפתח>&f1=.... אפשר להציג "כתובת מלאה" או "כתובת מופרדת" ולהעתיק. בעזרת הקישור מתחברים ל integromat, zapier וכו'. - עריכת חוק: תפריט משנה: "הגדרות" (כל שלבי האשף), "שינוי שם חוק API", "העבר מאגר", "בחירת שדות", "יחסי API", "הגדרות API" ו"הגבלות IP".
- הרץ פעם אחת: שליחת בקשה אמיתית אחת לחוק מתוך טופס, בלי בדיקת IP ושיטת גישה. שימושי לבדיקה.
- שכפול חוק: חוק חדש עם הגדרות זהות ומפתח חדש. בוחרים שם ומאגר, אבל העותק נשאר על המאגר של החוק המקורי. כדי לשנות מאגר, השתמשו אחר כך ב"עריכת חוק" ← "העבר מאגר".
- יצירת מפתח חדש: אפשר להקליד מפתח או להשאיר ריק למפתח אקראי. המפתח הישן מפסיק לעבוד מיד, ולכן יש לעדכן את כל מי ששולח לידים לחוק.
- היסטוריית בקשות: מאפשר לצפות בכל בקשות ה API שהתקבלו.
- מחיקת חוק: מוחק את חוק ה API (אפשר כמה חוקים יחד). הקישור שלו יחזיר מאותו רגע קוד 10.
קישור ה API
לנוחיותכם, מובאים כאן הגדרות התממשקות ל-API של Make ושל Zapier.
אפשר לשלוח את הפרמטרים בכתובת, בטופס או כ-JSON בגוף הבקשה. השמות type, ip, customer, once, p, rule_id ו-locale שמורים למערכת. אל תשתמשו בהם כשמות של שדות.
סוגי תשובות ה-API
התשובה היא JSON בפורמט הבא:
{
"result": <true/false>, // false only when the request was rejected before processing (codes 1-35)
"data": [
{
"code": <int>, // 0 for success, other for failure
"message": <string>, // the record id for success, or the error text
"status": <string>, // success / duplicate / failure; missing for codes 1-35
"instance_id": <int> // the repository assign id of the customer
}
],
"id": <string> // id of the request ("" when the request was not saved)
}
- result הוא true לכל בקשה שעובדה, גם כשהלקוח נדחה ככפול (40, 43) וגם בשגיאת עיבוד (44, 500). לכן בדקו תמיד את code ואת status.
- בבקשה שנדחתה בבדיקות הראשונות (קודים 1 עד 35) יכולות להיות כמה שגיאות ב-data, בלי status.
- ההודעות מתורגמות לפי שפת הבקשה. כדאי להסתמך על code ולא על הטקסט.
- המערכת מחכה עד 15 שניות לסיום העיבוד. אם העיבוד עוד לא הסתיים, data יחזור בלי code ועם status "new" או "in progress". התוצאה הסופית מופיעה בהיסטוריית הבקשות.
דוגמא לכישלון:
{
"result": false,
"data": [
{
"code": 12,
"message": "IP [1.1.1.1] is not allowed for API 1"
},
{
"code": 13,
"message": "Authentication key mismatch for API 1"
}
],
"id": "11337"
}
דוגמא להצלחה:
{
"result": true,
"data": [
{
"code": 0,
"message": "4992062",
"status": "success",
"instance_id": "4992062"
}
],
"id": "11308"
}
דוגמא לתשובה כאשר הלקוח קיים (ונפסל על כפילות):
{
"result": true,
"data": [
{
"code": 40,
"message": "Record already exists",
"status": "duplicate",
"instance_id": "4992063"
}
],
"id": "11336"
}
רשימת קודי שגיאה עבור חוקי API
להלן רשימה מלאה של הקודים המוחזרים. f<N> הוא מספר הפרמטר בבקשה, ו-<id> מספר החוק.
| קוד | הודעה | הסבר |
|---|---|---|
| 0 | <id of customer> | הצלחה. מחזיר את מזהה שיוך הלקוח למאגר במערכת (כמו instance_id) |
| 1 | Empty request | התקבלה בקשה ללא שדות כלל |
| 2 | Authentication key not provided | התקבלה בקשה ללא מפתח זיהוי |
| 3 | Missing project or rule id | בקשה בלי מספר חוק ובלי מזהה פרויקט |
| 4 | Failed to add request data | שמירת פרטי הבקשה נכשלה |
| 5 | Could not find any rule id for this request | אין חוק עם המספר שבכתובת |
| 10 | API <id> status is not active | החוק אינו פעיל או נמחק |
| 11 | The Ip field is invalid | כתובת ה-IP של השולח אינה כתובת IPv4 אחת (למשל IPv6) |
| 12 | IP [<ip>] is not allowed for API <id> | התקבלה בקשה מכתובת IP לא מאושרת |
| 13 | Authentication key mismatch for API <id> | מפתח האימות שהתקבל אינו תואם למפתח של החוק |
| 14 | Incorrect request type for API <id> | שיטת הבקשה (GET/POST/PUT) אינה תואמת לשיטה שהוגדרה בחוק |
| 15 | No fields found in request | לא נמצאו בבקשה פרמטרים f1, f2... |
| 17 | No API rule found for given auth_key | API של פרויקט: אין חוק עם מפתח האימות שהתקבל |
| 18 | No API rule found for rule with those fields | API של פרויקט: אין חוק שמתאים לשדה ולערך שנשלחו |
| 19 | API rule is inactive for the given field | API של פרויקט: החוק שמתאים לשדה שנשלח אינו פעיל |
| 20 | Requests limit exceeded | מספר הבקשות חרג מהמגבלה של החוק |
| 21 | Failed requests limit exceeded | לידיעה בלבד: מספר הבקשות שנכשלו הגיע למגבלה. הבקשה לא נחסמת בגללו |
| 31 | The f<N> (phone type) field is empty / The f<N> (phone type) field is invalid | שדה טלפון חובה נשלח ריק, או שהערך אינו מספר טלפון תקין |
| 32 | The f<N> field needs to be <max> or shorter in length | הערך ארוך מדי (עד 200 תווים, או הגודל של השדה) |
| 33 | The f<N> field needs to be <min> or longer in length | הערך קצר מהאורך המינימלי של השדה |
| 34 | The f<N> field needs to be <max> or shorter in length | הערך ארוך מהאורך המקסימלי שהוגדר לשדה |
| 35 | The f<N> field does not fit the pattern | הערך אינו מתאים לתבנית שהוגדרה לשדה |
| 40 | Record already exists | הלקוח קיים במערכת ונדחה ככפול לפי הגדרות החוק (status = duplicate). עם status = failure: יצירת הלקוח נכשלה, וההודעה מפרטת את השגיאה |
| 43 | Black list customer | הלקוח נמצא במאגר של רשימה שחורה |
| 44 | Failed to resolve repository assign id | שיוך הלקוח למאגר נכשל |
| 99 | Could not insert request | שמירת הבקשה נכשלה (נדיר) |
| 500 | Unexpected error during customer insert | שגיאה פנימית בעיבוד הבקשה (status = failure) |
| סטטוסים |
|
|---|---|
| חוקים |
|