הגדרה ובדיקה של פעולות API מותאם

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

איך זה עובד

החיבור שומר את כתובת הבסיס של הספק, את האימות ואת הכותרות המשותפות לבקשות. כל נקודת קצה מגדירה בקשה אחת, את הקלטים שלה, הנחיות ואת שדות התשובה שאתם מרשים לשתף עם הבוט. עצם ההגדרה לא אומרת שהפעולה תשמש בכל שיחה.

נקודות קצה חדשות מתחילות כבויות. לשימוש רגיל בשיחות, גם נקודת הקצה וגם החיבור שלה צריכים להיות במצב מופעל. בדיקה היא פעולה נפרדת: הרצת קריאת ניסיון שולחת בקשה אמיתית גם כשהטיוטה כבויה.

הפעילו מבצעת פעולה אמיתית לכל בקשה שמשנה משהו במערכת החיצונית. לאחר מכן בחרו בנפרד אם להפעיל לבקש אישור מחבר צוות לפני כל קריאה. האישור כבוי בנקודות קצה שנוצרות מאפס; בייבוא וביצירה מתבנית הוא יכול להיות מופעל. בנקודות קצה קיימות שמשנות נתונים הוא נשאר מופעל. המתודה אינה קובעת זאת: ספק יכול להשתמש ב־POST גם לשליפת מידע וגם לשינוי נתונים.

סוכן מחובר מורשה יכול להחמיר או להקל ישירות בדרישות אימות הלקוח ומקור המשתמשים, לפי אותן הרשאות ובדיקות תקינות כמו בעורך באפליקציה. הוא יכול לשנות גם מתודה וסיווג של פעולה אמיתית בנקודת קצה פעילה. הזנת סודות ובדיקות אמיתיות נשארות בצעדים הקיימים באפליקציה; עריכה לא בודקת ולא שולחת דבר. ראו עריכת חיבור להסרת סודות ולכיבוי נקודות קצה אחרי שינוי כתובת או מיקום האימות.

איפה זה נמצא

פתחו הגדרות ← אינטגרציות, בחרו את ספק ה־API המותאם, ואז הגדרות טכניות ואת הפעולה הרצויה. לשונית חיבור פותחת את הגדרות הכתובת והאימות המשותפות; המדריך ← מה [שם העוזר] עושה כש… כולל התאמות להתנהגות וגם את פקד מופעל של הפעולה.

העורך הטכני שומר על מתג מופעל משלו למנהלי אינטגרציות; שני הפקדים עורכים את אותה פעולה. להגדרות הבטיחות — מבצעת פעולה אמיתית, לבקש אישור מחבר צוות לפני כל קריאה וגם הצוות יכול להשתמש בה — יש מקום עריכה אחד לכל אדם: הכלל במדריך אם יש לכם הרשאות עריכה למדריך ולהגדרות הבוט וניהול אינטגרציות; אחרת, מנהלי אינטגרציות עורכים בהגדרות טכניות ← בטיחות. קוראים אחרים במדריך רואים את הבחירות השמורות ללא פקדי עריכה. בנייה ובדיקה של בקשות דורשות הרשאה לניהול אינטגרציות. עריכת כלל במדריך דורשת הרשאת עריכה למדריך והרשאה להגדרות הבוט; למי שאין גישה לפרטי הבקשה וההתחברות עשויים להופיע רק פקדי ההתנהגות. ראו הרשאות.

הגדרה

1. קבלו מהספק את תיעוד הבקשה ורשומות שמתאימות לבדיקה.
2. השלימו את הגדרות החיבור המשותפות.
3. בחרו הוספת נקודת קצה, או השתמשו ב־ייבוא כפי שמוסבר בהמשך.
4. הגדירו כותרת ו־שם הכלי שאינו תפוס בסביבת העבודה.
5. מלאו את ששת השלבים הממוספרים שמוסברים תחת הגדרות.
6. הפעילו מבצעת פעולה אמיתית לפני בדיקה של בקשה שמשנה נתונים.
7. הזינו קלטים בטוחים לדוגמה ובחרו הרצת קריאת ניסיון.
8. בחרו את שדות התשובה שמותר לבוט לקבל.
9. בדקו את האימות, ההנחיות, התאמות ההתנהגות והבחירה באישור לכל קריאה.
10. הפעילו את מופעל רק אחרי שבדקתם את הפעולה ואת החיבור שלה. גם סוכן מחובר יכול להפעיל אותה; הוא מספק קישורים לבדיקה ומדווח על מצב החיבור ואם נמצאו פרטי התחברות שמורים. בדקו בעצמכם את שיטת האימות הנוכחית ואת השדות הנדרשים לה; סימון כפעיל לא מוכיח שהספק מקבל אותם.

העורך שומר שינויים אוטומטית. תקנו שגיאות שמירה לפני היציאה מהעמוד. הבדיקה ממתינה לשמירת שינויים בבקשה; אם השמירה נכשלת, היא לא בודקת גרסה שלא נשמרה.

