ממשק REST API של שַׁגֵּר בעשר דקות: מהקריאה whoami ועד פוסט מתוזמן לעשרות חשבונות

ממשק REST API של שַׁגֵּר יושב תחת https://app.shager.ai/api/v1, מאמת כל בקשה בכותרת Authorization: Bearer shgr_live_…, ומחזיר תשובות במבנה { "data": … } ושגיאות במבנה { "error": { "code", "message" } }. הרצף הבסיסי הוא GET /me, אחריו GET /workspaces, רשימת החשבונות של סביבת עבודה, העלאת מדיה, יצירת פוסט ותזמון שלו. המפרט המלא, OpenAPI 3.1, נמצא בכתובת https://app.shager.ai/api/v1/openapi.json, וכל פעולה בו מקבילה לכלי באותו שם בשרת MCP.

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

לפני הקריאה הראשונה

צריך מפתח API. אדם בצוות יוצר אותו בכתובת https://app.shager.ai/dashboard/agents ובוחר הרשאות מתוך read, write או publish, או שסוכן נרשם בעצמו ומקבל sandbox, כמו שמוסבר במדריך על הרשמה עצמית של סוכן. הגישה לממשק API כלולה בכל המסלולים, כולל החינמי, כפי שמופיע בעמוד המחירים.

שומרים את המפתח במשתנה סביבה:

export SHAGER_API_KEY="shgr_live_XXXXXXXXXXXXXXXX"
export SHAGER="https://app.shager.ai/api/v1"

מפת הפעולות

פעולה	שיטה ונתיב	הרשאה סבירה
whoami	GET /me	read
list_workspaces	GET /workspaces	read
create_workspace	POST /workspaces	write
list_channels	GET /workspaces/{id}/channels	read
create_connect_link	POST /workspaces/{id}/connect-links	write
list_groups, create_group	GET או POST /workspaces/{id}/groups	read, write
upload_media_from_url	POST /workspaces/{id}/media	write
create_post, list_posts	POST או GET /workspaces/{id}/posts	write, read
get_post	GET /workspaces/{id}/posts/{post_id}	read
schedule_post	POST /workspaces/{id}/posts/{post_id}/schedule	publish
request_approval	POST /workspaces/{id}/posts/{post_id}/approval	write
cancel_post	POST /workspaces/{id}/posts/{post_id}/cancel	write
get_analytics	GET /workspaces/{id}/analytics	read

העמודה האחרונה היא הנחת עבודה סבירה לפי אופי הפעולה. הקובע הוא ההרשאות שהמפתח שלכם קיבל בפועל, וְשַׁגֵּר יחזיר שגיאה ברורה אם חסרה הרשאה.

שלב 1: מי אני ואיפה אני עובד

curl -s "$SHAGER/me" -H "Authorization: Bearer $SHAGER_API_KEY"
curl -s "$SHAGER/workspaces" -H "Authorization: Bearer $SHAGER_API_KEY"

בְּשַׁגֵּר כל לקוח הוא סביבת עבודה (workspace). אם אין עדיין אף אחת, יוצרים:

curl -s -X POST "$SHAGER/workspaces" \
  -H "Authorization: Bearer $SHAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "רשת מרפאות השן", "timezone": "Asia/Jerusalem"}'

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

שלב 2: אילו חשבונות מחוברים

curl -s "$SHAGER/workspaces/$WS/channels" -H "Authorization: Bearer $SHAGER_API_KEY"
curl -s "$SHAGER/workspaces/$WS/groups"   -H "Authorization: Bearer $SHAGER_API_KEY"

אם הרשימה ריקה, יוצרים קישור חיבור עם POST /workspaces/{id}/connect-links ושולחים אותו לבעל החשבונות. הלקוח מחבר את הפייסבוק, האינסטגרם או היוטיוב שלו דרך הקישור, בלי חשבון בְּשַׁגֵּר ובלי למסור סיסמה. קבוצות חשבונות שימושיות כשיש עשרות עמודים: במקום לרשום מזהים אחד אחד, שולחים group_ids וכל החשבונות הפעילים בקבוצה נכנסים לפוסט.

שלב 3: העלאת מדיה

שַׁגֵּר מושך את הקובץ מכתובת URL. עבור סרטון קצר כדאי לשלוח גם מידות ואורך:

curl -s -X POST "$SHAGER/workspaces/$WS/media" \
  -H "Authorization: Bearer $SHAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://cdn.example.com/autumn-30s.mp4",
    "file_name": "autumn-30s.mp4",
    "width": 1080,
    "height": 1920,
    "duration_ms": 30000
  }'

השדות width, height וגם duration_ms הם מה שמאפשר לְשַׁגֵּר לבדוק מראש אם הסרטון מתאים לפורמט Reel, Short או Story, ולא לגלות את זה רק כשהרשת דוחה אותו. המזהה של המדיה חוזר בתוך data, ואותו מעבירים בשדה media_ids.

שלב 4: יצירת פוסט

זו הקריאה שבה רוב הערך נמצא:

curl -s -X POST "$SHAGER/workspaces/$WS/posts" \
  -H "Authorization: Bearer $SHAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "מבצע סתיו, שבוע 1",
    "campaign": "autumn-2026",
    "group_ids": ["GROUP_NORTH"],
    "media_ids": ["MEDIA_ID"],
    "format": "REEL",
    "caption": "בדיקה שנתית לכל המשפחה, עכשיו עם תור תוך שבוע.",
    "per_channel": [
      {"channel_id": "CH_HAIFA",  "caption": "חיפה, התורים לסתיו נפתחו."},
      {"channel_id": "CH_AFULA",  "caption": "בעפולה? יש תורים כבר לשבוע הבא."}
    ],
    "cta_url": "https://example.com/autumn",
    "first_comment": "לקביעת תור בסניף הקרוב:",
    "stagger_seconds": [45, 120]
  }'

