חוקי API: הבדלים בין גרסאות בדף

מתוך Mind Connect
קפיצה לניווט קפיצה לחיפוש
(הוספת כותרת עבור רשימת קודי שגיאה)
 
(7 גרסאות ביניים של 2 משתמשים אינן מוצגות)
שורה 2: שורה 2:


יצירה או עריכת חוקי API מתבצעת כברירת מחדל בתפריט הראשי: "פרויקטים" ← "ניהול" ← "חוקי API".
יצירה או עריכת חוקי API מתבצעת כברירת מחדל בתפריט הראשי: "פרויקטים" ← "ניהול" ← "חוקי API".
 
__TOC__
=== יצירת חוק API ===
=== יצירת חוק API ===
כדי ליצור API חדש תחילה יש לבחור את הפרויקט ואת המאגר שמשויך לפרויקט שאליו נרצה לשייך את הלקוחות שיגיעו דרך ה API.
כדי ליצור API חדש תחילה יש לבחור את הפרויקט ואת המאגר שמשויך לפרויקט שאליו נרצה לשייך את הלקוחות שיגיעו דרך ה API.
שורה 39: שורה 39:


=== קישור ה API ===
=== קישור ה API ===
לנוחיותכם, מובאים כאן הגדרות התממשקות ל-API של Make ושל Zapier.


==== integromat (make) ====
* [[Make (Integromat)|להגדרות של Make (לשעבר Integromat)]]
נדגים יצירת קישור API בין פרסום פייסבוק למערכת CRM על-ידי המערכת integromat (make):
*[[חיבור MAKE APP|להגדרות שימוש ב-Make App]]
* [[Zapier|להגדרות של Zapier]]