הגדרות

קהל ואימות

בכל נקודת קצה, למי זה מיועד מוסיף חברות מאושרת בתגיות לצד אפשרויות האימות הקיימות. ברירת המחדל לקהל היא כולם; לפחות אחת מהן או כולן משלבות כמה תגיות. נדרשת עמידה גם בתנאי הקהל וגם בהוכחה. מוסתר עד לעמידה בתנאים מונע את העברת הוראות הפעולה עבור הלקוח עד שהוא עומד בשניהם. העברת בורר ההוכחה לכאן אינה מאפסת את הדרישה השמורה. שינוי הקהל של פריט קיים דרך סוכן מחובר דורש שלב הרשאה באפליקציה; הגדרות ההוכחה נשארות ניתנות לעריכה ישירה באותן הרשאות.

ברירות המחדל הבאות מתייחסות ל־הוספת נקודת קצה. פעולות שיובאו ותבניות מוכנות יכולות לכלול ערכים אחרים, ולכן צריך לבדוק כל אחת בנפרד.

שם הפעולה ומופעל

הגדרה	מה היא עושה	ערך התחלתי
כותרת	שם קריא ברשימת הפעולות. אם הוא ריק, הרשימה משתמשת בשם הכלי.	ריק.
שם הכלי	השם הקבוע שמשמש לקריאה לפעולה. השתמשו ב־2–61 תווים: אות אנגלית קטנה בהתחלה, ובהמשך אותיות אנגליות קטנות, ספרות וקווים תחתונים. השם לא יכול להיות זהה לשם של פעולה אחרת או לשם כלי שמור בסביבת העבודה.	new_endpoint, עם סיומת לפי הצורך.
מופעל	מאפשר שימוש רגיל בפעולה בשיחות, בתנאי שגם חיבור הספק מופעל. ההפעלה לא שולחת בקשה עכשיו.	כבוי.

1. מה היא עושה

תיאור (מסביר לעוזר מתי להשתמש בכלי) מתאר את מטרת הפעולה ואת הקלטים שלה. הוא מתחיל ריק. תארו מה הבקשה באמת עושה ומתי היא רלוונטית, ולא רק ״API משלוחים״. למשל: ״בדיקת משלוח לפי מספר מעקב והחזרת המצב הנוכחי שלו״.

אל תכניסו סיסמאות או מפתחות לתיאורים ולהנחיות.

2. איך הבוט משתמש בה

הגדרה	מה היא עושה	ברירת מחדל
התנהגות ברירת מחדל	ההנחיות שלכם לגבי מתי ואיך להשתמש בפעולה. הן נפרדות מההגדרות הטכניות של הבקשה.	ריק.
איך לקרוא תשובות	הסבר לערכי המצב ולשדות שהספק מחזיר, כולל מה מציין תוצאה עסקית שלא הצליחה. עד 2,000 תווים.	ריק; ללא הנחיות פרשנות נוספות.
לפני הקריאה, הלקוח חייב להיות	קובע את דרישת האימות או השייכות שמוסברת בהמשך.	כולם.
האימות תקף	קובע אם אפשר להסתמך על אימות מתאים משיחה קודמת.	כל אימות קודם.

בכלל הפעולה המותאמת במדריך, השדה איך הבוט צריך להשתמש בה מאפשר התאמת התנהגות. טקסט שאינו ריק מחליף את התנהגות ברירת מחדל; מחיקתו מחזירה את ברירת המחדל. הוא לא מחליף את הבקשה, את התיאור, את השדות המשותפים או את איך לקרוא תשובות. בקרות האימות שם עורכות את אותה דרישה של הפעולה, ולא מוסיפות בדיקה נפרדת.

תשובות אמיתיות אחרונות מוצג כשיש דוגמאות ויש לכם הרשאה לניהול האינטגרציה. הוא מציג תשובות אחרונות לבקשות אמיתיות מתוך שיחות, עם קוד HTTP וזמן הקבלה. קריאות ניסיון מהעורך לא ממלאות את ההיסטוריה הזאת. תשובה עשויה להיות מסומנת כמושמטת אם לא ניתן היה לשמור אותה במלואה. היעזרו בדוגמאות לשיפור הנחיות הפרשנות, והתייחסו אליהן כמידע שעשוי לכלול פרטי לקוחות. סודות האימות השמורים מושחרים בהיסטוריה הזאת; אין בכך הבטחה שכל מידע אישי הוסר.

אפשרויות אימות לקוח

הדרישות שאפשר לבחור הן:

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

בשתי אפשרויות השייכות, בחרו ספק מסוים או כל ספק. בחירה בספק מסוים לא מאפשרת מעבר לספק אחר. עם ספק מסוים, אפשר לדרוש דרך תפקידים (אחד מהם) אחד מערכי התפקידים שהספק כבר החזיר בפועל; אותה התאמה לחשבון צריכה לעמוד גם בבדיקת התפקיד.

