תיעוד ⁦API⁩

⁦Shifton⁩ משימות מאפשרת לבצע אוטומציה של העבודה עם הפלטפורמה ולחבר אותה לשירותים חיצוניים דרך ⁦API⁩ פתוח. דרך ⁦API⁩ זמינות כל הישויות המרכזיות — משימות, לקוחות, עובדים, רשימות בדיקה, מלאי, אזורי שירות, מסמכים פיננסיים ודוחות — ולכן אפשר לקשר את ⁦Shifton⁩ למערכות ה⁦HR⁩, חישוב השכר והאנליטיקה שלכם, וכן לשירותים הפנימיים של החברה.

התיעוד פורסם בשתי גרסאות:

🚀 תיעוד חדש — הגרסה העדכנית של המדריך עם מבנה מעודכן והשיטות האחרונות: 👉 https://api2.shifton.com/openapi/
📄 תיעוד ישן — הגרסה הקודמת (עדיין נתמכת עבור אינטגרציות קיימות): 👉 https://api2.shifton.com/docs/

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

התיעוד זמין בשתי שפות. בפינה הימנית העליונה של עמוד התיעוד החדש יש מתג ⁦EN / RU⁩ — השפה הנבחרת נשמרת.

איך לקבל מפתח ⁦API⁩

מפתח ⁦API⁩ נוצר באפליקציה עצמה:

פתחו את הקטע ⁦Developer⁩.
עברו ללשונית מפתחות API (״מפתחות API״).
לחצו על ״צור מפתח API״.

מה למלא בעת יצירת המפתח

ייפתח פאנל צד צור מפתח API עם השדות:

כותרת — שם המפתח, שדה חובה. קראו לו לפי הייעוד, כדי שיהיה ברור אחר כך מה לכבות: ״ייצוא ל⁦1C⁩״, ״דוחות לאנליטיקה״.
פג תוקף ב — התאריך שאחריו המפתח יפסיק לפעול. אם משאירים את השדה ריק, תוקף המפתח אינו מוגבל.
גישה — היקף ההרשאות של המפתח:
גישה מלאה (פעל במקומי) — המפתח פועל בשמכם ועם ההרשאות שלכם.
הרשאות מוגבלות — סט מוגבל של הרשאות שאתם בוחרים בעצמכם.

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

📷 *צילום מסך של פאנל יצירת המפתח — לצלם בסביבת הייצור*

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

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

הרשאה

כל הבקשות ל⁦API⁩ נחתמות במפתח בכותרת:

Authorization: Bearer {your_API_key}

הכתובת הבסיסית של ⁦API⁩:

https://api2.shifton.com/work/1.0.0

בקשה בלי מפתח בתוקף מחזירה ⁦401⁩ וגוף ⁦{"message":"Unauthenticated."}⁩.

הבקשה הראשונה

לדוגמה, כדי לקבל את רשימת עובדי החברה (הציבו את מזהה החברה שלכם במקום ⁦{companyId}⁩):

GET https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees
Authorization: Bearer {your_API_key}
Accept: application/json

אותו הדבר דרך ⁦curl⁩:

curl -H "Authorization: Bearer {your_API_key}" \
     -H "Accept: application/json" \
     https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees

מזהה החברה נראה בשורת הכתובת של האפליקציה: ⁦app.shifton.com/c/8397/...⁩ — המספר שאחרי ⁦/c/⁩.

מה זמין דרך ⁦API⁩

המדריך מכסה יותר מ⁦360⁩ שיטות. הקטעים העיקריים עבור השירות בשטח:

משימות — ⁦/companies/{companyId}/tasks⁩: יצירה, שינוי, סטטוסים, קבצים של משימות.
רשימת מטלות ⁦(To Do)⁩ — ⁦/companies/{companyId}/todo⁩.
לקוחות — ⁦/companies/{companyId}/clients⁩, וכן כתובות ושדות מותאמים אישית של לקוחות.
רשימות בדיקה — ⁦/companies/{companyId}/checklists⁩.
אזורי שירות — ⁦/companies/{companyId}/tasks/service-areas⁩.
כישורים — ⁦/companies/{companyId}/skills⁩.
עובדים — ⁦/companies/{companyId}/employees⁩: הוספה, עריכה, פיטורים ושחזור.
מלאי — פריטים, קטגוריות, מערכות ויתרות במחסנים.
מסמכים פיננסיים — הצעות מחיר, הזמנות עבודה, חשבוניות, קבלות, מוני מסמכים ולוגו.
דוחות — ייצוא נתונים על העבודה והנוכחות.

בנוסף, זמינים לוחות זמנים ומשמרות, חופשות ובקשות לחופש, נוכחות, חיוב וחיוב ⁦SMS⁩, התראות ומודולים.

וובהוקים

