נקודות הקצה של ה-API לניהול בכמות גדולה מאפשרות ליצור או לעדכן מספר גדול של משתמשים באמצעות אוסף הניהול של משתמשים בכמות גדולה.
ה-API תומך בשימוש בקובצי JSON. אפשר לקבל נתונים בפורמט JSON באמצעות Template API.
יש תמיכה רק באימות של משתמש API. צריך להזין את טוקן המשתמש ב-API במשתנה הסיסמה. אין תמיכה באימות מדור קודם באמצעות סוד החברה.
כשמעלים קובץ JSON באמצעות ה-API להעלאה, נוצרת משימה שמאמתת את סכימת קובץ ה-JSON.
נקודות הקצה שנתמכות לניהול משתמשים בכמות גדולה כוללות את הנקודות הבאות:
כדי להוסיף או לעדכן משתמשים בכמות גדולה באמצעות ה-API של משתמשים בכמות גדולה:
קוראים לשיטת Template כדי לקבל את אובייקט תבנית ה-JSON שבו תשתמשו כדי ליצור את קובץ ה-JSON.
מפעילים את השיטה Bulk add users from file או את השיטה Bulk update users from file, בהתאם לפעולה שרוצים לבצע (הוספה או עדכון של משתמשים בכמות גדולה). בבדיקה הזו מאומתת הסכימה של קובץ ה-JSON שסיפקתם.
אחרי שמאמתים את סכימת קובץ ה-JSON, קוראים לשיטה Proceed. המשימה תתחיל.
כדי לקבוע את הסטטוס של העבודה, צריך לבצע קריאה לשיטה Jobs.
פורמט קובץ JSON
כדי לקבל את פורמט קובץ ה-JSON, צריך להפעיל את שיטת התבנית.
| שם השדה | ערכים | חובה | אימות |
|---|---|---|---|
| אימייל | מחרוזת(אימייל) | כן | חובה להזין כתובת אימייל תקינה. הערך צריך להיות ייחודי בקובץ בעמודה 'אימייל' (ללא כפילויות), כך שיהיה רק עדכון אחד לכל כתובת אימייל בכל קובץ |
| new_email | מחרוזת(אימייל) | לא | חובה להזין כתובת אימייל תקינה. הערך צריך להיות ייחודי בקובץ בעמודה 'אימייל חדש' (ללא כפילויות). כלומר, אפשר לבצע רק עדכון אחד לכל כתובת אימייל בכל קובץ |
| agent_number | String | לא | מחרוזת ללא אימות |
| first_name | String | כן | מחרוזת לא ריקה |
| last_name | String | כן | מחרוזת לא ריקה |
| סטטוס | פעיל, לא פעיל, ריק | לא | חייב להיות 'פעיל', 'לא פעיל' או ריק |
| location | מחרוזת שהיא שם מיקום, ריקה או Null | לא | הערך צריך להיות זהה לאחד מהמיקומים הקיימים (לא תלוי באותיות רישיות), או Null, או ריק |
| max_chat_limit | 1 עד X (כאשר X הוא הערך המוגדר), ריק | לא | הערך חייב להיות בין 1 ל-X (כולל), או ריק |
| max_chat_limit_enabled | 0, 1, ריק | לא | הערך חייב להיות 0, 1 או ריק |
| roles | name: Role name / value: 0, 1, Empty | לא | הערך חייב להיות 0, 1 או ריק |
| צוותים | name: Team name / value: 0, 1, Empty | לא | הערך חייב להיות 0, 1 או ריק |
אחרי שהשיטה להעלאת קובץ JSON באמצעות API מצליחה, אפשר להפעיל את השיטה של API להמשך, והפעולות של יצירת משתמש או שינוי משתמש יעברו עיבוד.
השיטות upload ו-proceed מבוצעות באופן אסינכרוני על ידי Contact Center AI Platform (CCAI Platform). כדי לבדוק את הסטטוס, מפעילים את השיטה jobs ומציינים את job_id.
שדה סטטוס
השדה status יכול לקבל כל אחד מהערכים הבאים:
| סטטוס המשרה | תיאור |
|---|---|
| ההגדרות האישיות נוצרו | נוצרה משימה שממתינה לאימות. |
| valid_scheme | האימות של הסכימה הצליח ואפשר להמשיך. |
| invalid_scheme | אימות הסכימה נכשל. אפשר לבדוק מידע מפורט באמצעות Scheme error log API. |
| in_progress | מתבצע עדכון או יצירה של כמות גדולה של משתמשים. |
| הסתיימה | העדכון או היצירה של משתמשים בכמות גדולה הושלמו. |
תבנית
נקודת קצה (endpoint):
Method: GET
Type:
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/template
דוגמה לבקשה ולתשובות
בקטעים הבאים מופיעות דוגמאות לבקשות לנקודת הקצה.
קבלת תבנית
בדוגמה הזו אפשר לראות איך מאחזרים את התבניות.
בקשה
Body: None
תשובה: תבנית
[
{
"email": "user1@somedomain.com",
"new_email": "user1@somedomain.com",
"agent_number": "A-001",
"first_name": "James",
"last_name": "Bond",
"status": "Active",
"location": "Mexico",
"max_chat_limit": "2",
"max_chat_limit_enabled": "0",
"roles": [
{
"name": "Admin",
"value": 0
},
{
"name": "Manager",
"value": 0
},
{
"name": "Agent",
"value": 0
},
{
"name": "Developer",
"value": 0
},
{
"name": "Manager Admin",
"value": 0
},
{
"name": "Manager Team",
"value": 0
},
{
"name": "Manager Data",
"value": 0
}
],
"teams": [
{
"name": "test team_1",
"value": 0
},
{
"name": "test Team 2",
"value": 0
},
{
"name": "test team 3",
"value": 0
}
]
},
{
"email": "user2@somedomain.com",
"new_email": "user3@somedomain.com",
"agent_number": "A-002",
"first_name": "John",
"last_name": "Doe",
"status": "Inactive",
"location": "",
"max_chat_limit": "",
"max_chat_limit_enabled": "1",
"roles": [
{
"name": "Admin",
"value": 0
},
{
"name": "Manager",
"value": 0
},
{
"name": "Agent",
"value": 0
},
{
"name": "Developer",
"value": 0
},
{
"name": "Manager Admin",
"value": 0
},
{
"name": "Manager Team",
"value": 0
},
{
"name": "Manager Data",
"value": 0
}
],
"teams": [
{
"name": "test team_1",
"value": 0
},
{
"name": "test Team 2",
"value": 0
},
{
"name": "test team 3",
"value": 0
}
]
},
{
"email": "user3@somedomain.com",
"new_email": "user2@somedomain.com",
"agent_number": "A-003",
"first_name": "Jane",
"last_name": "Doe",
"status": "",
"location": "null",
"max_chat_limit": "1",
"max_chat_limit_enabled": "",
"roles": [
{
"name": "Admin",
"value": 0
},
{
"name": "Manager",
"value": 0
},
{
"name": "Agent",
"value": 0
},
{
"name": "Developer",
"value": 0
},
{
"name": "Manager Admin",
"value": 0
},
{
"name": "Manager Team",
"value": 0
},
{
"name": "Manager Data",
"value": 0
}
],
"teams": [
{
"name": "test team_1",
"value": 0
},
{
"name": "test Team 2",
"value": 0
},
{
"name": "test team 3",
"value": 0
}
]
}
]
קוד הסטטוס: 200
תעסוקה
נקודת קצה (endpoint):
Method: GET
Type:
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/bulk/users/jobs/{job_id}
דוגמה לבקשה ולתשובות
בקטעים הבאים מופיעות דוגמאות לבקשות לנקודת הקצה.
פרטי המשרה
בדוגמה הזו מוסבר איך לאחזר את פרטי המשרה של משרה ספציפית. בדוגמה הזו, מזהה המשרה הוא 1.
בקשה
כותרות:
| מפתח | ערך | תיאור |
|---|---|---|
| סוג התוכן | application/json |
שאילתה:
Method: GET
Type:
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
תשובה: פרטי משרה
{
"id": 1,
"created_at": "2022-01-07T06:06:45.000Z",
"process_requested_at": null,
"filename": "100row.csv",
"total_rows": 100,
"affected_rows": 0,
"failed_rows": 0,
"status": "created",
"uploaded_user_name": null,
"proceed_user_name": null,
"uploaded_api_user_name": "zdco_admin",
"proceed_api_user_name": null,
"scheme_errors": [],
"update_errors": []
}
קוד הסטטוס: 200
רשימת משרות
בדוגמה הזו מוסבר איך מקבלים את כל המשרות.
בקשה
כותרות:
| מפתח | ערך | תיאור |
|---|---|---|
| סוג התוכן | application/json |
שאילתה:
Method: GET
Type:
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/
תשובה: רשימת משרות
[
{
"id": 3,
"created_at": "2022-01-07T06:21:10.000Z",
"process_requested_at": "2022-01-07T06:22:25.000Z",
"filename": "100row_new.csv",
"total_rows": 100,
"affected_rows": 0,
"failed_rows": 0,
"status": "in_progress",
"uploaded_user_name": null,
"proceed_user_name": null,
"uploaded_api_user_name": "zdco_admin",
"proceed_api_user_name": "zdco_admin",
"scheme_errors": [],
"update_errors": []
},
{
"id": 2,
"created_at": "2022-01-07T06:17:09.000Z",
"process_requested_at": null,
"filename": "100row.csv",
"total_rows": 100,
"affected_rows": 0,
"failed_rows": 0,
"status": "created",
"uploaded_user_name": null,
"proceed_user_name": null,
"uploaded_api_user_name": "zdco_admin",
"proceed_api_user_name": null,
"scheme_errors": [],
"update_errors": []
},
{
"id": 1,
"created_at": "2022-01-07T06:06:45.000Z",
"process_requested_at": null,
"filename": "100row.csv",
"total_rows": 100,
"affected_rows": 0,
"failed_rows": 0,
"status": "created",
"uploaded_user_name": null,
"proceed_user_name": null,
"uploaded_api_user_name": "zdco_admin",
"proceed_api_user_name": null,
"scheme_errors": [],
"update_errors": []
}
]
קוד הסטטוס: 200
המשימה נוצרה
בדוגמה הזו מוסבר איך לאחזר את המשימות של בקשות משתמשים בכמות גדולה שנוצרו.
בקשה
כותרות:
| מפתח | ערך | תיאור |
|---|---|---|
| סוג התוכן | application/json |
שאילתה:
Method: GET
Type:
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
תשובה: המשימה נוצרה
{
"id": 1,
"created_at": "2022-01-07T06:39:59.000Z",
"process_requested_at": null,
"filename": "100row_new.csv",
"total_rows": 100,
"affected_rows": 0,
"failed_rows": 0,
"status": "created",
"uploaded_user_name": null,
"proceed_user_name": null,
"uploaded_api_user_name": "zdco_admin",
"proceed_api_user_name": null,
"scheme_errors": [],
"update_errors": []
}
קוד הסטטוס: 200
האימות של המשימה הצליח
בדוגמה הזו אפשר לראות איך לוודא שהעבודה בוצעה בהצלחה.
בקשה
כותרות:
| מפתח | ערך | תיאור |
|---|---|---|
| סוג התוכן | application/json |
שאילתה:
Method: GET
Type:
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
תשובה: אימות המשרה הושלם בהצלחה
{
"id": 1,
"created_at": "2022-01-07T06:40:34.000Z",
"process_requested_at": null,
"filename": "100row_new.csv",
"total_rows": 100,
"affected_rows": 0,
"failed_rows": 0,
"status": "valid_scheme",
"uploaded_user_name": null,
"proceed_user_name": null,
"uploaded_api_user_name": "zdco_admin",
"proceed_api_user_name": null,
"scheme_errors": [],
"update_errors": []
}
קוד הסטטוס: 200
האימות של המשרה נכשל
בדוגמה הזו מוסבר איך לזהות משימה שנכשלה.
בקשה
כותרות:
| מפתח | ערך | תיאור |
|---|---|---|
| סוג התוכן | application/json |
שאילתה:
Method: GET
Type:
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
תגובה: אימות המשרה נכשל
{
"id": 1,
"created_at": "2022-01-07T06:40:34.000Z",
"process_requested_at": null,
"filename": "100row_new.csv",
"total_rows": 100,
"affected_rows": 0,
"failed_rows": 0,
"status": "invalid_scheme",
"uploaded_user_name": null,
"proceed_user_name": null,
"uploaded_api_user_name": "zdco_admin",
"proceed_api_user_name": null,
"scheme_errors": [
"scheme error detail 1",
"scheme error detail 2",
"scheme error detail 3"
],
"update_errors": []
}
קוד הסטטוס: 200
עדכון משרה
בדוגמה הזו אפשר לראות איך קובעים אם משימה מתעדכנת.
בקשה
כותרות:
| מפתח | ערך | תיאור |
|---|---|---|
| סוג התוכן | application/json |
שאילתה:
Method: GET
Type:
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
תשובה: עדכון משרה
{
"id": 1,
"created_at": "2022-01-07T06:40:34.000Z",
"process_requested_at": "2022-01-07T06:42:59.000Z",
"filename": "100row_new.csv",
"total_rows": 100,
"affected_rows": 52,
"failed_rows": 0,
"status": "in_progress",
"uploaded_user_name": null,
"proceed_user_name": null,
"uploaded_api_user_name": "zdco_admin",
"proceed_api_user_name": "zdco_admin",
"scheme_errors": [],
"update_errors": []
}
קוד הסטטוס: 200
עדכון המשרה הסתיים ללא שגיאות
בדוגמה הזו אנחנו מראים איך לזהות עבודה שהסתיימה ללא שגיאות.
בקשה
כותרות:
| מפתח | ערך | תיאור |
|---|---|---|
| סוג התוכן | application/json |
שאילתה:
Method: GET
Type:
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
תגובה: עדכון המשרה הסתיים ללא שגיאות
{
"id": 1,
"created_at": "2022-01-07T06:40:34.000Z",
"process_requested_at": "2022-01-07T06:42:59.000Z",
"filename": "100row_new.csv",
"total_rows": 100,
"affected_rows": 100,
"failed_rows": 0,
"status": "finished",
"uploaded_user_name": null,
"proceed_user_name": null,
"uploaded_api_user_name": "zdco_admin",
"proceed_api_user_name": "zdco_admin",
"scheme_errors": [],
"update_errors": []
}
קוד הסטטוס: 200
העדכון של המשרה הסתיים עם שגיאות
בדוגמה הזו אנחנו מראים איך לזהות משימה שהסתיימה עם שגיאות.
בקשה
כותרות:
| מפתח | ערך | תיאור |
|---|---|---|
| סוג התוכן | application/json |
שאילתה:
Method: GET
Type:
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
תגובה: העדכון של המשרה הסתיים עם שגיאות
{
"id": 1,
"created_at": "2022-01-07T06:40:34.000Z",
"process_requested_at": "2022-01-07T06:42:59.000Z",
"filename": "100row_new.csv",
"total_rows": 100,
"affected_rows": 100,
"failed_rows": 0,
"status": "finished",
"uploaded_user_name": null,
"proceed_user_name": null,
"uploaded_api_user_name": "zdco_admin",
"proceed_api_user_name": "zdco_admin",
"scheme_errors": [],
"update_errors": [
"update error detail 1",
"update error detail 2",
"update error detail 3"
]
}
קוד הסטטוס: 200
שגיאה: מזהה המשרה לא תקין
בדוגמה הזו מוצגת בקשה שנכשלה כי מזהה המשימה לא תקין.
בקשה
כותרות:
| מפתח | ערך | תיאור |
|---|---|---|
| סוג התוכן | application/json |
שאילתה:
Method: GET
Type:
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
תגובה: שגיאה: מזהה משרה לא תקין
{
"message": "Not Found"
}
קוד סטטוס: 404
הוספה ועריכה של משתמשים מקובץ בכמות גדולה
כותרות:
| מפתח | ערך | תיאור |
|---|---|---|
| סוג התוכן | multipart/form-data |
נקודת קצה (endpoint):
Method: POST
Type: FORM DATA
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/bulk/users/upload
Body:
| מפתח | ערך | תיאור |
|---|---|---|
| קובץ |
דוגמה לבקשה ולתשובות
בקטעים הבאים מופיעות דוגמאות לבקשות לנקודת הקצה.
המשימה נוצרה
בדוגמה הזו אפשר לראות איך שולחים משימה.
בקשה
Body:
| מפתח | ערך | תיאור |
|---|---|---|
| קובץ |
תשובה: המשימה נוצרה
{
"id": 1,
"status": "created",
"link": "https://{{subdomain}}.{{domain}}/apps/api/v1/bulk/users/jobs/1"
}
קוד הסטטוס: 200
המשך
נקודת הקצה הזו של ה-API משמשת להמשך של עבודת ipport שהתחילה.
נקודת קצה (endpoint):
Method: POST
Type: FORM DATA
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/bulk/users/proceed
כותרות:
| מפתח | ערך | תיאור |
|---|---|---|
| סוג התוכן | multipart/form-data |
Body:
| מפתח | ערך | תיאור |
|---|---|---|
| id | `[job_id}` |
דוגמה לבקשה ולתשובות
בקטעים הבאים מופיעות דוגמאות לבקשות לנקודת הקצה.
המשך הפעולה הושלם בהצלחה
בדוגמה הזו מוצג תהליך עבודה של משרה שהושלם בהצלחה.
בקשה
כותרות:
| מפתח | ערך | תיאור |
|---|---|---|
| סוג התוכן | multipart/form-data |
שאילתה:
| מפתח | ערך | תיאור |
|---|---|---|
| id | `[job_id}` |
תשובה: ההמשך בוצע בהצלחה
{
"id": 1,
"status": "valid_scheme",
"link": "https://{{subdomain}}.{{domain}}/apps/api/v1/bulk/users/jobs/1"
}
קוד הסטטוס: 200
שגיאה: צריך להמשיך לפני האימות
בדוגמה הזו מוצג מעבר לשלב הבא לפני השלמת האימות.
בקשה
כותרות:
| מפתח | ערך | תיאור |
|---|---|---|
| סוג התוכן | multipart/form-data |
שאילתה:
| מפתח | ערך | תיאור |
|---|---|---|
| id | `[job_id}` |
תגובה: שגיאה: צריך להמשיך לפני האימות
{
"message": "This job cannot proceed update. status: created"
}
קוד סטטוס: 400
שגיאה: צריך להמשיך כשהסטטוס הוא 'בתהליך'
בדוגמה הזו מוצגת פעולה להמשך התהליך כשהעבודה כבר בעיצומה.
בקשה
כותרות:
| מפתח | ערך | תיאור |
|---|---|---|
| סוג התוכן | multipart/form-data |
שאילתה:
| מפתח | ערך | תיאור |
|---|---|---|
| id | `[job_id}` |
תגובה: שגיאה: צריך להמשיך כשהפעולה מתבצעת
{
"message": "Update is already in progress."
}
קוד סטטוס: 400
שגיאות בתוכנית
נקודת קצה (endpoint):
Method: GET
Type:
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/bulk/users/errors/scheme/{job_id}
דוגמה לבקשה ולתשובות
בקטעים הבאים מופיעות דוגמאות לבקשות לנקודת הקצה.
שגיאות בתוכנית
בדוגמה הזו אפשר לראות איך מאחזרים את שגיאות הסכימה.
בקשה
Body: None
תגובה: שגיאות בסכימה
[
{
"message": "scheme error message 1",
"column": null,
"row": 1
},
{
"message": "scheme error message 2",
"column": null,
"row": 2
}
]
קוד הסטטוס: 200
אין שגיאות
בדוגמה הזו אפשר לראות איך מאחזרים את שגיאות הסכימה בלי שגיאות.
בקשה
Body: None
תגובה: אין שגיאות
[]
קוד הסטטוס: 200
שגיאות בעדכון
נקודת קצה (endpoint):
Method: GET
Type:
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/bulk/users/errors/update/{job_id}
דוגמה לבקשה ולתשובות
בקטעים הבאים מופיעות דוגמאות לבקשות לנקודת הקצה.
שגיאות בעדכון
בדוגמה הזו אפשר לראות איך מאחזרים את שגיאות הסכימה עם שגיאות העדכון.
בקשה
Body: None
תגובה: שגיאות בעדכון
[
{
"message": "update error message 1",
"column": 1,
"row": 1,
"error_type": "error"
},
{
"message": "update error message 2",
"column": null,
"row": 2,
"error_type": "error"
},
{
"message": "update warning message 1",
"column": 3,
"row": 3,
"error_type": "warning"
},
{
"message": "update warning message 2",
"column": null,
"row": 4,
"error_type": "warning"
}
]
קוד הסטטוס: 200
אין שגיאות
בדוגמה הזו אפשר לראות איך לאחזר את שגיאות הסכימה בלי שגיאות.
בקשה
Body: None
תגובה: אין שגיאות
[]
קוד הסטטוס: 200