בחירת דרישות שייכות ועריכת תפקידים עשויות להיות לא זמינות במהלך ההשקה. דרישות שכבר נשמרו ממשיכות לחול, ושינוי שדה אחר לא מסיר אותן. ראו זיהוי משתמשים להגדרה ולזמינות.

כל אימות קודם מאפשר להסתמך על אימות מתאים קודם שעדיין בתוקף. בשיחה הזו דורש שהאימות הושג בשיחה הנוכחית. ברירת מחדל (כל אימות קודם) זהה לאפשרות הראשונה. חלק מהתבניות המיובאות עשויות להציג מספר במקום זאת; זהו משך זמן בשניות, ולא רמת אימות נוספת.

אימות הלקוח נפרד מהבחירה ב־זהות מאומתת כמקור לקלט. קלט זהות שמסומן כחובה עדיין דורש את הערך המאומת המסוים שלו, גם אם הפעולה מוגדרת כולם.

3. בקשה

הגדרה	מה היא עושה	ברירת מחדל
מתודה	מתודת ה־HTTP שהספק דורש: GET, POST, PUT, PATCH או DELETE.	GET.
תבנית נתיב	הנתיב היחסי שמתווסף לכתובת הבסיס של החיבור. עבור /deliveries/{tracking_number}, הוסיפו פרמטר בשם tracking_number שנשלח בנתיב. אל תדביקו כאן כתובת בסיס מלאה נוספת.	/.
מבנה גוף הבקשה	מופיע עבור POST, PUT, PATCH ו־DELETE. JSON שולח אובייקט JSON; מקודד-טופס שולח זוגות שם וערך במבנה של טופס. התאימו לתיעוד הספק.	JSON.

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

בגוף JSON, פרמטר בשם customer.email יוצר אובייקט מקונן, שבו email נמצא בתוך customer. במבנה מקודד-טופס, שם עם נקודות נשאר שם שטוח. בקשת JSON בשיטת POST, PUT או PATCH שולחת אובייקט ריק ({}) גם כשאין קלטים בגוף הבקשה. סוג תוכן JSON שהוגדר במפורש נשמר; אחרת נשלח application/json. בקשות GET, DELETE ובקשות מקודדות-טופס ללא קלטים אינן שולחות גוף. ערכים בנתיב מקודדים כמקטע אחד, כך שרווח או לוכסן בתוך ערך לא משנים את מבנה הנתיב.

כותרות ברירת מחדל ו־אימות שייכים לחיבור וחלים על כל הפעולות שלו. כששם כותרת חוזר, כותרות ברירת המחדל של החיבור גוברות על קלטי הכותרות של נקודת הקצה, וכותרות האימות גוברות על שניהם. קלטי שאילתה מחליפים ערכים בעלי אותו שם בכתובת הבסיס של החיבור; שאר ערכי השאילתה נשמרים. מפתח אימות שנשלח בשאילתה גובר על שניהם. שנו פרטי התחברות בשדות האימות של החיבור, ולא בקלט מתוך שיחה. ראו אפשרויות חיבור ואימות.

4. קלטים

בחרו הוספת פרמטר לכל קלט שהספק מצפה לקבל. הסרת פרמטר מסירה שורה. לכל קלט חייבים לבחור מיקום בבקשה ו־ממולא מתוך. אין להשאיר אותם חסרים או להוסיף רווחים לפני שם הקלט או אחריו.

שדה	מה הוא עושה	ברירת מחדל לשורה חדשה
שם	השם המדויק שהספק מצפה לו. קלט בנתיב חייב להתאים למציין המקום, בלי הסוגריים המסולסלים. אל תחזרו על אותו שם באותו מיקום בבקשה.	ריק.
משמעות	הסבר פשוט לקלט, במיוחד למידע שצריך לקחת מתוך השיחה.	ריק.
מיקום בבקשה	נתיב ממלא מציין מקום; שאילתה מוסיפה ערך לכתובת; כותרת שולחת כותרת בבקשה; גוף שולח שדה בגוף הבקשה.	שאילתה.
ממולא מתוך	בחירה בין ערך קבוע, מתוך השיחה ו־ערך מ־omotto. בשורות זהות קיימות נשארת גם זהות מאומתת.	מתוך השיחה.
סוג	כל סוג (כפי שנשלח) שומר על הסוג שסופק. בחרו טקסט, מספר שלם, מספר או כן/לא לפי מה שהמערכת המקבלת מצפה לקבל.	כל סוג (כפי שנשלח).
ערך	מופיע עבור ערך קבוע. שולח את הערך שהגדרתם במקום לאסוף אותו מהשיחה. במספר שלם ובמספר מזינים מספר; בכן/לא בוחרים כן או לא.	לא הוגדר.
ערך מ־omotto	בחירת מידע שכבר נמצא במערכת. ערכים מאומתים מסומנים, וערכים כפי שנמסרו מציגים אזהרה.	ללא בחירה.
מקור זהות	מופיע בשורת זהות מאומתת קיימת.	המקור השמור.
חובה	מונע את הבקשה כשערך מתוך השיחה, ממקור זהות או מהמערכת חסר או ריק. גם ערך קבוע שמסומן כחובה חייב להיות מלא לפני הפעלה. קלט בנתיב תמיד נדרש, גם כשהמתג כבוי.	כבוי.

