# API النشر في SosoAPI: المصادقة والطلبات والنتائج

الرابط الأساسي: https://sosoapi.ai/ar/docs/publishing-api-reference

ابنِ تكامل نشر على الخادم حول Scheduled Post واحد لكل وجهة. يغطي المرجع عقد API النشر المراجع في 20 أكتوبر 2026. الأمثلة بعناصر نائبة ولا تعمل على الصفحة.

## 1. المصادقة من خادمك

أنشئ مفتاح API في SosoAPI App → Settings → Agents & API Access. خزّنه في 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 لإصداره الحالي وإجراءاته المتاحة ونتيجة نشره.

نقاط نهاية Scheduled Posts؛ كل طلب يستخدم POST

| المسار | الطلب | الاستجابة والحدود |

| --- | --- | --- |

| /studio-api/scheduled-posts/list | workspace_id؛ واختيارياً project_id و status وزوج وقت و limit و cursor. | posts و next_cursor و returned_count. قراءة ضمن نطاق مساحة العمل. |

| /studio-api/scheduled-posts/get | id. | post و delivery و actions و attempts و outcomes. اقرأ الإصدار الحالي هنا. |

| /studio-api/scheduled-posts/eligibility | workspace_id و targets؛ و include_quota اختياري. | الوجهات والحصة الاختيارية. فحص تمهيدي للقراءة فقط، وليس حجزاً. |

| /studio-api/scheduled-posts/create | workspace_id والحساب المحدد و provider_payload و content و scheduled_at و idempotency_key. | post و deduped. الرمز 201 لجدول جديد؛ و 200 لإعادة طلب مطابقة. |

| /studio-api/scheduled-posts/bulk-create | workspace_id ومن 1 إلى 50 عنصراً في targets، لكل منها idempotency_key خاص. | batch_id و successes و failures. الرمز 201 إذا نجح واحد على الأقل؛ و 422 إذا لم ينجح أي منها. افحص المصفوفتين. |

| /studio-api/scheduled-posts/update | id و expected_version و patch؛ و provider_payload مطابق اختياري. | المنشور. يُرفض الإصدار القديم؛ ولا يمكن تغيير الوجهة. |

| /studio-api/scheduled-posts/publish-now | id و expected_version. | المنشور. يطلب التنفيذ الفوري؛ ولا يثبت النشر. |

| /studio-api/scheduled-posts/retry | id و expected_version؛ و scheduled_at مستقبلي اختياري. | المنشور. استرداد للفشل فقط ومشروط بالأدلة؛ لا إعادة إرسال عمياء أبداً. |

| /studio-api/scheduled-posts/cancel | id و expected_version. | المنشور. يُلغي العمل غير المنشور؛ وقد يبقى الإلغاء لدى المنصة معلّقاً. |

| /studio-api/scheduled-posts/delete | id و expected_version. | المنشور. لا تستطيع الجهات الآلية حذف محتوى مزوّد الخدمة المنشور بالفعل. |

| /studio-api/scheduled-posts/withdraw-delete | id و expected_version. | المنشور. يسحب طلب حذف Instagram Login متوقفاً وللتحقق فقط؛ ويحتفظ بمحتوى مزوّد الخدمة. |

## 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 نصياً حقيقياً عند تشغيله. احصل على تأكيد الشخص للحساب والمحتوى والوقت قبل استدعاء الإنشاء.

اضبط provider_payload.platform و publish_options للمنصة. يفحص الخادم مطابقتهما للحساب المختار. يمكن تضمين project_id لتوثيق مصدر المنشور؛ لا يمنح المشروع وصول النشر ولا يتحكم بالجدول.

حقول طلب الإنشاء وقيمها الافتراضية

| الحقل | العقد |

| --- | --- |

| workspace_id / social_account_id | معرّفات UUID المطلوبة لمساحة العمل المفوّضة والوجهة المحددة بدقة. |

| provider_payload | مميّز المنصة المطلوب و publish_options الخاصة بالمنصة. |

| scheduled_at / display_timezone | لحظة زمنية ISO-8601 مطلوبة مع إزاحة؛ ومنطقة عرض IANA صالحة، الافتراضي UTC. |

| idempotency_key | نص مطلوب بلا فراغات طرفية، طوله 8–160 حرفاً، وثابت لهذا القصد الواحد. |

| caption / hashtags | يقبل caption قيمة null وبحد أقصى 5,000 حرف؛ الافتراضي null. و hashtags افتراضياً []؛ حتى 100 نص من 100 حرف. قد تكون حدود المزوّد أضيق. |