כמה דברים שקורים כאן מאחורי הקלעים. cta_url מקבל לכל חשבון קישור מקוצר ותגיות UTM משלו, כש utm_content מזהה את החשבון, והשדה campaign הופך לפרמטר utm_campaign. first_comment עולה כתגובה ראשונה מיד אחרי הפרסום, וזה המקום הטבעי לקישור לליד. per_channel מחליף את הכיתוב רק בחשבונות שציינתם, והשאר מקבלים את caption הכללי. והשדה stagger_seconds קובע את טווח ההשהיה האקראית בין חשבונות של אותה רשת, עם ברירת מחדל של 30 עד 90 שניות. פוסט בלי schedule_at נשמר כטיוטה.

ליוטיוב יש שני שדות נוספים: youtube_title וגם youtube_privacy עם הערכים public, unlisted או private.

שלב 5: אישור, תזמון ומעקב

אם הלקוח צריך לאשר, שולחים בקשת אישור עם שם הסוקר. הלקוח מאשר דרך קישור, בלי להתחבר:

curl -s -X POST "$SHAGER/workspaces/$WS/posts/$POST_ID/approval" \
  -H "Authorization: Bearer $SHAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reviewer_name": "מיכל", "reviewer_email": "michal@example.com", "send_email": true}'

תזמון דורש זמן בפורמט ISO 8601 עם offset:

curl -s -X POST "$SHAGER/workspaces/$WS/posts/$POST_ID/schedule" \
  -H "Authorization: Bearer $SHAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schedule_at": "2026-09-20T09:00:00+03:00"}'

אפשר גם לשלוח schedule_at כבר בקריאה create_post ולחסוך קריאה. לבדיקת מצב משתמשים בפעולה get_post, או בפעולה list_posts עם status, למשל SCHEDULED, PUBLISHED, PARTIALLY_PUBLISHED או FAILED. ואחרי כמה ימים:

curl -s "$SHAGER/workspaces/$WS/analytics?from=2026-09-20T00:00:00%2B03:00" \
  -H "Authorization: Bearer $SHAGER_API_KEY"

התשובה כוללת לחיצות לפי חשבון ולפי פוסט בטווח התאריכים. בלי from, ברירת המחדל היא 30 הימים האחרונים.

שגיאות ומגבלת קצב

כל שגיאה חוזרת עם code וגם message קריאים. שווה לטפל בשלושה מקרים במפורש: 401 על מפתח לא תקין או מבוטל, sandbox_unclaimed כשמנסים פעולה חסומה לפני שאדם אישר את סביבת sandbox, וקוד rejected כְּשֶׁשַּׁגֵּר בודק את הפוסט מול הכללים של הרשת ומוצא משהו שהיא הייתה דוחה. ההודעה אומרת מה בדיוק לא עבר.

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

חמישה הרגלים שהופכים סקריפט לאינטגרציה

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

1. שמרו כל מזהה שחוזר. מזהה סביבת העבודה, המדיה והפוסט צריכים להישמר אצלכם, בטבלה או בקובץ, יחד עם המקור שממנו נוצרו. כך אפשר לחזור לפוסט, לבדוק את המצב שלו ולבטל אותו בלי לחפש.
2. אל תיצרו פוסט פעמיים. אם הסקריפט נופל באמצע וחוזר לרוץ, הוא עלול ליצור את אותה טיוטה שוב. בדקו קודם עם list_posts אם כבר קיים פוסט עם אותו label.
3. המתינו כשמגיעים למגבלה. על שגיאת קצב, חכו ונסו שוב עם השהיה הולכת וגדלה, במקום להפציץ את השרת.
4. אל תדפיסו את המפתח. לא בלוג, לא בהודעת שגיאה ולא בצילום מסך. אם הוא דלף, מבטלים אותו במסך הסוכנים ויוצרים חדש.
5. התחילו בטיוטות. מפתח בלי publish בשבועות הראשונים נותן לכם לראות מה הקוד מייצר לפני שזה עולה לעמודים אמיתיים.

מה הלאה

אם אתם בונים סוכן ולא סקריפט, אותן פעולות זמינות כשרת MCP בכתובת https://app.shager.ai/api/mcp, והחיבור לרוב הכלים לוקח דקות. המדריך לחיבור שַׁגֵּר אל Claude Code הוא נקודת התחלה טובה, ועמוד הסוכנים מרכז את כל דרכי החיבור. ואם אתם מתכננים זרימה מלאה מבריף ועד דוח, המדריך לצינור תוכן של סוכן מקצה לקצה מחבר את כל השלבים.

שאלות נפוצות

יש SDK רשמי לְשַׁגֵּר?

אין כרגע SDK או CLI רשמי, CLI של שַׁגֵּר נמצא בפיתוח. מכיוון שיש מפרט OpenAPI 3.1 מלא, אפשר לייצר לקוח בכל שפה עם מחולל קוד סטנדרטי, או פשוט לעבוד עם HTTP ישירות כמו בדוגמאות.

מה ההבדל בין שליחת schedule_at בקריאה create_post לבין schedule_post?

התוצאה זהה. שליחה בקריאה create_post חוסכת קריאה כשהכול מוכן מראש. schedule_post מתאים כשיוצרים טיוטה, שולחים לאישור, ומתזמנים רק אחרי שהלקוח אישר.

איך מבטלים פוסט שכבר תוזמן?

שולחים POST לנתיב /workspaces/{id}/posts/{post_id}/cancel. אחרי הביטול הסטטוס של הפוסט יהיה CANCELED, ואפשר לראות את זה בפעולה get_post.