בחירה בטקסט שולחת טקסט גם כשהקלט הוא מספר; ערך מובנה שלם הופך לטקסט JSON. מספר שלם, מספר וכן/לא שולחים מספרים או ערכי אמת בגוף JSON, ואת הצורה הטקסטואלית שלהם במיקומים אחרים בבקשה. אם הבוט מספק ערך שלא ניתן להמיר, הבקשה לא נשלחת. הבוט מקבל את שם השדה כדי שיוכל לתקן את הקריאה. ערך קבוע מהסוג הלא מתאים נדחה בשמירה. מספרים שלמים קבועים מחוץ לטווח ±9,007,199,254,740,992, או מספרים עשרוניים עם יותר מ־15 ספרות משמעותיות, נדחים במקום להתעגל. למזהים ולמספרים ארוכים בחרו טקסט. ערך טקסט קבוע שאינו חובה יכול להיות ריק: הוא נשלח כטקסט ריק ולא מושמט.

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

ערך מ־omotto שולח מידע שכבר נמצא במערכת, בלי לבקש מהבוט לנחש אותו. בחרו את הערך שהמערכת השנייה מצפה לקבל:

• מזהה שיחה או קישור לאינבוקס, ערוץ השיחה ושפת הלקוח.
• מזהה הקו או שמו, ומזהה סביבת העבודה או שמה.
• מזהה הטיקט הפתוח הנוכחי או קישור אליו, אם יש טיקט כזה.
• מזהה לקוח ושם הלקוח כפי שנמסר.
• טלפון או דוא״ל מאומתים של הלקוח.
• טלפון או דוא״ל כפי שהוקלדו — ייתכן שאינם שלו. אלו ערכים נפרדים מהפרטים המאומתים.
• מספר ההזמנה האחרון בחנות, שמסומן לא מאומת. החיפוש בחנות עשוי להשתמש בכתובת מפרופיל הלקוח; הוא לא מוכיח בעלות.

למשל, הוסיפו external_id, בחרו ערך מ־omotto ואז מזהה שיחה. המערכת השנייה מקבלת את המזהה הקבוע של השיחה ויכולה להשתמש בו כדי למנוע יצירת אותה בקשה פעמיים. אין צורך לבקש מהבוט להמציא מזהה.

שם הלקוח ופרטים כפי שנמסרו אינם אימות. מזהה חשבון וואטסאפ אינו מספר טלפון. גם בחירה בערך מאומת לא מאמתת את הלקוח בעצמה. אם ערך חובה אינו זמין, הבקשה לא נשלחת. ערך לא זמין שאינו חובה פשוט לא נשלח.

קלטי זהות מאומתת קיימים ממשיכים לעבוד. טלפון מאומת ו־אימייל מאומת מקבילים לערכים המאומתים ברשימה החדשה. מספר הזמנה בשופיפיי שומר על התנהגות החיפוש הקיימת ואינו הוכחת זהות. שורות קיימות של מזהה המשתמש התואם נשארות קשורות לחשבון שעבר את בדיקת ה־ספק שנבחר לפעולה, תחת משתמש מאומת, ולא למזהה שהוקלד בשיחה.

הוספה, הסרה או שינוי של קלט מהמערכת דרך סוכן מחובר נשמרים ישירות, כמו עריכה באפליקציה. כך גם כשהסוכן יוצר או מייבא פעולה. בתוצאה כתוב אילו ערכים הפעולה תשלח ולאיזה יעד. זהו מידע לידיעתכם, לא בקשה לאישור. מעבר בין שתי צורות כתיבה שקולות אינו משנה את המידע שנשלח.

ביטול שינוי שאינו קשור לאימות דרך סוכן מחובר אינו מבקש לאשר מחדש הגדרות אימות לקוח שלא השתנו. אם הביטול ישנה בפועל את תנאי זיהוי המשתמש, משלימים את השינוי באפליקציה.

לכל פעולה אפשר להגדיר עד 100 קלטים. שם של קלט יכול להכיל עד 200 בתים שמורים, ולא בהכרח 200 תווים: תווים מסוימים תופסים יותר מבית אחד. אם פעולה קיימת חורגת מהמגבלה, עדיין אפשר לשנות הגדרות שאינן קשורות לקלטים או לכבות אותה. תקנו את הקלטים לפני שינוי ההגדרה או הפעלה מחדש.

