API הפרסום של SosoAPI: אימות, בקשות ותוצאות

1. בצעו אימות מהשרת שלכם

צרו מפתח API באפליקציית SosoAPI ← הגדרות ← סוכנים וגישת API. שמרו אותו בתור SOSOAPI_API_KEY בסביבת השרת. בקשות משתמשות ב-Authorization: Bearer <your-key> וב-Content-Type: application/json. לעולם אין להטמיע את המפתח באתר, בחבילת אפליקציה לנייד, ב-URL או במאגר ציבורי.

כל נקודות הקצה שלהלן משתמשות ב-POST עם גוף JSON. מפתחות והרשאות סוכן מואצל מוגבלים על ידי היכולות, סביבות העבודה המותרות והחברות העדכנית של הבעלים. קריאות דורשות agent:operate וגישה ברמת viewer לפחות; שינויי פרסום דורשים agent:publish וגישה ברמת editor לפחות. הרשאה אינה יכולה להרחיב את זכויות הבעלים.

השתמשו בסביבת העבודה ובחשבונות המחוברים הנוכחיים באפליקציה, או קראו ל-/identity-api/workspace/list ול-/identity-api/user/social-accounts/list כדי למצוא מזהים שאתם מורשים להשתמש בהם. אין לנחש מזהה סביבת עבודה או חשבון של לקוח.

// Node.js 20+; run only on your server.
const apiKey = process.env.SOSOAPI_API_KEY;
if (!apiKey) throw new Error("Set SOSOAPI_API_KEY on your server");
const apiBase = "https://gqeshlawtcexsapabaui.supabase.co/functions/v1";

async function sosoPost(path, body) {
  const response = await fetch(apiBase + path, {
    method: "POST",
    headers: {
      Authorization: "Bearer " + apiKey,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(body)
  });
  const result = await response.json();
  if (!response.ok) {
    const requestId = result.request_id ?? response.headers.get("x-request-id");
    // Handler errors use code/message; schema-validation 400s instead use
    // success:false and error:{name:"ZodError",message:...}.
    // Preserve status, available code and requestId in server diagnostics.
    // Never log the key or an Authorization header.
    throw new Error("SosoAPI " + response.status + " (" +
      (requestId ?? "no request id") + ")");
  }
  return result;
}

2. מפת נקודות קצה לפרסום

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

3. הציגו ודפדפו בלי לאבד את ההיקף

ברירת המחדל של limit היא 50 והטווח המתקבל הוא 1–200. ‏status אופציונלי הוא אחד מ-scheduled, publishing, published, failed, expired, needs_reschedule, cancelled או deleted. יש לספק scheduled_from ו-scheduled_to יחד כרגעי ISO-8601 עם היסטי זמן; הסיום חייב להיות אחרי ההתחלה.

next_cursor הוא null או אובייקט עם scheduled_at ו-id. שלחו את כל האובייקט הזה חזרה בתור cursor יחד עם אותה סביבת עבודה ואותם מסננים. נקודת הקצה אינה מקבלת מסנני page, offset, platform או social_account_id.

await sosoPost("/studio-api/scheduled-posts/list", {
  "workspace_id": "<workspace-uuid>",
  "limit": 50
});

const first = await sosoPost("/studio-api/scheduled-posts/list", {
  workspace_id: "<workspace-uuid>", limit: 50
});
if (first.next_cursor) {
  const next = await sosoPost("/studio-api/scheduled-posts/list", {
    workspace_id: "<workspace-uuid>", limit: 50, cursor: first.next_cursor
  });
  // Consume next.posts; continue only while next_cursor is not null.
}

4. אמתו וצרו פוסט אחד שנבדק

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

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

await sosoPost("/studio-api/scheduled-posts/eligibility", {
  "workspace_id": "<workspace-uuid>",
  "include_quota": true,
  "targets": [
    {
      "social_account_id": "<threads-account-uuid>",
      "media": [],
      "provider_payload": {
        "platform": "threads",
        "publish_options": {
          "post_type": "TEXT"
        }
      },
      "draft": {
        "caption": "A reviewed update from our team.",
        "hashtags": [],
        "scheduled_at": "<future-ISO-8601-instant-with-offset>",
        "display_timezone": "Asia/Hong_Kong"
      }
    }
  ]
});

await sosoPost("/studio-api/scheduled-posts/create", {
  "workspace_id": "<workspace-uuid>",
  "social_account_id": "<threads-account-uuid>",
  "caption": "A reviewed update from our team.",
  "hashtags": [],
  "media": [],
  "provider_payload": {
    "platform": "threads",
    "publish_options": {
      "post_type": "TEXT"
    }
  },
  "scheduled_at": "<future-ISO-8601-instant-with-offset>",
  "display_timezone": "Asia/Hong_Kong",
  "idempotency_key": "<stable-key-for-this-one-intent>"
});

5. קראו את התוצאה ובטלו בבטחה

Create מחזיר { post, deduped }. ‏List מחזיר { posts, next_cursor, returned_count }. ‏Get מחזיר { post, delivery, actions, attempts, outcomes }. פוסט כולל id, status, version, יעד, תזמון וזהות/קישור קבוע זמינים אצל הספק; delivery ו-actions מסבירים התקדמות נוכחית וצעדים הבאים שמותרים.

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

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

await sosoPost("/studio-api/scheduled-posts/get", {
  "id": "<scheduled-post-uuid>"
});

const detail = await sosoPost("/studio-api/scheduled-posts/get", {
  id: "<scheduled-post-uuid>"
});
// Run only after the person confirms cancelling this unpublished post.
await sosoPost("/studio-api/scheduled-posts/cancel", {
  id: detail.post.id, expected_version: detail.post.version
});

6. אידמפוטנטיות, התנגשויות וכתיבות לא ודאיות

השתמשו באותו idempotency_key בחזרה על אותה בקשת create. בקשה חוזרת תואמת מחזירה את הפוסט הקיים עם deduped=true. שינוי התוכן תוך שימוש חוזר במפתח גורם להתנגשות. כך נמנעת יצירה כפולה ב-SosoAPI; אין בכך הבטחה למסירה בדיוק פעם אחת אצל הספק.

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

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

7. שגיאות, מגבלות קצב ומגבלות שילוב

שגיאות מטפל משתמשות במעטפת עם error, message, ‏code אופציונלי, retryable, request_id, ‏details אופציונלי ו-retry_after_seconds. תגובות 400 לאימות סכמה מחזירות מבנה אחר: { success: false, error: { name: "ZodError", message: "…" } }. הודעת האימות כוללת כעת את בעיות השדות המסודרות, כולל הנתיבים שלהן; אין להניח ששדות מעטפת המטפל קיימים.

באבחון כשל, שמרו את סטטוס ה-HTTP, קוד השגיאה ומזהה הקישור מ-result.request_id ?? response.headers.get("x-request-id"). השתמשו בנתיבי שדות האימות לתיקון הבקשה. לשגיאות אימות או הרשאה, תקנו את אמצעי הגישה או ההרשאה לפני ניסיון נוסף.

מגבלת studio-api הנוכחית היא 240 בקשות לדקה למשתמש אנושי ו-480 לדקה במכסה המכונתית הנפרדת של אותו משתמש. אלה תקרות בקשות, ולא תפוקת פרסום או מכסות מסלול. לנקודות קצה אחרות ולספקים החברתיים יש מגבלות נפרדות. פעלו לפי כותרת Retry-After העדכנית ב-429 או ב-503 שניתן לנסות שוב; אין לבצע לולאה רציפה.

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

• מטריצת יכולות פלטפורמות
• הגדרת סוכן AI משלכם