חיבור המערכת שלכם באמצעות API מותאם

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

איך זה עובד

יש שני חלקים:

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

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

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

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

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

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

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

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

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

איפה זה נמצא

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

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

הגדרה

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

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

לפני שמתחילים

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

מתחילים מאפס

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

שינויים בחיבור נשמרים אוטומטית. שדות סוד נשמרים כשעוזבים את השדה לאחר מילוי פרטי התחברות מלאים. ב־HTTP Basic מלאו גם שם משתמש וגם סיסמה; ב־OAuth2 (client credentials) מלאו גם Client ID וגם Client Secret. זוג שמולא רק בחלקו לא נשמר.

מתחילים מתבנית

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

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

מייבאים הגדרה מוכנה

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

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

אפשרות ייבוא	מה מספקים
פקודת cURL	מדביקים פקודה שמתארת בקשה, שקיבלתם ממי שמתחזק את המערכת השנייה.
מפרט OpenAPI	תיאור של השירות בגרסה 3, בקובץ JSON או YAML. אפשר להדביק, להשתמש ב…או משיכה מכתובת (OpenAPI), או ב…או בחירת קובץ.
אוסף Postman	מדביקים את תוכן ה־JSON של אוסף בקשות מוכנות.
תבנית omotto (.json)	מדביקים או בוחרים קובץ שיוצא קודם מ־omotto. הוא כולל הגדרות התנהגות ובטיחות של omotto לצד הבקשות.

JSON ו־YAML הם סוגי קבצים. בקשו ממי שמתחזק את המערכת קובץ מתאים; לא צריך לכתוב אותו בעצמכם.

משיכה של מפרט מקישור מוגבלת ל־2 MB. השתמשו בקישור HTTPS ציבורי שפותח את הקובץ ישירות; קישורים שמפנים לכתובת אחרת נדחים. אם הקובץ גדול יותר, בקשו מהאיש הטכני מפרט קטן יותר.

כשפותחים ייבוא מתפריט ההוספה, הבחירה ההתחלתית היא פקודת cURL. בחירת קובץ זמינה למפרט OpenAPI ולתבנית omotto, ולא ל־cURL או Postman. אם מילאתם את שדה הכתובת, הייבוא משתמש בה במקום בטקסט שהודבק; נקו אותה כדי להשתמש בטקסט.

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

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

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

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

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

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

מגדירים נקודת קצה שהבוט יכול לקרוא לה

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

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

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

לבחירתכם: בדיקת ההתנהגות שבחרתם

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

הגדרות

קהל ואימות

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

הגדרות החיבור

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

הגדרה	מה היא עושה	ערך התחלתי
שם	השם של החיבור בתוך omotto.	ספק חדש, עם מספר נוסף אם צריך.
כתובת בסיס	הכתובת המשותפת שאליה מצורפים נתיבי הפעולות. השתמשו בכתובת מהספק, כולל נתיב בסיס אם הוא נדרש.	`https://`, כתובת שעדיין אינה מלאה.
מופעל	מאפשרת להציע לבוט את נקודות הקצה הפעילות, אחרי שנשמרו פרטי ההתחברות הנדרשים לשיטת האימות שנבחרה. כיבוי מפסיק את הזמינות בלי למחוק את ההגדרה. פרטי התחברות חסרים לא מונעים את הדלקת המתג.	מופעל כשנוצר עם שם שרת בכתובת, גם בייבוא; כבוי כל עוד אין שם שרת, למשל בטיוטת `https://` הלא מלאה. השלמת טיוטה קיימת לא מפעילה אותה אוטומטית.
אימות	הדרך שבה omotto מזדהה בשם העסק מול המערכת השנייה. זה נפרד מאימות זהות של לקוח.	אסימון Bearer.
כותרות ברירת מחדל	פרטים בעלי שם שנשלחים בכל בקשה, למשל סוג התשובה הרצוי או גרסת השירות. השמות צריכים להיות שמות כותרת תקינים, כמו `Accept` או `X-Api-Version`, בלי רווחים או ירידות שורה. הערכים לא יכולים להכיל ירידות שורה או תווי null. שינוי לא תקין לא נשמר. הוספת כותרת מוסיפה זוג שם וערך; הסרת כותרת מסירה אותו.	ריק.

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

אימות: כל האפשרויות והשדות שלהן

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

אפשרות אימות	השדות ומשמעותם
ללא (ללא אימות)	לא מוסיפה פרטי התחברות ברמת החיבור. לא מוצגים שדות סוד. השתמשו בה רק כשהגדרת השירות דורשת זאת.
מפתח API (כותרת)	שם כותרת / פרמטר הוא שם הכותרת. סוד הוא המפתח שקיבלתם מהספק.
מפתח API (פרמטר)	אותם שני שדות, אבל המפתח נשלח בכתובת הבקשה במקום בכותרת.
אסימון Bearer	סוד מכיל את אסימון הגישה, קוד פרטי שהספק הנפיק. omotto מוסיף את כותרת ההתחברות מסוג Bearer.
HTTP Basic	שם משתמש וסיסמה הם זוג פרטי ההתחברות אצל הספק. בהחלפה, הזינו את שניהם.
כותרת מותאמת	שם כותרת / פרמטר מגדיר את שם הכותרת. ערך הכותרת הוא הערך הקבוע המלא שלה, בדיוק כפי שהספק מסר.
OAuth2 (client credentials)	omotto מקבל אסימון גישה בעזרת פרטי השירות שלכם. זהו חיבור בין מערכות, לא כניסה של לקוח ולא חלון התחברות בדפדפן. מלאו את השדות הנוספים בהמשך.

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