לכל מציין מקום בנתיב חייב להיות קלט אחד תואם שנשלח בנתיב. שמרו על שם הקלט המדויק של הספק, כולל מקפים, נקודות או אותיות שאינן באנגלית. שמות כותרות משתמשים באותיות באנגלית, בספרות או בסימני HTTP כמו מקף, בלי רווחים, נקודתיים או אותיות בשפות אחרות. ערכי כותרת קבועים אינם יכולים לכלול ירידות שורה או תו אפס (NUL). שמות כותרות נחשבים כפולים גם כשההבדל הוא רק באותיות גדולות וקטנות. בגוף JSON, אל תגדירו גם אובייקט שלם כמו client וגם שדה בתוכו כמו client.email.

אם נדרש אישור צוות וערך מהמערכת משתנה בזמן ההמתנה, omotto לא מריצה את הבקשה שהשתנתה מכוח האישור הישן. יש להציע אותה מחדש עם הערכים העדכניים.

5. בדיקה ובחירת מה שהבוט רואה

1. תחת קריאת ניסיון, הזינו ערכים לדוגמה לקלטים מהשיחה, למקורות הזהות ולערכים מ־omotto.
2. בחרו הרצת קריאת ניסיון.
3. אם מופיע להריץ פעולה אמיתית?, אשרו רק אם אתם מתכוונים לבצע את השינוי במערכת החיה.
4. בדקו את קוד ה־HTTP ואת דוגמאות השדות שהוחזרו.
5. סמנו כל שדה שמותר לבוט לקבל.
6. הוסיפו תווית לפי הצורך כדי להבהיר את משמעותו של שדה שנבחר.
7. פתחו תגובה גולמית אם צריך לראות את ה־JSON המלא שהוחזר.
8. השתמשו ב־העתקת JSON רק אם בטוח להעתיק את המידע הזה.

הבדיקות משתמשות בחיבור ובאימות האמיתיים. ערכי הזהות שאתם מזינים כאן הם דוגמאות: בדיקה שהצליחה לא מוכיחה שללקוח יש פרטים מאומתים או שקריאה בשיחה תעבור את בדיקת האימות. בדיקת פעולה שמשנה נתונים נעשית באישור מפורש שלכם, ולא דרך תהליך אישור הצוות של שיחת לקוח.

הרשימה מתחילה בלי שדות משותפים. בחירה ריקה לא משתפת את התשובה כולה. הבוט מקבל את קוד ה־HTTP ואת הנחיות הפרשנות, אם הוגדרו, אבל לא שדות מגוף התשובה. זה נכון גם לפעולות כתיבה שנכשלו: בחרו שדה שגיאה, למשל error, אם הבוט צריך את הפרט הזה. בחירה ריקה או שדה שלא נמצא לא משתפים את גוף התשובה. תשובה גדולה או לא קריאה עשויה להיות מושמטת; דוגמאות תשובה מלאות נשארות זמינות רק למנהלי האינטגרציה. בנפרד, פעולה אמיתית שנכשלה משאירה באינבוקס עותק שגיאה לצוות בלבד, אחרי הסתרת סודות התחברות ופרטי לקוח מוכרים, גם כשלא משתפים שדות עם הבוט. העותק הזה לא נשלח ללקוח ולא נמסר לבוט. שתפו רק את הנתונים שנחוצים למשימה. השאירו הערות פרטיות, פרטי התחברות ועלויות פנימיות מחוץ לבחירה.

• אובייקטים מקוננים מציגים את השדות שלהם בנפרד, למשל customer.name.
• בשדות של מערך אפשר לבחור כל פריט או הראשון בלבד, אחרי סימון השדה. האפשרות הראשונה משתפת את השדה בפריטים שהוחזרו; השנייה רק בפריט שבמקום אפס. היא לא בוחרת עבורכם את הפריט החדש או המתאים ביותר.
• גם אוספים שהמפתחות שלהם הם מזהים יכולים להציע שדות לכל פריט, אבל לא את האפשרות הראשון בלבד. תשובות גדולות עשויות להתקצר; בחירה בכל פריט לא מבטיחה שהבוט יקבל את כל התוצאות באוסף גדול.
• אפשר לבחור שדות מתוך אובייקטים מקוננים בפריטי אוסף. מערכים מקוננים לא נפתחים אוטומטית לשדות ברשימה.
• שדה שכבר נבחר ולא הופיע בתשובה האחרונה נשאר ברשימה עם הסימון מוגדר, אך לא הופיע בתגובה הזו. הוא לא נמחק בשקט.
• לשדה חסר או עמוק יותר, בחרו ＋ הוספת שדה לפי נתיב (מתקדם), הזינו נתיב כמו status,‏ events[0].city או events[*].city, ואז בחרו הוספה. הדוגמה האחרונה משתפת את city בכל פריטי המערך. נתמכת רק רמה אחת של בחירת כל הפריטים. תקנו שגיאות נתיב שמוצגות.
• בחירת אובייקט או מערך שלם באמצעות נתיב מתקדם יכולה לשתף את התוכן שלו, ולא רק שדה בודד. העדיפו שדות נפרדים כשחלק מהתוכן פרטי.