| media | الافتراضي []؛ حتى 20 مرجع وسائط مسجّلاً. لكل منها kind بقيمة image/video و url أساسي؛ أضف asset_id الجاهز. قد تكون قواعد المنصة أضيق. |

| link_url | URL اختياري أو null. يجب أن تدعمه الوجهة ونوع المنشور. |

| local_scheduled_at / schedule_dst_disambiguation | زوج اختياري: وقت محلي بلا إزاحة و exact/earlier/later. وفّرهما معاً أو احذفهما معاً؛ يجب أن يطابقا اللحظة والمنطقة الزمنية المقصودتين. |

| expires_at / automatic_retry_enabled | انتهاء اختياري بعد scheduled_at؛ وتعني null عدم الانتهاء. إعادة المحاولة التلقائية افتراضياً true وتظل خاضعة لسلامة مزوّد الخدمة. |

| project_id / source_ref | معرّف Project UUID اختياري يقبل null وكائن مصدر للجهة المستدعية. لا يغيّر أيهما الصلاحيات. |

```
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 التقدم والخطوات المسموحة.

المنشور بحالة scheduled أو publishing لا يزال معلّقاً. تؤكد نتيجة publish نهائية بحالة published النشر وتحوي أدلة المزوّد المتاحة؛ وقد يغيب الرابط الدائم. إذا انقطع العميل أوتأخرت الاستجابة، اقرأ المنشور الموجود قبل الإبلاغ.

قبل الإلغاء، اجلب التفاصيل ومرّر version الرقمي الحالي. قد تكون النتيجة 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 نفسه عند تكرار طلب الإنشاء نفسه. تُعيد المطابقة المنشور الموجود مع deduped=true. تغيير المحتوى بالمفتاح نفسه يسبب تعارضاً. يمنع هذا الإنشاء المكرر في SosoAPI؛ ولا يضمن تسليم المزوّد مرة واحدة بالضبط.

للتحديثات والإجراءات، مرّر expected_version من أحدث تفاصيل. عند التعارض، اجلب المنشور مجدداً وراجع تغييرك مقابل الإصدار الجديد. فقدان الاستجابة يستدعي فحص الموجود، لا إنشاء منشور آخر بمفتاح جديد.

قد يرفض حارس المحتوى المكرر طلباً مستقلاً بالمحتوى العام المنسّق نفسه والحساب نفسه ووقت قريب. افحص مرجع المنشور الموجود إن فوّضت لقراءته، واسأل المستخدم قبل تغيير الطلب. تُعيد الدفعات نتيجة لكل وجهة؛ وقد ينجح بعضها ويفشل غيرها.

## 7. الأخطاء وحدود المعدّل والتكامل

تستخدم أخطاء المعالج غلافاً يحوي error و message و code اختياري و retryable و request_id و details اختياري و retry_after_seconds. أخطاء التحقق 400s بصيغة أخرى: { 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 للمشترك أوميزات متطابقة عبر المنصات أوموعد نشر ثابت.

استجابات HTTP والخطوات التالية المفيدة

| الحالة | المعنى والاستجابة |

| --- | --- |

| 400 | قد يُعيد تحقق المخطط success:false مع ZodError في error، بدلاً من غلاف المعالج. أصلح الحقول؛ استخدم x-request-id إن غاب request_id. قد تستخدم طلبات المعالج غير الصالحة أوغير المدعومة 400 أيضاً. |

| 401 / 403 | بيانات اعتماد مفقودة/منتهية أو رفض إمكانية أو دور أو وصول لمساحة عمل أو حساب. أصلح التفويض أو العضوية المحددين. |

| 404 | المورد غير متاح ضمن النطاق المفوّض. تحقّق من الهوية. |

| 409 | تعارض حالة/إصدار أو منع تكرار أو محتوى مكرر أو أهلية. أعِد القراءة؛ لا تُعِد الإرسال عشوائياً. |

| 422 للإنشاء الجماعي | لم تنجح أي وجهة. افحص الإخفاقات؛ النجاح الجزئي يستخدم 201 بدلاً من ذلك. |

| 429 | تقييد معدل الطلبات. التزم بـ Retry-After واحتفظ بهوية القصد نفسها. |

| 503 / أخطاء 5xx الأخرى | فشل مؤقت في الخدمة أو خلل داخلي. احتفظ بـ request_id؛ افحص الحالة الموجودة قبل إعادة محاولة تعديل غير مؤكد. |

- [مصفوفة إمكانات المنصات](https://sosoapi.ai/ar/docs/publishing-capabilities)

- [إعداد وكيل الذكاء الاصطناعي الخاص بك](https://sosoapi.ai/ar/docs/quickstart)