'''הערה:''' נדרש לאשר את כתובת ה IP לפי השרת עליו ה integromat שלכם יושב (בדר"כ זה יהיה eu1) כפי שמוצג [https://www.make.com/en/help/connections/allowing-connections-to-and-from-make-ip-addresses במסמך באתר הרשמי integromat (make).]
=== סוגי תשובות ה-API ===
מצ"ב קודי תשובות מה-API וההסברים. התשובה המחוזרת היא בפורמט JSON הבא:<syntaxhighlight lang="json">
{
    "result": <true/false>,
    "data": [
        {
            "code": <int>, //0 for success, other for failure
            "message": <string>, // describes the error for failure, or record id for success
            "status": <success/duplicate>, // for success and duplicate results. for failure, will not exists.
            "repository assign id": <int> // relations id of the customers, or for the given customer
        }
    ],
    "id": <int> // id of the request
}


# אם נרצה לקשר חוק API קיים אפשר להתקדם לשלב הבא.  במידה ואין חוק API קיים או שנרצה לקשר לחוק API חדש, יש ליצור חוק API חדש לפי השלבים שמופיעים בראש העמוד תחת "יצירת חוק API".
</syntaxhighlight>דוגמא לכישלון:<syntaxhighlight lang="json">
# נתחבר ל integomat ונקשר את הפרסום בפייסבוק (או בכל אתר אחר) ל integromat.
{
# נלחץ על הפלוס שמופיע ב "router"[[קובץ:Integromat קישור API 1.png|ללא|ממוזער]]
    "result": false,
# נבחר HTTP [[קובץ:Integromat קישור API 2.png|ללא|ממוזער]]
    "data": [
# לאחר מכן תפתח רשימת אפשרויות, ונבחר "Make a request"[[קובץ:Integromat קישור API 3.png|ללא|ממוזער]]
        {
# נחזור למערכת ה CRM, נלחץ מקש ימני על חוק ה API שאותו נרצה לקשר ונבחר הצג קישור.[[קובץ:Integromat קישור API 4.png|ללא|ממוזער]]
            "code": 12,
# לפני השדות שמופיעים בקישור כך נמלא את הפרטים ב integromat.[[קובץ:Integromat קישור API 7.png|ללא|ממוזער]]<br />יש להוסיף תחת Query string:
            "message": "IP [1.1.1.1] is not allowed for API 1"
## auth_key: ולהעתיק את הקישור עד את המספר החל מ "AUTKEY=" ועד ל "&f1" (כפי שמופיע בתמונה בשלב 8).
        },
## f1: ולרשום ולבחור את השדה שהופיע ליד f1 בקישור.
        {
## f2: ולרשום ולבחור את השדה שהופיע ליד f2 בקישור.
            "code": 13,
## f3: ולרשום ולבחור את השדה שהופיע ליד f3 בקישור.
            "message": "Authentication key mismatch for API 1"
## במידה וחוק ה API יכיל יותר תאים או פחות כמות ה fים תהיה גדולה או קטנה בהתאמה.
        },
# נלחץ מקש ימני על המודל שכעת יצרנו ונבחר "Run this module only" כדי לבדוק האם החוק שיצרנו עובד.[[קובץ:Integromat קישור API 6.png|ללא|ממוזער]]
        {
# נמלא פרטי בדיקה ונלחץ "OK"[[קובץ:Integromat קישור API 8.png|ללא|ממוזער]]
            "code": 14,
#כעת נחזור לחוק ה API, נלחץ עליו מקש ימני ונבחר: "היסטורית בקשות".[[קובץ:Integromat קישור API 9.png|ללא|ממוזער|612x612 פיקסלים]]בסיום התהליך נאכל לראות כי הסטטוס הוא "בהצלחה" וזה אומר שהקישור עובד באופן תקין.
            "message": "Incorrect request type for API 1"
# במידה ונקבל סטטוס "כישלון" זה יכול להיות מכמה סיבות:
        },
## ה method של ה API ב integromat וב CRM שונה. (לדוגמא, אחד מהם מוגדר על post והשני על get).
        {
## צריך לוודא שה-IPים שהגדרנו בעת היצירה תואמים למה שנדרש מהמערכת אליה אנחנו מנסים להתחבר, לדוגמא integromat דורשים שיהיו כל ה IPים בין: 82.208.14.119 - 82.208.14.110.
            "code": 15,
            "message": "No customer fields found in request"
        }
    ],
    "id": "11337"
}


==== zapier ====
</syntaxhighlight>דוגמא להצלחה:<syntaxhighlight lang="json">
נדגים יצירת קישור API בין פרסום פייסבוק למערכת CRM על-ידי המערכת zapier:
{
    "result": true,
    "data": [
        {
            "code": 0,
            "message": "4992062",
            "status": "success",
            "repository assign id": "4992062",
        }
    ],
    "id": "11308"
}


'''הערה:''' המערכת zapier עובדת לפי כתובות IP רנדומליים ולכן מצריכה אישור של כל כתובת ה IP, פעולה זו בעצם תאפשר לכל מי שיהיה לו את הקישור API שלכם להעביר אליכם את הליד.
</syntaxhighlight>דוגמא לתשובה כאשר הלקוח קיים (ונפסל על כפילות):<syntaxhighlight lang="json">
{
    "result": true,
    "data": [
        {
            "code": 40,
            "message": "Customer already exists",
            "status": "duplicate",
            "repository assign id": 4992063
        }
    ],
    "id": "11336"
}


לכן חשוב מאוד לא להעביר את הקישור API לאף גורם מלבד להתממשקות מול zapier.
</syntaxhighlight>


#אם נרצה לקשר חוק API קיים אפשר להתקדם לשלב הבא.  במידה ואין חוק API קיים או שנרצה לקשר לחוק API חדש, יש ליצור חוק API חדש לפי השלבים שמופיעים בראש העמוד תחת "יצירת חוק API".
=== רשימת קודי שגיאה עבור חוקי API ===
#נתחבר ל zapier ונקשר את הפרסום בפייסבוק (או בכל אתר אחר) ל zapier.[[קובץ:Zapier facebook connection.png|ללא|ממוזער]]
להלן רשימה מלאה של קודי השגיאה המוחזרים
#נלחץ על ה + ונוסיף zapier formatter[[קובץ:Zapier formatter.png|ללא|ממוזער]]
{| class="wikitable"
#ב Event נבחר באפשרות של : TEXT.
|error id
#ב Action נבחר:
|error message
##ב Transform נבחר "Replace".
|explanation
##ב Find נרשום "+9720" (ללא "", כפי שמופיע בתמונה)
|-
##ב Replace נרשום "0" (ללא "", כפי שמופיע בתמונה)[[קובץ:Zapier formatter action.png|ללא|ממוזער]]
|0
#נלחץ על ה + ונוסיף webhooks.[[קובץ:Zapier webhook.png|ללא|ממוזער]]
|<id of customer>
#ב Event נבחר את שיטת הגישה לחוק כפי שהגדרנו ב"יצירת חוק API" שלב (1).
|הצלחה, מחזיר את מזהה שיוך הלקוח למאגר במערכת
#נחזור למערכת ה CRM, נלחץ מקש ימני על חוק ה API שאותו נרצה לקשר ונבחר הצג קישור.[[קובץ:Integromat קישור API 4.png|ללא|ממוזער]]
|-
# לפני השדות שמופיעים בקישור כך נמלא את הפרטים בזאפייר תחת ה Action של ה webhook. '''הערה:''' ב URL נעתיק מהקישור מההתחלה ועד ל "?" (כפי שמופיע בתמונה בשלב 8)[[קובץ:Webhook action.png|ללא|ממוזער]]
|1
#יש להוסיף תחת Data:
|Empty request
## auth_key: ולהעתיק את הקישור עד את המספר החל מ "AUTKEY=" ועד ל "&f1" (כפי שמופיע בתמונה בשלב 8).
|התקבלה בקשה ללא שדות כלל
## f1: ולרשום ולבחור את השדה שהופיע ליד f1 בקישור.
|-
## f2: ולרשום ולבחור את השדה שהופיע ליד f2 בקישור.
|2
## f3: ולרשום ולבחור את השדה שהופיע ליד f3 בקישור.
|Authentication key not provided
#לסיום נלחץ על "Test action" כדי לבצע בדיקה ולראות שלידים יוכלו להיכנס בצורה תקינה למערכת.[[קובץ:Zapier test action.png|ללא|ממוזער]]
|התקבלה בקשה ללא מפתח זיהוי
#כעת נחזור לחוק ה API, נלחץ עליו מקש ימני ונבחר: "היסטורית בקשות".[[קובץ:Integromat קישור API 9.png|ללא|ממוזער|612x612 פיקסלים]]בסיום התהליך נאכל לראות כי הסטטוס הוא "בהצלחה" וזה אומר שהקישור עובד באופן תקין.
|-
# במידה ונקבל סטטוס "כישלון" זה יכול להיות מכמה סיבות:
|3
## ה method של ה API ב zapier וב CRM שונה. (לדוגמא, אחד מהם מוגדר על post והשני על get).
|Project needed but not exists
##במידה והליד מגיע בהצלחה אך הוא ריק מפרטים, יש לבצע את הבדיקות [[לידים ריקים|כאן]].[[קובץ:ליד ריק.png|ללא|ממוזער]]
|התקבלה בקשה ל-API כללי ללא מזהה פרויקט
## צריך לוודא שה-IPים שהגדרנו בעת היצירה תואמים למה שנדרש מהמערכת אליה אנחנו מנסים להתחבר, לדוגמא zapier דורשים שיהיו כל ה IPים ולכן צריך להיות סימן של *[[קובץ:Zapier allow all IPS.png|ללא|ממוזער]]
|-
|10
|API status is not active
|ה-API המבוקש אינו פעיל
|-
|11
|The Ip field is invalid
|התרחשה שגיאה בפיענוח IP של מבקש הבקשה
|-
|12
|IP [<ip>] is not allowed
|התקבלה בקשה מכתובת IP לא מאושרת
|-
|13
|Authentication key mismatch
|מפתח האימות שהתקבל אינו תואם למפתח האימות שהוגדר לבקשה
|-
|14
|Incorrect request type
|סוג הבקשה שהתקבלה אינו תואם לסוג  הבקשה שהוגדר
|-
|15
|No customer fields found in request
|לא נמצאו שדות לקוח בבקשה שהתקבלה
|-
|17
|No API rule found for given auth_key
|לא נמצאה הגדרת API עבור מפתח האימות שהתקבל
|-
|18
|No API rule found for rule fields
|לא נמצאה הגדרת API עבור שדה החיפוש שהוגדר (sid)
|-
|19
|Api rule is inactive for the given field
|שיוך חוק ה-API לפי שדה החיפוש שהוגדר אינו פעיל
|-
|20
|Requests limit exceeded
|מספר הבקשות שהתקבלו חורגות מהמותר
|-
|21
|Failed requests limit exceeded
|מספר הבקשות שנכשלו חורגות מהמותר
|-
|30
|Invalid phone fields found
|שדה טלפון שהתקבל לא תקין
|-
|31
|Phone <field id> (phone type) invalid
|הערך <field id> אינו מספר טלפון תקין
|-
|32
|Fholder <fieldnumber> is invalid
|הערך בשדה <fieldnumber> אינו תקין
|-
|40
|Record already exists
|הלקוח קיים במערכת וסומן ככפול לפי הגדרות בקשת ה-API
|-
|41
|Insert customer status error
|קביעת סטטוס ללקוח נכשלה
|-
|42
|Insert customer details error
|הכנסת פרטי הלקוח לבסיס הנתונים נכשלה
|-
|43
|Black list customer
|לקוח ברשימה שחורה
|-
|99
|Could not insert request
|התרחשה שגיאה בהכנסת הבקשה לבסיס הנתונים
|}

גרסה אחרונה מ־10:59, 24 ביולי 2025

מערכת ה CRM מאפשרת לקבל לקוחות למאגרים קיימים על-ידי API וכך לקבל את הלידים שמגיעים מפרסומים ישירות למאגר הלקוחות במערכת.

יצירה או עריכת חוקי API מתבצעת כברירת מחדל בתפריט הראשי: "פרויקטים" ← "ניהול" ← "חוקי API".

יצירת חוק API

כדי ליצור API חדש תחילה יש לבחור את הפרויקט ואת המאגר שמשויך לפרויקט שאליו נרצה לשייך את הלקוחות שיגיעו דרך ה API.

יצירת חוק API חדש

לאחר שנבחר מאגר ההערה שבכחול "עליך לבחור מאגר בכדי להתחיל לערוך חוקי API" תתחלף ל '+'.

כפתור יצירת חוק API חדש

כאשר נלחץ על ה'+' נעבור לתהליך יצירת חוק API חדש עם ארבעה שלבים:

  1. בחירת שדות: בשלב זה נבחר את השדות אותם נרצה שה API ימלא במאגר כאשר הוא מקבל נתוני הלקוחות.
    בחירת שדות ביצירת חוק API חדש
  2. הגדרות API:
    יצירת חוק API חדש - הגדרות API
    1. שיטת גישה לחוק API: נדרש לבחור את שיטת משלוח ה-API (יש להתאים את השיטה לצורת השליחה של מקור ה-API).
    2. הגבל את סך הבקשות בפרק זמן מסוים: מגביל את סך בקשות ה API שיכולות להתקבל בפרק זמן מוגדר (עוזר למניעת ספאם).
    3. הגבל את מספר הבקשות שנכשלו בפרק זמן מסוים: מגביל את מספר בקשות ה API שנכשלו בעת קבלתם (עוזר למניעת ספאם).
  3. סוג חוק API:
    הגדרת סוג חוק API ביצירת חוק API API
    1. סטטוס לקוח: לקוחות שייכנסו דרך ה API הסטטוס יוגדר להם כפי הסטטוס שנבחר ב "סטטוס לקוח". (שדה זה אינו שדה חובה).
    2. הגדרות API:
      1. לקוח ממקור אורגני: לקוחות ממקור אורגני מקבלים עדיפות על לקוחות ממקור שאינו אורגני ולכן אם קיים לקוח ממקור לא אורגני ואותו לקוח התווסף ממקור אורגני הפרטים של הלקוח התעדכנו לפי המקור האורגני.
      2. אם הלקוח כבר קיים במערכת: לקוח ייחשב כפול אם לא עבר פרק הזמן שהוגדר בשדה זה.
  1. בחירת מגבלות IP: ההתחברות ה API מתבצעות לפי כתובות IP, יש לבדוק את הגבלות ה IP של הממשק אליו אתם מתחברים. לדוגמא, integromat (make) מצריך אישור כתובת IP לפי המסמך באתר שלהם.
    יצירת סוג API חדש - בחירת מגבלות IP

בסיום התהליך יש ללחוץ על "אישור" וייווצר חוק API חדש. המשויך למאגר שהגדרנו.

עריכת חוק API קיים

קיימת אפשרות לערוך חוק API קיים על-ידי לחיצה ימנית בעכבר על חוק ה API אותו נרצה לשנות.

עריכת חוק API קיים


לאחר הלחיצה יפתחו מספר אפשרויות:

  • הצגת קישור: מציג את הקישור של ה API. בעזרת הקישור מתחברים ל integromat, zapier וכו'.
    הצגת קישור API
  • עריכת חוק: מאפשר לערוך את כל השלבים שעברנו עליהם בעת יצירת חוק ה API.
    עריכת חוק API
  • שכפול חוק: מאפשר לשכפל חוק API במידה ונרצה ליצור חוק API עם הגדרות זהות לחוק API חדש.
    שיכפול חוק API קיים
  • יצירת מפתח חדש: בחירה באפשרות זו תשנה את המפתח של חוק ה API.
  • היסטוריית בקשות: מאפשר לצפות בכל בקשות ה API שהתקבלו.
  • מחיקת חוק: מוחק את חוק ה API.

קישור ה API

לנוחיותכם, מובאים כאן הגדרות התממשקות ל-API של Make ושל Zapier.

סוגי תשובות ה-API

מצ"ב קודי תשובות מה-API וההסברים. התשובה המחוזרת היא בפורמט JSON הבא:

{
    "result": <true/false>,
    "data": [
        {
            "code": <int>, //0 for success, other for failure
            "message": <string>, // describes the error for failure, or record id for success
            "status": <success/duplicate>, // for success and duplicate results. for failure, will not exists.
            "repository assign id": <int> // relations id of the customers, or for the given customer
        }
    ],
    "id": <int> // id of the request
}

דוגמא לכישלון:

{
    "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"
        },
        {
            "code": 14,
            "message": "Incorrect request type for API 1"
        },
        {
            "code": 15,
            "message": "No customer fields found in request"
        }
    ],
    "id": "11337"
}