הצפייה בתגובה הגולמית מיועדת למי שמנהלים את האינטגרציה. היא לא משנה אילו שדות משותפים עם הבוט. תשובות יכולות להכיל פרטי לקוחות או מידע שהספק החזיר כפי שקיבל; בדקו אותן לפני העתקה או שליחה לתמיכה.

6. בטיחות

הגדרה	מה היא עושה	ברירת מחדל
מבצעת פעולה אמיתית	מסמנת בקשה שמשנה את המערכת החיצונית. הפעילו עבור יצירה, עדכון, ביטול או מחיקת נתונים, בלי קשר למתודה. הסימון לבדו לא מחייב אישור לכל קריאה.	כבוי. עליכם לסווג את הפעולה נכון.
לבקש אישור מחבר צוות לפני כל קריאה	בפעולה אמיתית, ממתינה לאישור של חבר צוות לכל קריאה בשיחת לקוח. כרטיס אישור תואם שממתין מבוטל כשהבוט משתמש שוב בפעולה ללא דרישת אישור; אי אפשר לאשר את הכרטיס הזה עוד.	כבוי בנקודות קצה שנוצרות מאפס. בייבוא וביצירה מתבנית הוא יכול להיות מופעל; נשאר מופעל בנקודות קצה קיימות שמשנות נתונים.
גם הצוות יכול להשתמש בה	מאפשר שימוש בפעולת קריאה בלבד בערוץ הצוות. שימוש הצוות לא דורש אימות לקוח, אבל קלטי זהות שמסומנים כחובה עדיין זקוקים לערך זמין.	כבוי. הפעלת מבצעת פעולה אמיתית מכבה את המתג ומונעת את הפעלתו.

הנחיות טקסט אינן תחליף למתגים האלה. POST לא נחשב אוטומטית לפעולת כתיבה, ונקודת קצה כבויה אינה סביבת ניסוי מבודדת.

לבקש אישור מחבר צוות לפני כל קריאה חל רק על פעולת ה־API המותאם הזאת. שינוי ההגדרה אינו משנה את האישורים של היכולת המובנית לתיקון כתובת משלוח ופרטי קשר בהזמנת Shopify, ואינו מעניק לה גישה לחנות. הגדירו בנפרד את יכולת Shopify המובנית, את מדיניות החנות שלה ואת הרשאות Shopify הנדרשות; אישור קריאת API מותאם אינו מחליף אותם.

מה קורה כש…

יש בעיות בהגדרת הפעולה

העורך מציג יש לתקן את הפעולה לפני שהבוט יוכל להשתמש בה, עם השדות שדורשים תיקון. הודעת הסירוב מציינת שדה, למשל params[2].source, כדי שמי שמגדיר את הפעולה יוכל לתקן את הקלט המסוים. הכלל חל גם על הגדרות שיצר סוכן מחובר.

פעולה עם בעיות בהגדרה אינה זמינה לבוט. פעולות תקינות אחרות נשארות זמינות. קריאת ניסיון לא שולחת בקשה עד לתיקון ההגדרה; ערכי דוגמה אינם מסתירים מקור זהות שגוי. אפשר לשמור טיוטה כבויה כשערך קבוע שמסומן כחובה עדיין חסר, אבל חייבים למלא אותו לפני הפעלה. תמיד אפשר לכבות פעולה כשזה השינוי היחיד, גם אם ההגדרה שלה דורשת תיקון.

בדיקה מצליחה, נכשלת או שהבקשה משתנה

נבדק אומר שהבדיקה האחרונה החזירה HTTP בטווח 200–299 ושהגדרת הבקשה עדיין עדכנית. פעיל אומר שנקודת הקצה והחיבור מופעלים; זו לא הבטחה שהבדיקה הצליחה. במקרים אחרים הפעולה מוצגת כ־טיוטה, אלא אם היא מתאימה להצגת נבדק.

שינוי מתודה, תבנית נתיב, מבנה גוף הבקשה או פרמטרים מוחק את תוצאת הבדיקה הישנה. גם שינויים בכתובת החיבור, באימות או בכותרות המשותפות מבטלים את תוקף הבדיקות הרלוונטיות. עריכת התיאור, ההתנהגות או שדות התשובה לא מוחקת את בדיקת הבקשה; בדקו אותם בנפרד. אין תנאי שמחייב בדיקה מוצלחת לפני הפעלת נקודת קצה.

גם תשובה עסקית כמו HTTP 404 יכולה לכלול JSON שימושי לבחירת שדות ולהנחיות פרשנות. היא לא מקבלת סימון של בדיקה מוצלחת. כשלי אימות, הגבלת קצב וכשלי שרת נשארים שגיאות. כשאין קוד HTTP, בדרך כלל לא התקבלה תשובה שימושית מהשירות.

פעולה בשיחת לקוח נדחית או שלא מתקבלת תשובה

