# دليل إعداد SosoAPI

الرابط الأساسي: https://sosoapi.ai/ar/docs/setup-guide

صِل وكيل الذكاء الاصطناعي، واربط حساباً اجتماعياً، وجهّز منشورك الأول.

<a id="choose-your-starting-point"></a>

## اختر نقطة البداية

يوفّر SosoAPI للوكيل الذي تستخدمه بالفعل اتصالاً واحداً بحساباتك الاجتماعية. يساعد وكيلك على كتابة المحتوى ومراجعته؛ يتولى SosoAPI عمليات الحساب المدعومة والجدولة ونتائج النشر. يمكنك مراجعة المنشورات نفسها في التطبيق أو استخدام API من كودك.

يبدأ هذا الدليل بشخص واحد وحساب اجتماعي واحد. ستصل عميل MCP محلياً أو مستضافاً، وتختار الوصول، وتفحص حساباً اجتماعياً، وتجهّز منشوراً وتوافق عليه، وتقرأ نتيجته الفعلية. يشرح الجزء المتقدم CLI وHTTP API. الإعداد نفسه لا يتطلب منشور اختبار.

- [دع Claude Code أو Codex يتولى الإعداد: الخطوة 1](#1-give-your-agent-the-setup-request)

- [إعداد عميل MCP بنفسك: الخطوة 3](#3-connect-your-agent-manually-if-needed)

- [استخدام الطرفية أو الخادم الخلفي: الخطوة 9](#9-cli-and-api-walkthrough)

- [إصلاح اتصال: الخطوة 10](#10-troubleshooting)

<a id="before-you-start"></a>

## قبل البدء

تحتاج إلى عميل ذكاء اصطناعي متوافق مع MCP وحساب SosoAPI وحساب اجتماعي يحق لك إدارته. يمكنك إنشاء حساب SosoAPI عند فتح تسجيل الدخول. جهّز فكرة لمحتوى حقيقي واحد.

يحتاج MCP المحلي إلى Node.js 20 أو أحدث مع npm/npx وعميل الذكاء الاصطناعي المختار. يحتاج MCP المستضاف إلى عميل يدعم MCP البعيد وOAuth والتسجيل التلقائي للعملاء؛ لا يحتاج تثبيت Node.js محلياً. قد تعتمد ميزات العميل على خطته وإعدادات المسؤول.

يربط SosoAPI بين Instagram وThreads وFacebook Pages وYouTube وX. اختر حساباً يطابق نوعه وأذوناته وصيغة المنشور مهمتك. حساب Threads مؤهّل مثال أول مفيد للنص فقط. يحتاج Instagram وYouTube إلى وسائط مناسبة لصيغ النشر المدعومة. ظهور منصة في قائمة الاتصال لا يعني توفر كل إجراء لكل حساب.

افحص قدرات الحساب المحدد أثناء الإعداد. اقرأ خطتك الحالية وحصتك في التطبيق قبل جدولة دفعة؛ لـ X رصيد منفصل على مستوى Organization. مثال منصة واحدة لا يثبت الدعم على منصة أخرى.

- [المنصات المدعومة](https://sosoapi.ai/ar/docs/supported-platforms)

- [قدرات النشر ومتطلبات الحساب](https://sosoapi.ai/ar/docs/publishing-capabilities)

<a id="1-give-your-agent-the-setup-request"></a>

## 1. أعطِ وكيلك طلب الإعداد

ألصق هذا في محادثة Claude Code أو Codex الحالية.

ينبغي أن يفحص الوكيل أولاً اتصال SosoAPI يعمل ويعيد استخدامه. وإلا يتبع وصفة الإعداد ويخبرك عند الحاجة لتسجيل الدخول بالمتصفح أو إعادة تشغيل العميل. النتيجة المتوقعة: أدوات SosoAPI قابلة للاستخدام في هذه المحادثة. رسالة التثبيت وحدها ليست إثباتاً. تابع بتسجيل الدخول وفحص الحساب، أو استخدم الخطوة 3 للإعداد اليدوي.

> إعداد SosoAPI من https://sosoapi.ai/setup.md. احتفظ بمحتواي ومهمتي الحاليين. سأسجّل الدخول وأوافق على الوصول عند الطلب. لا تنشر شيئاً أثناء الإعداد.

<a id="2-sign-in-and-choose-your-agents-access"></a>

## 2. سجّل الدخول واختر وصول وكيلك

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

احتفظ برابط تسجيل الدخول الذي قدّمه وكيلك ليتمكن المتصفح من العودة إلى التفويض المعلّق. يمكنك البدء في التطبيق أولاً ثم العودة إلى الوكيل. لا تستبدل رابط موافقة معلّقاً برابط تسجيل دخول مختلف.

تظل أدوار Workspace وأذونات المنصة سارية: لا يصبح المشاهد محرراً لأن للوكيل وصول نشر. يستمر وصول النشر ضمن النطاق الذي تمنحه؛ لا يتطلب SosoAPI موافقة متصفح جديدة لكل منشور. أخبر وكيلك متى يتوقف لمراجعة المحتوى. إعداد OAuth المعتاد لا يتطلب لصق كلمة مرور اجتماعية أو مفتاح API في الوكيل.

النتيجة المتوقعة: اكتمال تسجيل الدخول بهويتك المقصودة وقدرة الوكيل على استرجاع Workspaces التي فوّضتها. استخدم استكشاف الأخطاء إذا فُتح ملف المتصفح الخاطئ.

اختر الوصول للمهمة

| خيار الوصول | الغرض منه |

| --- | --- |

| القراءة والإنشاء والتعديل | قراءة معلومات الحساب المتاحة وتجهيز العمل. |

| الجدولة والنشر | إرسال أعمال النشر وإدارتها ضمن النطاق المختار. |

| أذونات إضافية | فعّلها لحاجة محددة فقط. النشر المعتاد لا يحتاج إدارة مفاتيح API. |

- [ابدأ في تطبيق SosoAPI](https://app.sosoapi.ai/start?lang=en)

<a id="3-connect-your-agent-manually-if-needed"></a>

## 3. اتصل بوكيلك يدوياً عند الحاجة

اختر طريقة اتصال واحدة. تجاوز هذا القسم إذا أعدّ وكيلك اتصالاً يعمل بالفعل. لـ MCP المحلي، افحص Node.js وnpx أولاً. يجب أن يكون Node.js بالإصدار 20 أو أحدث.

```
node --version
npx --version
```

<a id="local-mcp-claude-code-or-codex"></a>

## MCP المحلي: Claude Code أو Codex

نفّذ أمر عميلك فقط: الأول لـ Claude Code والثاني لـ Codex. يغطي ملف core النشر اليومي. تغيّر الملفات الأدوات المعروضة ولا تمنح أذونات. احتفظ باتصال full-profile يعمل إذا كان لديك بالفعل.

أعد الاتصال أو التشغيل إن طلب العميل، ثم تحقّق من توفر أدوات SosoAPI في المحادثة الحالية. يبدأ أول استدعاء مصادَق عليه تسجيل الدخول بالمتصفح عند الحاجة.

```
claude mcp add sosoapi -e SOSOAPI_TOOL_PROFILE=core -- npx -y sosoapi
```

```
codex mcp add sosoapi --env SOSOAPI_TOOL_PROFILE=core -- npx -y sosoapi
```

<a id="other-local-mcp-clients"></a>

## عملاء MCP محليون آخرون

للعملاء الذين يستخدمون mcpServers JSON، أضف هذا الإدخال إلى الإعداد الموجود واحتفظ بالخوادم الأخرى. ينبغي للصيغ الأخرى أن تتلقى الأمر والوسائط ومتغير البيئة نفسها عبر إعدادات MCP الخاصة بالعميل.

```
{
  "mcpServers": {
    "sosoapi": {
      "command": "npx",
      "args": [
        "-y",
        "sosoapi"
      ],
      "env": {
        "SOSOAPI_TOOL_PROFILE": "core"
      }
    }
  }
}
```

- [مرجع التثبيت وخيارات الحزمة](https://sosoapi.ai/ar/docs/installation)

<a id="hosted-mcp"></a>

## MCP المستضاف: عملاء متصفح أو عملاء بعيدون متوافقون

في إعدادات الموصّل المخصص أو MCP البعيد للعميل، أضف اتصالاً باسم SosoAPI باستخدام عنوان الخادم أدناه. اختر OAuth مع التسجيل التلقائي للعملاء عند عرضه. سجّل الدخول إلى SosoAPI واختر Workspaces والإجراءات المسموحة، ثم عد إلى محادثتك وفعّل الاتصال عند الحاجة. اطلب من الوكيل فحص الحسابات المفوّضة.

الاستخدام https://sosoapi.ai لاتصال مستضاف جديد. نقطة النهاية القديمة https://gqeshlawtcexsapabaui.supabase.co/functions/v1/remote-mcp يظل مدعوماً. حافظ على الاتصال المحلي أو المستضاف الذي يعمل؛ لا حاجة لاستبداله لمجرد تغيير عنوان URL.

لا يلزم لصق مفتاح API أو معرّف عميل أو سر عميل. تعتمد تطبيقات ChatGPT المخصصة لـ MCP على خطة العميل ووضع المطوّر وإعدادات المسؤول. تصف هذه التعليمات اتصالاً مخصصاً لا إدراجاً في دليل التطبيقات. لا يقرأ MCP المستضاف الملفات المحلية؛ استخدم استيراد URL عام أو MCP المحلي لرفع الملفات المحلية.

```
https://sosoapi.ai
```

- [تسجيل عميل OAuth مخصص ووصفة الرمز](https://sosoapi.ai/auth.md)

<a id="check-local-sign-in"></a>

## فحص اختياري لتسجيل الدخول بالطرفية

للاتصال المحلي، نفّذ auth status أولاً. نفّذ auth login فقط إذا أفاد بأنك غير مسجّل. أكمل مسار المتصفح وافحص الحالة مجدداً. لا تُطبع الرموز. يفحص ذلك مصادقة CLI المحلية لا تسجيل دخول موصّل مستضاف منفصل.

```
npx -y sosoapi auth status
```

```
npx -y sosoapi auth login
```

<a id="4-connect-your-social-account"></a>

## 4. صِل حسابك الاجتماعي

افتح وصل الحسابات أو استخدم الأمر المحلي أدناه. استبدل threads بـ instagram أو facebook أو youtube أو x حسب الحاجة. يفتح ذلك مسار الاتصال ولا ينشر محتوى.

تحقّق من Organization وWorkspace المعروضتين. اختر المنصة وسجّل الدخول عبر صفحة تفويضها وحدد الحساب أو Page أو القناة بدقة. أكمل الموافقة وأي تأكيد لاختيار الحساب عند العودة. ثم اطلب من الوكيل تحديث الحسابات المتصلة لـ Workspace المقصودة.

أعد استخدام اتصال سليم موجود. إن كان تابعاً إلى Organization أو Workspace أخرى، احسم الاختيار في التطبيق؛ يجب ألا يفصله الإعداد المعتاد أو ينقله. النتيجة المتوقعة: ظهور الحساب الصحيح في Workspace المقصودة بمعلومات الصحة والقدرات الحالية. نجاح رد الاتصال وحده ليس إثباتاً لإذن النشر.

تحقّق من الوجهة المقصودة

| الوجهة | ما يجب فحصه |

| --- | --- |

| Threads | الملف الشخصي المقصود والإذن المطلوب لصيغة النص أو الوسائط المطلوبة. |

| Instagram | إعداد حساب مهني مدعوم وإذن نشر للصيغة المطلوبة. |

| Facebook | الـ Page التي تديرها والأذونات المطلوبة لها. |

| YouTube | القناة المقصودة، خصوصاً إذا كان حساب Google واحد يدير عدة قنوات. |

| X | قدرات النص أو الفيديو للحساب ورصيد X المتبقي للـ Organization. |

```
npx -y sosoapi connect threads
```

- [وصل الحسابات](https://app.sosoapi.ai/connect?lang=en)

<a id="5-verify-access-without-publishing"></a>

## 5. تحقّق من الوصول دون نشر

ألصق التالي في محادثة الوكيل المتصل.

يمكن للوكيل استخدام sosoapi_get_workspace_context وsosoapi_list_connected_accounts وإعادة استخدام السياق المعروف وتمرير workspace_id المحدد صراحةً. قد تنشئ تهيئة الحساب أول Workspace لك؛ هذا الفحص للإعداد لا ينشئ منشوراً اجتماعياً.

قبل المتابعة، أكّد Workspace والوجهة ودورك ووصول الوكيل ودعم الوجهة للصيغة المقترحة. استخدم استكشاف الأخطاء إذا فشل فحص. إعادة تثبيت الحزمة لا تصلح إذن منصة مفقوداً.

> تحقّق من إعداد SosoAPI لدي دون نشر أو جدولة أي شيء.
> اعرض Workspaces التي أستطيع استخدامها والحسابات الاجتماعية في Workspace التي أختارها.
> للحساب الذي أختاره، اعرض المنصة وتسمية الحساب وصحة الاتصال وقدرات النشر للصيغة التي أقترحها.
> إذا احتمل تطابق عدة Workspaces أو حسابات، فاسألني أيها أستخدم.
> احتفظ بالمعرّفات الداخلية لاستدعاءات الأدوات؛ لا تطلب مني إيجادها أو اختراعها.

<a id="6-prepare-and-approve-your-first-post"></a>

## 6. جهّز منشورك الأول ووافق عليه

ابدأ بمنشور حقيقي واحد ووجهة واحدة. استبدل الحقول بين الأقواس في طلب المسودة هذا. يتولى الوكيل الكتابة؛ يوفّر SosoAPI عمليات الاتصال والنشر. راجع الادعاءات والإملاء والروابط والوسائط بنفسك.

استخدم تاريخاً ووقتاً محلياً ومنطقة IANA صريحة لمنشور مستقبلي. إذا جعل التوقيت الصيفي الوقت المحلي ملتبساً، اختر أي تكرار تقصد قبل الإرسال. النتيجة المتوقعة الآن: مسودة دقيقة لمراجعتك، دون إرسال طلب نشر.

> ساعدني في إعداد إعلان منتج واحد باستخدام SosoAPI.
> 
> المنتج: [اسم المنتج العام]
> حقائق متحقّق منها: [المتاح اليوم]
> الجمهور: [من يستفيد من هذا]
> الوجهة: [تسمية الحساب والمنصة]
> اللغة: [اللغة]
> التاريخ والوقت المحليان المفضلان: [YYYY-MM-DD HH:mm]
> المنطقة الزمنية: [منطقة IANA، مثل Asia/Hong_Kong]
> الوسائط: [بلا وسائط أو ملف محلي أو URL عام للوسائط]
> 
> استخدم الحقائق التي قدّمتها فقط. افحص متطلبات صيغة الوجهة.
> اعرض المسودة والوسائط والوجهة والتاريخ والوقت والمنطقة الزمنية بدقة للمراجعة.
> لا تُجدول ولا تنشر بعد.

<a id="approve-and-schedule"></a>

## وافق على المنشور الدقيق قبل الجدولة

بعد صحة كل التفاصيل، أعطِ تعليمة محددة بالطلب أدناه. ينشئ ذلك جدولاً حقيقياً يمكن أن ينشر علناً. استخدم محتوى وحساباً تنوي النشر عليه. يحتاج النشر الفوري أيضاً إلى تعليمة صريحة بعد مراجعة التفاصيل نفسها.

النتيجة المتوقعة: معرّف Scheduled Post والوجهة المقصودة والوقت المقبول والحالة الحالية. قبول الجدول لا يعني أن المنصة نشرته.

> جدوِل المنشور المطابق الموافق عليه أدناه للحساب المسمّى في التاريخ والوقت والمنطقة الزمنية المذكورة.
> 
> [ألصق المحتوى النهائي والوسائط والوجهة والتاريخ والوقت والمنطقة الزمنية.]
> 
> تحقّق أولاً من وجود جدول مطابق. أرسل هذا المنشور مرة واحدة واقرأ النتيجة المحفوظة. أعد معرّفه ووجهته والوقت المقبول وحالته الحالية. إذا كانت النتيجة غير مؤكدة، افحص الطلب القائم قبل إجراء آخر.

<a id="7-check-the-result-reschedule-or-cancel"></a>

## 7. افحص النتيجة أو أعد الجدولة أو ألغِ

اطلب من الوكيل قراءة Scheduled Post نفسه باستخدام sosoapi_get_scheduled_post. يمكنك أيضاً فتح https://app.sosoapi.ai/scheduled-posts/<post-id> بعد تسجيل الدخول بحساب مفوّض. افحص كل وجهة على حدة إذا استهدف الطلب عدة حسابات؛ قد تنجح بعضها وتحتاج أخرى إلى الانتباه.

> اقرأ النتيجة الحالية لـ Scheduled Post [المعرّف المعاد].
> اعرض وجهته ووقت جدولته وحالته الحالية ونتيجة النشر.
> إذا تأكّد النشر، أدرج الرابط المباشر عند توفره.
> لا تُعد المحاولة أو الجدولة ولا تُنشئ منشوراً آخر.

فهم النتيجة المحفوظة

| النتيجة | المعنى | الخطوة التالية |

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

| مجدول | قُبل لوقت مستقبلي. | احتفظ بالمعرّف وافحصه بعد الموعد المحدد. |

| قيد الإعداد أو النشر أو تسوية الحالة | العمل جارٍ أو نتيجة المنصة النهائية غير معروفة. | اقرأ المنشور نفسه لاحقاً؛ تجنّب إرسال آخر. |

| تم النشر | تؤكد أدلة مستندة إلى المنصة اكتمال النشر. | افتح permalink المعاد عند توفره. |

| فشل أو يحتاج إلى الانتباه | يلزم إصلاح محدد أو إجراء مسموح. | اقرأ السبب والإجراءات المتاحة. |

| يلزم إعادة الجدولة أو انتهت الصلاحية | لا يمكن متابعة الجدول الأصلي كما طُلب. | راجع التفسير واختر إجراءً متاحاً. |

| أُلغي | تأكّد الإلغاء. | لا تتوقع نشر هذا الجدول. |

<a id="manage-a-pending-post"></a>

## إدارة منشور معلّق والعودة لاحقاً

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

بعد استلام التفاصيل المحفوظة لجدول مستقبلي، يمكنك مغادرة المحادثة والعودة إلى المنشور نفسه لاحقاً. إغلاق محادثة الوكيل لا يعني أنها ستستيقظ تلقائياً أو تنبهك ما لم يُضبط ذلك منفصلاً.

<a id="8-add-images-or-video-then-reuse-the-workflow"></a>

## 8. أضف صوراً أو فيديو ثم أعد استخدام المسار

شغّل مسار المنشور الواحد بنجاح قبل إعداد دفعة أكبر. أخبر الوكيل إن كانت الوسائط ملفاً محلياً أو URL عاماً أو أصلاً موجوداً في SosoAPI.

الملفات المحلية: يستطيع MCP المحلي استخدام sosoapi_upload_asset. يجب أن يكون الملف داخل مجلد رفع مسموح؛ تشرح الأداة المواقع المسموحة إذا خرج المسار عن النطاق. لا يستطيع MCP المستضاف قراءة ملفات حاسوبك.

عناوين URL العامة: استخدم sosoapi_import_asset_url، ثم sosoapi_get_asset_import_status مع include_asset=true. انتظر حتى يصبح الأصل جاهزاً. للأصل الموجود، تأكّد أنه ينتمي إلى Workspace المقصودة وجاهز للصيغة المختارة.

يستخدم طلب الجدولة العادي معرّف الأصل المسجّل وعنوان URL المعتمد للأصل معاً. لا يحل محلهما عنوان معاينة مؤقت أو عنوان المصدر الخارجي الأصلي. في مسار الصورة الواحدة عبر URL المدعوم، تجمع sosoapi_post_image_url الاستيراد والإرسال. إنها عملية نشر: وافق على المنشور كاملاً أولاً. احتفظ بمعرّف المنشور المقبول أثناء المعالجة؛ لا تبدأ استيراداً آخر لمتابعته.

يدعم X منشور TEXT أصلياً بلا وسائط، أو VIDEO بأصل فيديو MP4 واحد مسجّل وجاهز تماماً، لا تقل مدته عن 0.5 ثانية وضمن حد رفع 500 MiB. يتطلب الفيديو can_publish_video متحقّقاً منه للحساب المحدد؛ وصول النص وحده غير كافٍ. قد يحتاج اتصال قديم إلى موافقتك لإعادة الاتصال بإذن رفع الفيديو. يجب أن يلائم أي نص ووسوم ورابط حد X للنص الموزون. الصور والردود والاقتباسات وإعادة النشر ونشر السلاسل غير مدعومة. قبول الرفع أو معالجة الفيديو ليس نتيجة نشر.

قبل الإرسال إلى X، اقرأ sosoapi_get_x_usage للـ workspace_id المقصود والنص النهائي. حصته وتكلفته منفصلتان عن حصة الخطة العامة. لا تتجاوز حد الرصيد بتكرار الإرسال؛ سوِّ نشرًا غير مؤكد قبل إرسال آخر.

<a id="reuse-the-workflow"></a>

## جهّز دفعة مُراجَعة واقرأ الأداء بأمانة

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

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

> باستخدام الإعداد المتحقّق منه نفسه، جهّز سبع مسودات لإعلان المنتج، واحدة يومياً، من الحقائق العامة التي أقدّمها. اعرض جدول مراجعة بالمسودة والوجهة والوسائط والتاريخ المحلي والوقت والمنطقة الزمنية لكل صف. أبقِ المسودات السبع حتى أوافق على الجدول الدقيق.

<a id="9-cli-and-api-walkthrough"></a>

## 9. شرح CLI وAPI

استخدم هذا المسار الاختياري لملفات طلبات صريحة أو تكامل خلفي. يمكن لمستخدمي الوكيل تجاوزه. تستخدم الأمثلة الحساب وWorkspace وأذونات النشر نفسها المستخدمة في MCP.

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

```
npx -y sosoapi --help
npx -y sosoapi api contract --summary
npx -y sosoapi api contract --route /studio-api/scheduled-posts/
```

<a id="api-workspace-context"></a>

## CLI: نفّذ طلب السياق الأول بعد المصادقة

أكمل auth login. احفظ workspaces.json بمحرر نصوص متضمناً JSON أدناه، ثم نفّذ الأمر. استخدم ملفات لنصوص الطلبات بدلاً من إدراج المحتوى داخل أوامر الصدفة.

يعيد CLI الحقول schema_version وhttp_status وbody. تتضمن الاستجابة الناجحة body.active_workspace_id وbody.workspaces. اختر Workspace المقصودة من تلك الاستجابة؛ لا تحدد Workspace النشطة وجهة مهمة جديدة بصمت. قد يهيّئ أول استدعاء لحساب جديد أول Workspace له.

افحص http_status وbody، لا رمز خروج الصدفة فقط. قد يعيد الأمر مغلّف خطأ HTTP دون نجاح عملية API.

```
{}
```

```
npx -y sosoapi api post /identity-api/workspace/list < workspaces.json
```

<a id="api-connected-accounts"></a>

## CLI: اختر الحساب الاجتماعي المتصل

احفظ accounts.json باستخدام معرّف Workspace المعاد لحسابك، ثم نفّذ الأمر. اختر الحساب المقصود من body.accounts. معرّف حسابه في SosoAPI هو social_account_id المستخدم للجدولة؛ لا يحل اسم مستخدم أو معرّف Page من المنصة محله.

```
{
  "workspace_id": "<YOUR_WORKSPACE_ID>"
}
```

```
npx -y sosoapi api post /identity-api/user/social-accounts/list < accounts.json
```

<a id="api-create-schedule"></a>

## CLI: أنشئ جدول Threads نصياً واحداً مُوافقاً عليه

هذا قالب طلب وليس منشوراً جاهزاً للتنفيذ. احفظ post.json بمحرر ملفات واستبدل كل قيمة بين أقواس بقيمك المفوّضة. اختر طابع ISO زمنياً مستقبلياً بإزاحة UTC صريحة، أو Z لـ UTC. display_timezone منطقة زمنية من IANA للعرض؛ لا تجعل وقتاً محلياً ملتبساً مكتملاً.

أنشئ idempotency_key فريداً، مثل UUID، واحتفظ به مع نص الطلب الدقيق. أعد محاولة الطلب المطابق بالمفتاح نفسه؛ تأخّر الرد ليس سبباً لإنشاء مفتاح آخر. المنشور المعدّل طلب مختلف: تحقّق من النتيجة الأصلية قبل اختيار هوية جديدة.

بعد تأكيد المحتوى والحساب والوقت والأذونات والحصة الحالية، نفّذ أمر الإنشاء. يؤدي ذلك إلى جدولة منشور حقيقي. عند القبول، احتفظ بـ body.post.id واقرأ body.post.status وbody.post.scheduled_at وbody.post.destination. توضح body.deduped إن أُعيد استخدام طلب موجود. القبول لا يعني نشراً مؤكداً من المنصة.

```
{
  "workspace_id": "<YOUR_WORKSPACE_ID>",
  "social_account_id": "<YOUR_THREADS_ACCOUNT_ID>",
  "caption": "<YOUR_APPROVED_POST_TEXT>",
  "hashtags": [],
  "media": [],
  "provider_payload": {
    "platform": "threads",
    "publish_options": {
      "post_type": "TEXT"
    }
  },
  "scheduled_at": "<FUTURE_ISO_8601_TIME_WITH_OFFSET>",
  "display_timezone": "Asia/Hong_Kong",
  "idempotency_key": "<NEW_STABLE_REQUEST_KEY>"
}
```

```
npx -y sosoapi api post /studio-api/scheduled-posts/create < post.json
```

<a id="api-read-result"></a>

## CLI: اقرأ المنشور المحفوظ ونتيجته

احفظ post-status.json بالمعرّف المعاد. اقرأ body.post وbody.delivery وbody.actions وbody.outcomes. أكّد نتيجة النشر قبل الإبلاغ عن النجاح. إذا ضاع رد الإنشاء، استعد الطلب الأصلي بهويته المحفوظة؛ لا تنشئ جدولاً آخر بمفتاح جديد.

```
{
  "id": "<RETURNED_POST_ID>"
}
```

```
npx -y sosoapi api post /studio-api/scheduled-posts/get < post-status.json
```

<a id="api-cancel-schedule"></a>

## CLI: ألغِ فقط إذا سمحت النتيجة الحالية

إذا سمحت آخر قراءة بالإلغاء وكنت تقصد الإلغاء، احفظ cancel.json بالمعرّف المعاد ورقم body.post.version الحالي. المثال 1 توضيحي: استبدله بالإصدار الذي قرأته للتو. ثم نفّذ الأمر وأكّد النتيجة.

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

```
{
  "id": "<RETURNED_POST_ID>",
  "expected_version": 1
}
```

```
npx -y sosoapi api post /studio-api/scheduled-posts/cancel < cancel.json
```

<a id="http-from-your-backend"></a>

## HTTP: استدعِ من خادمك الخلفي

لتكامل على الخادم، أنشئ مفتاح API ضمن Connection → API واحفظ السر في إعدادات أسرار خادمك. تطلب الشاشة الحالية اسماً؛ لا تعرض محددات Workspace أو القدرات. مفتاح المستخدم الافتراضي يتيح operate وpublish وengage عبر Workspaces المتاحة له. افحص ملاءمة هذه الصلاحيات لتكاملك. يدعم عقد API قدرات محدودة صراحةً وworkspace_ids لمفتاح محدد النطاق.

يستخدم إعداد الوكيل المعتاد OAuth ولا يحتاج خطوة مفتاح API هذه. في المثال، SOSOAPI_ACCESS_TOKEN متغير مثال على خادمك يحوي المفتاح؛ ليس إعداداً في SosoAPI CLI. متغير رمز الوصول الشخصي الاختياري للـ CLI هو VICKY_API_KEY.

استخدم ملف workspaces.json أعلاه. يعيد HTTP المباشر نص نقطة النهاية دون مغلّف http_status/body للـ CLI؛ اقرأ حالة HTTP الفعلية وJSON. أبقِ بيانات الاعتماد في الخادم الخلفي وخارج كود المتصفح والطلبات النصية ولقطات الشاشة وملفات الطلبات المشتركة.

تضمين الاتصال الاجتماعي في منتج لعملائك مهمة تكامل منفصلة. هذا الشرح لحساب واحد لا يثبت جاهزية مسار إعداد العملاء.

```
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer ${SOSOAPI_ACCESS_TOKEN}" \
  -H 'Content-Type: application/json' \
  --data-binary @workspaces.json \
  'https://gqeshlawtcexsapabaui.supabase.co/functions/v1/identity-api/workspace/list'
```

- [إدارة مفاتيح API: Connection → API](https://app.sosoapi.ai/connection/api?lang=en)

- [مرجع API](https://sosoapi.ai/ar/docs/api)

- [إنشاء مفتاح API والصلاحية الصريحة](https://sosoapi.ai/ar/docs/api/identity-api-api-keys-create)

- [المصادقة والأذونات](https://sosoapi.ai/ar/docs/authentication)

- [مرجع CLI](https://sosoapi.ai/ar/docs/cli-reference)

<a id="10-troubleshooting"></a>

## 10. استكشاف الأخطاء

استخدم الخطأ الفعلي والاتصال الذي تشخّصه. توسيع الأذونات أو تكرار الإرسال لا يصلح كل عطل.

الاستعادة دون فقدان الطلب الأصلي

| العَرَض | ما يجب فحصه أو فعله |

| --- | --- |

| node أو npx غير متاح | ثبّت بيئة Node.js مدعومة لاستخدام MCP محلياً، أو استخدم MCP مستضافاً متوافقاً. |

| يبدو أن npx sosoapi ينتظر إلى الأبد | من دون أمر، يعمل خادم stdio MCP منتظراً عميله. استخدم --help لتعليمات الطرفية. |

| مثبّت، لكن لا توجد أدوات في المحادثة | أعد وصل العميل الفعلي أو تشغيله وفعّل SosoAPI في المحادثة الحالية. |

| تسجيل الدخول يفتح ملف متصفح خاطئاً | أوقف تسجيل دخولك المحلي المعلّق. أكّد وجود --no-open باستخدام --help، ثم نفّذ npx -y sosoapi auth login --no-open. افتح الرابط الجديد في الملف المقصود وتحقّق من الهوية قبل الموافقة. لا تستخدم ملفين بالتزامن على رابط واحد. |

| المنفذ 8789 مشغول | افحص باستخدام lsof -nP -iTCP:8789 -sTCP:LISTEN. أوقف المستمع فقط إذا كان عملية تسجيل الدخول المعلّقة الخاصة بك. |

| فشل التحقق من البريد أو تسجيل الدخول | اقرأ الخطأ الفعلي واستخدم إعادة المحاولة المتاحة. يستخدم تسجيل الدخول بالبريد تحقّقاً في الخلفية، دون مربع CAPTCHA للبحث عنه. المتابعة باستخدام Google خيار آخر. |

| استجابة 401 | افحص تسجيل دخول هذا الاتصال وصلاحية اعتماده. auth status المحلي لا يفحص موصّلاً مستضافاً. |

| 403 أو إجراء نشر مفقود | افحص Workspace المختارة والدور والقدرة الممنوحة. اطلب الوصول المطلوب من المالك عند الاقتضاء. |

| الحساب الاجتماعي المتوقع مفقود | افحص الهوية وWorkspace واختيار حساب المنصة. أكمل أي تأكيد اتصال معلّق. |

| متصل، لكن النشر غير متاح | اقرأ قدرات الحساب المحدد ومتطلبات المنصة. أعد الاتصال فقط إذا لزمت فعلاً موافقة جديدة على المنصة؛ قد يختلف الوصول للفيديو عن النص. |

| مسار الرفع خارج المجلدات المسموحة | استخدم مجلداً مسموحاً أو اضبط SOSOAPI_UPLOAD_ROOTS عمداً في بيئة MCP المحلية. |

| استيراد الوسائط ما زال معلقاً | افحص الاستيراد القائم ومعرّف المهمة. أبلغ عن خطأ التنفيذ أو الإعداد بدلاً من إنشاء استيرادات مكررة. |

| نفدت الحصة أو أرصدة X | اقرأ الحصة ذات الصلة واختر إجراءً مسموحاً للجدولة أو الخطة. تكرار الإرسال لا يزيل الحد. |

| انتهت مهلة طلب الإنشاء | احتفظ بمفتاح الطلب ومعرّف المنشور المقبول إن كان معروفاً. اقرأ الطلب الأصلي أو استعده قبل المحاولة مجدداً؛ تحتفظ المحاولة المطابقة بمفتاحها. |

| تعارض إصدار عند التحديث أو الإلغاء | اقرأ المنشور نفسه مجدداً، وافحص الإجراءات المتاحة، واستخدم إصداره الحالي للإجراء المقصود فقط. |

| خطأ في المخطط أو عدم توافق الإصدارات | حدّث الحزمة التي يشغّلها عميل MCP فعلياً وأعد الاتصال وافحص عقدها. المزيد من الأذونات لا يصلح عدم تطابق المخطط. |

<a id="updates-and-revocation"></a>

## التحديث أو إلغاء الوصول أو طلب المساعدة

يفحص الأمر الأول أدناه تعليمات أحدث حزمة دون تشغيل خادم MCP. إذا ثبّت العميل إصداراً محدداً في أمره المحفوظ، حدّث ذلك الأمر عمداً. تحديث تثبيت عام منفصل لا يحدّث نسخة العميل المثبّتة.

لإلغاء وصول جهاز محلي، استخدم Connection → Agent أو أمر auth logout أدناه. للموصّل المستضاف، ألغِ التفويض المستضاف المطابق ضمن Connection → Agent. تُدار مفاتيح API منفصلةً ضمن Connection → API. إلغاء وصول الوكيل لا يلغي الجداول المقبولة بالفعل؛ أدر تلك المنشورات منفصلةً.

للمساعدة، قدّم العميل وإصدار الحزمة والخطوة الفاشلة والخطأ المعروض والوقت/المنطقة الزمنية. شارك معرّفات الطلبات أو المنشورات ذات الصلة سراً مع الدعم عند الحاجة. لا ترسل اعتمادات أو روابط تفويض أو سجلات خام قد تحتوي رموزاً.

```
npx -y sosoapi@latest --help
```

```
npx -y sosoapi auth logout
```

- [إدارة عملاء الوكيل: Connection → Agent](https://app.sosoapi.ai/connection/agent?lang=en)

- [إدارة مفاتيح API: Connection → API](https://app.sosoapi.ai/connection/api?lang=en)

- [مرجع استكشاف الأخطاء](https://sosoapi.ai/ar/docs/troubleshooting)

- [التواصل مع دعم SosoAPI](mailto:vickyai.tech@gmail.com)

<a id="setup-completion-checklist"></a>

## قائمة إتمام الإعداد

يمكنك إكمال إعداد الاتصال دون إرسال منشور. إذا نشرت، استخدم فحص النتيجة المنفصل لتأكيد مسار النشر الأول.

- يستطيع عميلي استخدام أدوات SosoAPI، أو يستطيع CLI/API لدي تنفيذ طلب مفوّض.

- سجّلت الدخول بالحساب المقصود واخترت Workspace الصحيحة.

- يظهر حسابي الاجتماعي بالقدرات المطلوبة للمهمة.

- أفهم إن كان وكيلي يستطيع تجهيز العمل فقط أم جدولته ونشره أيضاً.

- يمكنني إعداد مسودة ومراجعة الوجهة والمحتوى والوقت بدقة.

- إذا أرسلت منشوراً، فقد احتفظت بمعرّفه ويمكنني التمييز بين القبول والنشر المؤكد.

- أعرف كيفية فحص الفشل وإدارة جدول نشر معلّق وإلغاء الوصول.