כדי שהבוט יוכל להשתמש בחיבור, שמרו סוד לאסימון Bearer או לאחת משיטות מפתח ה־API; שם משתמש וסיסמה ל־HTTP Basic; ערך הכותרת לכותרת מותאמת; או Client ID וClient Secret ל־OAuth2. האפשרות ללא (ללא אימות) לא דורשת פרטי התחברות. פרט שנשמר לשיטת אימות אחרת לא משלים את השיטה שנבחרה. ערכי התחברות לא יכולים להכיל ירידות שורה או תווי null. באימות באמצעות כותרת, גם שם כותרת / פרמטר צריך להיות שם כותרת תקין בלי רווחים או ירידות שורה.

OAuth2 (client credentials)

כאן המילה ״לקוח״ מתייחסת ליישום השירות שלכם, לא ללקוח של העסק.

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

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

פעולה מותאמת: הפעלה, התנהגות ואימות לקוח

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

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

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

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

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

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

מה מגדירים אחר כך

בחרו רק את האפשרויות שמתאימות למה שאתם רוצים לעשות עם היכולת הזאת.

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

מה קורה כש…

מכבים משהו?

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

מה אומר מצב החיבור?

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

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

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

מופיע טיוטה, נבדק או פעיל?

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

המערכת השנייה מחזירה יותר מידע ממה שרוצים לשתף?

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

פעולה אמיתית נכשלת או שלא מתקבלת תשובה?

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

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

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

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

רוצים לייצא או להסיר את החיבור?

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

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

פתרון בעיות

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

כפתורי היצירה או העריכה לא מופיעים. בקשו ממנהלי סביבת העבודה לבדוק הרשאות. עריכת בקשות ועריכת יכולות דורשות הרשאות נפרדות.
הכתובת נדחית. בדקו עם הספק את כתובת ה־HTTPS הציבורית המלאה. כתובות של רשת פרטית או מחשב מקומי לא מתקבלות. בכתובת OpenAPI השתמשו במסמך נגיש ישירות; עמוד התחברות אינו מפרט.
התצוגה המקדימה לא מצליחה לקרוא את המקור. בדקו את סוג הייבוא שנבחר. השתמשו ב־OpenAPI בגרסה 3, באוסף Postman ולא בתשובה בודדת, או בתבנית שיוצאה מ־omotto. קראו את האזהרות לפני הייבוא.
ההתחברות נכשלת. בדקו את שיטת האימות, את השם המדויק של הכותרת או הפרמטר ואת פרטי הספק. ב־Basic או OAuth2 הזינו את הזוג המלא. הודעה על סוד שמור מאשרת שהוא נשמר, לא שהספק קיבל אותו. הריצו בדיקה חדשה.
פעולה מופעלת אבל לא זמינה. בדקו את מתג החיבור ושמרו בניהול החיבור את כל פרטי ההתחברות שנדרשים לשיטת האימות שנבחרה. הודעה על סוד שמור לא מוכיחה לבדה שכל הפרטים לשיטה הזו קיימים. אם עורך נקודת הקצה מציג בעיות בהגדרה, תקנו את שדות הקלט המצוינים; פעולה עם בעיות כאלה לא מוצעת לבוט. ראו הגדרת קלטים ובעיות בהגדרה. אחר כך בדקו את דרישת אימות הלקוח ואת הקלטים שדורשים פרטים מאומתים. שימוש בערוץ הצוות דורש גם את האפשרות המיועדת לצוות בפעולת קריאה בלבד.
פעולה אמיתית נכשלה או שהתוצאה שלה אינה ידועה. קראו את ההערה בשיחה. תקנו בקשה שנדחתה לפני ניסיון נוסף; אחרי שגיאת שרת או תוצאה לא ידועה, בדקו קודם במערכת האחרת.
הבדיקה מדווחת על שגיאה בהגדרות החיבור. בדקו את כותרות ברירת המחדל, את שם כותרת האימות ואת ערכי ההתחברות השמורים. הסירו רווחים משמות הכותרות וירידות שורה או תווי null מהערכים. השתמשו בפרטים המדויקים מהספק; שינוי ערכי הדוגמה של הפעולה לא מתקן את הגדרות החיבור.
הבקשה מצליחה אבל לא מופיע מידע שימושי. בדקו את שדות תשובה משותפים מול התשובה בפועל, ועברו על איך לקרוא תשובות בעורך נקודת הקצה.
אי אפשר להפעיל תבנית שיובאה. בדקו אם יש דרישת מקור משתמשים שצריך לקשר לסביבת העבודה הזו. אל תחלישו את הדרישה רק כדי להעלים שגיאה.
עדיין תקועים? פנו לתמיכה של omotto עם שם החיבור, שם הפעולה והשגיאה שמופיעה. אל תשלחו סיסמאות, מפתחות פרטיים או קובץ תבנית שלא בדקתם.

שמירת קלטים מהמערכת בהעברת הגדרות

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