אישור הוא רשות לנסות, לא הוכחה להצלחה. בקשה שהשירות דחה נרשמת כלא בוצעה ומופיעה בשיחה; הבוט יכול לנסות שוב אחרי תיקון, או שחבר צוות יכול להציע אותה מחדש. גם שגיאת שרת לא מסומנת כהצלחה, אבל לפני ניסיון נוסף צריך לבדוק אם הפעולה בוצעה בחלקה.

בקשה שנשלחה ולא התקבלה עליה תשובה היא בעלת תוצאה לא ידועה. ייתכן שהיא בוצעה. הניסיון הזה לעולם לא נשלח שוב אוטומטית; חבר צוות בודק ומחליט אם לאשר הצעה חדשה. הרישום קיים גם כשאישור לכל קריאה כבוי. ראו פעולות שנכשלו ותוצאות לא ידועות להסבר המלא.

מייבאים או מייצאים פעולות

ייבוא מקבל פקודת cURL,‏ מפרט OpenAPI (בגרסה 3, בפורמט JSON או YAML),‏ אוסף Postman או תבנית omotto (.json). מפרטים ישנים יותר, כולל Swagger 2.0, דורשים המרה ל־OpenAPI 3 לפני הייבוא. פקודת cURL מתארת בקשה; OpenAPI מתאר ממשק; אוסף Postman מרכז בקשות שמורות. ראו את המדריך הרשמי של cURL, את מפרט OpenAPI ואת מדריך הייצוא של Postman.

1. בחרו את פורמט הייבוא.
2. הדביקו את המקור. ב־OpenAPI ובתבניות omotto יש גם אפשרות לבחור קובץ; ב־OpenAPI אפשר גם לטעון מכתובת.
3. בחרו תצוגה מקדימה.
4. קראו את האזהרות והשאירו מסומנות רק את הפעולות הרצויות.
5. בחרו ייבוא הנבחרים.
6. בדקו כל פעולה שיובאה לפני בדיקה או הפעלה שלה.

תבנית omotto לא תקינה נדחית לפני שמייבאים ממנה דבר. השגיאה מציינת איזה שדה לתקן; omotto לא מחליף מקור קלט, שיטת התחברות או רמת אימות לא מוכרים בברירת מחדל. ערכים קבועים שהוסתרו נשארים כטיוטות כבויות, גם כשהקלט אינו שדה חובה. מלאו אותם ובדקו מקורות לא קשורים של זיהוי משתמשים לפני הפעלת פעולה.

הייבוא יוצר נקודות קצה כבויות. חיבור חדש שיובא מתחיל מופעל אם הכתובת כוללת שם שרת; חיבור שעדיין אין לו שם שרת מתחיל כבוי. הוא אינו כולל סודות התחברות שמורים; השלימו את פרטי ההתחברות הנדרשים לפני השימוש. ייבוא לחיבור קיים שומר את פרטי ההתחברות ואת כתובת הבסיס של אותו חיבור; בדקו אזהרה על הבדל בכתובות, אם מופיעה.

ייבוא מ־cURL, מ־OpenAPI ומ־Postman מתחיל ללא שדות תשובה משותפים ועם מבצעת פעולה אמיתית כבוי. תקנו את המתג הזה לפני בדיקה של פעולת כתיבה אמיתית. תבניות omotto יכולות לשמור התנהגות, שדות משותפים, מקורות זהות ואת הבחירה באישור לכל קריאה, אבל נקודות הקצה שלהן עדיין מגיעות כבויות. בתבניות ישנות ללא בחירת אישור, האישור נשאר מופעל עבור פעולות אמיתיות.

במסך הבדיקה מופיעות הערות על שדות מתחת לכל פעולה. הערות על בקשות שהושמטו מהאוסף מופיעות מעל הרשימה. לצד התווית המתורגמת נשמרים כתובת השדה והפרט הספציפי, כדי שתוכלו לזהות את הקלט שהושפע. כתובת כמו params[2].source מציינת את השדה. קראו את ההערות לפני ייבוא הנבחרים; הן מסבירות שינויים, ולא מתקנות את ההגדרות בעצמן.

• מלאו כותרות וכל קלט זהות שהוחלף בערך קבוע. בדקו קלטי נתיב שנוספו וקלטים שהועברו לשאילתה.
• הוסיפו ידנית מידע שהושמט מעוגיות או מגוף הבקשה, אם הוא נחוץ. בקשות בפרוטוקול, במארח או ביציאה אחרים צריכות חיבור נפרד.
• בדקו מערכים, אובייקטים מקוננים עמוק וערכים ריקים: הם הופכים לטקסט. גם מספרים ארוכים או מדויקים מאוד הופכים לטקסט כדי לשמור על כל הספרות.
• בתבנית omotto, קשרו מחדש קלטים ודרישות של חשבון משתמש להגדרת זיהוי המשתמשים של סביבת העבודה הזו לפני ההפעלה.