אם במקום בקשות סדירות ל⁦API⁩ אתם צריכים לקבל אירועים ברגע התרחשותם, השתמשו בוובהוקים — לשונית ⁦Webhooks⁩ בקטע ⁦Developer⁩. ⁦Shifton⁩ ישלח בעצמו בקשה לכתובת שלכם כאשר יתרחש האירוע הדרוש; את רשימת האירועים הנתמכים מחזירה שיטה נפרדת.

קודי שגיאות

⁦API⁩ של ⁦Shifton⁩ משתמש בקודי מצב ⁦HTTP⁩ תקניים:

⁦200⁩ — הבקשה בוצעה בהצלחה.
⁦201⁩ — האובייקט נוצר בהצלחה.
⁦400⁩ — פרמטרים שגויים בבקשה.
⁦401⁩ — שגיאת הרשאה: המפתח לא הועבר, אינו בתוקף או בוטל.
⁦403⁩ — הגישה אסורה.
⁦404⁩ — המשאב לא נמצא (לרוב שגיאת כתיב בכתובת השיטה).
⁦500⁩ — שגיאת שרת.

טיפים לשימוש

עבור אינטגרציות חדשות השתמשו בתיעוד החדש — הישן נשאר עבור אינטגרציות שכבר פועלות.
לבדיקת בקשות נוחים דוור או ⁦curl⁩ — הם מאפשרים לראות את התשובה בלי לכתוב אף שורת קוד.
אל תשמרו את המפתח בגלוי בקוד ואל תעבירו אותו לצדדים שלישיים: המפתח נותן גישה לנתוני החברה.
הקפידו על הגבלות תדירות הבקשות (⁦rate limits⁩) — חריגה מהן עלולה להוביל לחסימה זמנית של הגישה ל⁦API⁩.

שאלות נפוצות

שאלה: מאיפה לקחת מפתח ⁦API⁩? תשובה: באפליקציה: הקטע ⁦Developer⁩ ← לשונית מפתחות API ← הכפתור ״צור מפתח API״. המפתח מונפק עבור החברה הנוכחית.

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

שאלה: איך לבטל מפתח אם הוא הגיע לידיים הלא נכונות? תשובה: מחקו אותו בלשונית מפתחות API. הביטול חל מיד: כל הבקשות עם מפתח זה יתחילו מיד להחזיר ⁦401⁩.

שאלה: במה שונים ״⁦Full access⁩״ ו״⁦Restricted permissions⁩״? תשובה: גישה מלאה (פעל במקומי) נותן למפתח את אותן הרשאות שיש לכם. הרשאות מוגבלות מאפשר להנפיק למפתח רק את סט ההרשאות הנבחר — כך בטוח יותר עבור אינטגרציה שצריכה גישה לחלק מהנתונים בלבד.

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

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

שאלה: מהי הכתובת הבסיסית של ⁦API⁩? תשובה: ⁦https://api2.shifton.com/work/1.0.0⁩. אחריה מגיע נתיב השיטה, למשל ⁦/companies/{companyId}/tasks⁩.

שאלה: מאיפה לקחת את מזהה החברה עבור הבקשות? תשובה: הוא נמצא בשורת הכתובת של האפליקציה מיד אחרי ⁦/c/⁩ — למשל, ב⁦app.shifton.com/c/8397/tasks⁩ מזהה החברה שווה ל⁦8397⁩.

שאלה: באיזו גרסת תיעוד להשתמש? תשובה: עבור אינטגרציות חדשות — בחדשה (⁦api2.shifton.com/openapi⁩). הישנה (⁦api2.shifton.com/docs⁩) נתמכת עבור אינטגרציות קיימות.

שאלה: האם יש תיעוד בשפה הרוסית? תשובה: כן. בעמוד התיעוד החדש, בפינה הימנית העליונה, יש מתג ⁦EN / RU⁩.

שאלה: במה לבדוק בקשות ל⁦API⁩? תשובה: הנוח ביותר הוא דוור או ⁦curl⁩ — הם מאפשרים לשלוח בקשות ולראות תשובות בלי לכתוב קוד.

שאלה: מדוע מתקבל ⁦401⁩, אף שהעתקתי את המפתח? תשובה: בדקו שהמפתח מועבר בכותרת ⁦Authorization⁩ עם המילה ⁦Bearer⁩ לפניו, שהמפתח לא בוטל ושתוקפו לא פג.

שאלה: מדוע מתקבל ⁦404⁩? תשובה: לרוב הכתובת התבלבלה: החלק הבסיסי צריך להיות ⁦https://api2.shifton.com/work/1.0.0⁩, ובנתיב השיטה — ה⁦{companyId}⁩ הנכון.

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

שאלה: האם אפשר לקבל אירועים מ⁦Shifton⁩, במקום לתשאל את ⁦API⁩? תשובה: כן, לשם כך יש וובהוקים — לשונית ⁦Webhooks⁩ בקטע ⁦Developer⁩.

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