דוגמא להצלחה:

{
    "result": true,
    "data": [
        {
            "code": 0,
            "message": "4992062",
            "status": "success",
            "repository assign id": "4992062",
        }
    ],
    "id": "11308"
}

דוגמא לתשובה כאשר הלקוח קיים (ונפסל על כפילות):

{
    "result": true,
    "data": [
        {
            "code": 40,
            "message": "Customer already exists",
            "status": "duplicate",
            "repository assign id": 4992063
        }
    ],
    "id": "11336"
}

רשימת קודי שגיאה עבור חוקי API

להלן רשימה מלאה של קודי השגיאה המוחזרים

error id error message explanation
0 <id of customer> הצלחה, מחזיר את מזהה שיוך הלקוח למאגר במערכת
1 Empty request התקבלה בקשה ללא שדות כלל
2 Authentication key not provided התקבלה בקשה ללא מפתח זיהוי
3 Project needed but not exists התקבלה בקשה ל-API כללי ללא מזהה פרויקט
10 API status is not active ה-API המבוקש אינו פעיל
11 The Ip field is invalid התרחשה שגיאה בפיענוח IP של מבקש הבקשה
12 IP [<ip>] is not allowed התקבלה בקשה מכתובת IP לא מאושרת
13 Authentication key mismatch מפתח האימות שהתקבל אינו תואם למפתח האימות שהוגדר לבקשה
14 Incorrect request type סוג הבקשה שהתקבלה אינו תואם לסוג הבקשה שהוגדר
15 No customer fields found in request לא נמצאו שדות לקוח בבקשה שהתקבלה
17 No API rule found for given auth_key לא נמצאה הגדרת API עבור מפתח האימות שהתקבל
18 No API rule found for rule fields לא נמצאה הגדרת API עבור שדה החיפוש שהוגדר (sid)
19 Api rule is inactive for the given field שיוך חוק ה-API לפי שדה החיפוש שהוגדר אינו פעיל
20 Requests limit exceeded מספר הבקשות שהתקבלו חורגות מהמותר
21 Failed requests limit exceeded מספר הבקשות שנכשלו חורגות מהמותר
30 Invalid phone fields found שדה טלפון שהתקבל לא תקין
31 Phone <field id> (phone type) invalid הערך <field id> אינו מספר טלפון תקין
32 Fholder <fieldnumber> is invalid הערך בשדה <fieldnumber> אינו תקין
40 Record already exists הלקוח קיים במערכת וסומן ככפול לפי הגדרות בקשת ה-API
41 Insert customer status error קביעת סטטוס ללקוח נכשלה
42 Insert customer details error הכנסת פרטי הלקוח לבסיס הנתונים נכשלה
43 Black list customer לקוח ברשימה שחורה
99 Could not insert request התרחשה שגיאה בהכנסת הבקשה לבסיס הנתונים
אוחזר מתוך "https://wiki.mindc.co/index.php?title=חוקי_API&oldid=839"