משתני Postman הופכים לקלטים שנקראים על שם השדה שנשלח: email={{customer_email}} הופך לקלט בשם email, ולא customer_email. גם משתני כותרת שומרים על שם הכותרת המדויק שנשלח, למשל X-Customer, ושם המשתנה נשמר בתיאור. מספרים וערכי כן/לא ב־JSON שומרים על הסוג שלהם, גם בדוגמאות שבתוך מערכים או אובייקטים עמוקים שמוצגים כטקסט. ייבוא OpenAPI שומר על שדות חובה מקוננים ומשתמש בהגדרת הפרמטר של הפעולה כשהיא מחליפה הגדרה משותפת. cURL תומך ב־--data-urlencode ושומר כמה שדות נתונים; כשיש נתונים, הבקשה היא POST אלא אם הפקודה קובעת שיטה אחרת.

ייצוא תבנית מייצא הגדרות לשימוש חוזר, בלי סודות האימות השמורים של החיבור. הקובץ עדיין יכול לכלול ערכי קלט קבועים, כותרות ברירת מחדל, כתובות וטקסט הנחיות. בדקו אותו לפני שיתוף. אל תניחו שסודות שהודבקו במקומות האלה יוסרו. באותו אופן, הסירו סודות ומידע אישי שאינם נחוצים מחומר המקור לפני ייבוא; הייבוא אינו מנגנון כללי לניקוי סודות.

מסירים פעולה

בחרו פעולות נוספות ← הסרת נקודת קצה ואשרו. אי אפשר לבטל את ההסרה. אם הפעולה נבחרה כמקור לזיהוי משתמשים, בחרו קודם מקור אחר.

פתרון בעיות

מה קורה	מה לבדוק
חסר קלט או מופיעה שגיאת נתיב	ודאו שלכל מציין מקום כמו {placeholder} יש פרמטר בנתיב עם אותו שם. מלאו ערכי דוגמה נדרשים. בדקו את מיקום בבקשה ואת ממולא מתוך.
שגיאה בהגדרות החיבור	פתחו ניהול החיבור ותקנו את כותרות ברירת המחדל, את שם כותרת האימות או את ערכי ההתחברות השמורים. שמות הכותרות לא יכולים להכיל רווחים או ירידות שורה; הערכים לא יכולים להכיל ירידות שורה או תווי null. שינוי ערכי הדוגמה לא מתקן את הגדרות החיבור.
כשל באימות, HTTP 401 או 403	בדקו את מצב החיבור. נדרש טיפול מפנה לתיקון פרטי ההתחברות: הזינו את הפרטים הנכונים מחדש או הריצו בדיקה מוצלחת עם הפרטים הנוכחיים. בדקו את שיטת האימות, שם הכותרת או הפרמטר והרשאות אצל הספק. תשובת 403 לבדה לא מסמנת את החיבור כתקול; ייתכן שרק הפעולה המסוימת אינה מותרת. הזינו מחדש פרטי התחברות אחרי ייבוא חיבור חדש או שינוי סוג האימות שלו; שינוי הסוג מוחק את פרטי הגישה השמורים.
נתיב שגוי או תוצאה עסקית לא צפויה	בדקו את השילוב של כתובת הבסיס והנתיב, את המתודה ואת מבנה גוף הבקשה. קראו את תשובת הספק והסבירו את משמעותה העסקית תחת איך לקרוא תשובות.
הבדיקה מצליחה אבל קריאות לקוח נעצרות	ערכי זהות לדוגמה עוקפים את אימות הלקוח בבדיקה. בדקו טלפון או אימייל מאומתים של הלקוח האמיתי, את תוקף האימות ואת קלטי הזהות הנדרשים. אל תחלישו הגנה על מידע פרטי רק כדי לעבור בדיקה.
הבוט לא מקבל מידע שימושי מהתשובה	סמנו שדות ברשימה. בדקו נתיבים אמיתיים בתשובה, שדות חסרים ובחירה בכל פריט לעומת הראשון בלבד. כתיבת הנחיות פרשנות לא משתפת שדות שלא נבחרו.
הפעולה לא זמינה	בדקו את שני מתגי מופעל. בדיקה מוצלחת לא מפעילה דבר בפני עצמה. לשימוש בערוץ הצוות, בדקו את גם הצוות יכול להשתמש בה.
הכתובת חסומה או שהשירות לא נגיש	בקשו מהספק את כתובת ה־HTTPS הציבורית הנתמכת שלו ובדקו שהשירות זמין. פנו לתמיכה אם כתובת ציבורית מתועדת עדיין נחסמת.

בפנייה לתמיכה, ציינו את כותרת הפעולה, את זמן הבדיקה המשוער, את קוד ה־HTTP ותיאור מצונזר של הבעיה. אל תשלחו סודות התחברות או תשובות גולמיות עם פרטי לקוחות שלא בדקתם.

ראו גם

• חיבור מערכת חיצונית באמצעות API מותאם
• חיבור סוכן AI משלכם
• אימות וזיהוי משתמשים
• ערוץ הצוות
• אוטומציות
• פעולות דרך Zapier, Make או n8n