جدولة منشورات وسائل التواصل الاجتماعي عبر REST API

التسلسل الكامل

لجدولة منشور عبر Mellow Hub، تعرّف أولًا على صلاحيات بيانات الاعتماد، ثم اختر القنوات المتصلة، وتحقّق من صحة طلب واحد، ثم أنشئه بمفتاح ثابت لمنع التكرار (idempotency key). بعد ذلك اقرأ المنشور الناتج مرة أخرى لتعرف ما حدث في كل وجهة. فالاستجابة الناجحة لطلب الإنشاء ليست دليلًا على أن كل شبكة قد نشرته.

تستخدم هذه الوصفة REST. أما تطبيق عميل MCP فيتبع التسلسل المكافئ whoami → list_channels → validate_post → create_post → get_post الموضَّح في دليل MCP لوسائل التواصل الاجتماعي.

جرّب فحص المدخلات بمثال جاهز للتشغيل

نزّل أداة Node.js لفحص المدخلات وقالب post.example.json في المجلد نفسه. يحتاج السكربت إلى Node.js 22 أو أحدث، ولا يحتاج إلى أي حزم. اقرأ شيفرته المصدرية، ثم وفّر بيانات اعتماد Hub موجودة لديك في متغير بيئة سري باسم MELLOW_HUB_KEY.

يكفي لهذا الفحص الإذنان channels:read وposts:read. واختر في إعدادات الوصول في Hub القنوات التي تنوي استخدامها فقط. ويحتاج عرض قائمة القنوات إلى الإذن الأول وحده. ولا يتطلب فحص المدخلات هذا أي إذن بالنشر ولا أي اشتراك.

node mellow-hub-check.mjs --channels
# استبدل معرّفات القنوات وعنوان URL للوسائط في post.example.json.
node mellow-hub-check.mjs post.example.json

يتحقق السكربت من القنوات المتاحة لبيانات الاعتماد، ويرسل ملف JSON الذي عدّلته إلى نقطة نهاية التحقق المحمية بالمصادقة في Mellow Hub، ثم يطبع المشكلات المانعة والملاحظات. وينتهي برمز الخروج 0 عندما تنجح فحوص المدخلات هذه، و1 عند وجود مشكلات في المدخلات، و2 عند إخفاق يتعلق بالملف أو الأذونات أو الاتصال أو عند تلقي استجابة غير متوقعة. وحتى الاستجابة HTTP 200 التي تتضمن ok: false تُعدّ إخفاقًا في الفحص.

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

1. تحقّق من الحساب وبيانات الاعتماد

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

curl --fail-with-body https://www.mellow.world/api/hub/v1/whoami \
  -H "Authorization: Bearer $MELLOW_HUB_KEY"

curl --fail-with-body https://www.mellow.world/api/hub/v1/channels \
  -H "Authorization: Bearer $MELLOW_HUB_KEY"

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

2. صِف المنشور الفعلي

احفظ البنية التالية باسم post.json. واستبدل معرّفي القناتين، وعنوان الوسائط النموذجي، والنص، والتاريخ الوارد في المثال. استخدم إزاحة صريحة للمنطقة الزمنية وفق ISO 8601 أو الرمز Z الدال على UTC؛ فالطابع الزمني يمثل لحظة محددة، لا الساعة المحلية للقارئ. وتاريخ 2030 في المثال توضيحي عن قصد.

{
  "caption": "A short look at how this piece was made.",
  "channels": [
    "spc_your_instagram_channel",
    "spc_your_youtube_channel"
  ],
  "media": [
    "https://cdn.example.com/your-video.mp4"
  ],
  "scheduledAt": "2030-01-15T10:00:00Z",
  "options": {
    "instagram": {
      "placement": "reels"
    },
    "youtube": {
      "title": "How this piece was made",
      "privacyStatus": "public"
    }
  }
}

تجلب الشبكة الوسائط وقت النشر، لذا يجب أن يبقى عنوان URL الحقيقي عبر HTTPS متاحًا حينها. ولن ينجح ملف محلي خاص ولا عنوان URL موقَّع انتهت صلاحيته. ويمنح هذا المثال YouTube عنوانه المستقل، ويختار Reels مكانًا للنشر في Instagram. ويظل توفر التنسيقات معتمدًا على حساباتك المتصلة وعلى مزوّد الخدمة.

3. تحقّق من الصحة دون نشر

curl --fail-with-body https://www.mellow.world/api/hub/v1/validate \
  -H "Authorization: Bearer $MELLOW_HUB_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @post.json

افحص الحقول ok وissues وnotes في الاستجابة. وصحّح كل مشكلة مانعة قبل المتابعة. فقد يُرجع التحقق الحالة HTTP 200 مع ok: false، ولذلك لا يكفي فحص حالة HTTP وحدها. وتتحقق نقطة النهاية المحمية بالمصادقة من ملكيتك الفعلية للقنوات، إضافةً إلى قواعد المدخلات.

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

4. أنشئ مرة واحدة، وأعد المحاولة بالطريقة نفسها

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

الطلب التالي يُنشئ المنشور، فلا تشغّله إلا عندما يكون المحتوى وصلاحية النشر على الوجهة صحيحين. في وضع المراجعة ينتظر المنشور الاعتماد؛ وفي وضع الطيار الآلي يمكن أن يُنفَّذ الإجراء المفوَّض في الموعد المجدول.

curl --fail-with-body https://www.mellow.world/api/hub/v1/posts \
  -H "Authorization: Bearer $MELLOW_HUB_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: studio-process-video-slot-001" \
  --data-binary @post.json

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

5. اقرأ النتيجة لكل وجهة

احفظ قيمة post.id المُعادة، واسترجع المنشور بالطلب GET /api/hub/v1/posts/{id} مع ترويسة التفويض نفسها. وافحص كل عنصر في targets ورابطه العام. فقد تكون نتيجة المنشور الموجّه إلى عدة شبكات جزئية: تنجح وجهة وتفشل أخرى.

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

عالِج منشورًا انتهت مهلة طلبه أو نُشر جزئيًا

انتهاء المهلة يعني أن الطرف الذي أرسل الطلب لا يعرف النتيجة. أما النتيجة partial فتعني أن Hub سجّل نتائج مختلفة للوجهات المختارة. فافصل بين الحالتين عندما تقرر ما ترسله بعد ذلك.

ضاعت استجابة الإنشاء

احفظ حمولة الطلب (payload) الأصلية ومفتاح منع التكرار في سجل المهمة قبل الطلب الأول. ثم أعد إرسال ذلك الطلب دون تغيير، بالمفتاح نفسه وبصلاحية سارية. فإذا كان المنشور موجودًا لدى Hub، أعاد معرّفه وحالته الحالية. وتبقى استجابة REST هي HTTP 201، لذلك لا يخبرك الرمز 201 وحده هل أنشأت هذه المحاولة سجلًا جديدًا. وبعد أن تحصل على المعرّف، استخدم GET لمتابعة حالته.

إذا تلقيت 409 idempotency_key_reused، فقارن الطلب بالمهمة المحفوظة لديك. ولا تولّد مفتاحًا آخر تلقائيًا لتتجاوز الخطأ: فذلك يصف عملية جديدة، وقد يؤدي إلى تكرار النشر الأصلي.

فشلت إحدى الوجهات بعد أن نجح النشر في أخرى

اقرأ targets قبل التحضير لإعادة النشر. فمثلًا، إذا كانت حالة Instagram هي published وحالة YouTube هي failed، فأصلح مشكلة YouTube المُبلَغ عنها، وتحقّق من صحة حمولة جديدة لا تتضمن إلا قناة YouTube تلك. وإعادة النشر المقصودة تستخدم مفتاحًا جديدًا، مثل studio-process-video-slot-001-youtube-recovery-1. واحفظ معرّف المنشور الجديد إلى جانب المهمة الأصلية. وتظل أذونات القنوات المعتادة ووضع المراجعة وحصة المنشورات سارية.

وإعادة إرسال الطلب بالمفتاح الأصلي تُرجع المنشور الموجود؛ ولا تعيد تشغيل وجهاته التي فشلت. والوجهة التي ما زالت في الانتظار أو قيد النشر ليست فشلًا مؤكدًا. فلا تُعِد إرسالها لمجرد أن الطرف المستدعي توقف عن الانتظار، ولا تُدرج في طلب إعادة النشر الوجهات التي نُشر فيها المنشور بالفعل.

أسئلة تتكرر في عمليات التكامل الفعلية

هل يمكنني استخدام تعليق مختلف على شبكة واحدة؟

نعم. فالإدخال في perChannel الذي يكون مفتاحه معرّف القناة الحقيقي يستبدل تعليق تلك القناة أو وسائطها. أما الحقول التي تسري على المنصة كلها فمكانها options. واطّلع على الأمثلة التطبيقية في مرجع Hub.

هل يستطيع الوكيل ربط حساباتي على الشبكات الاجتماعية بنفسه؟

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

هل يستهلك الطلب الواحد منشورًا واحدًا من خطتي؟

تُحتسب الحصة لكل وجهة على الشبكات. فراجع الخطط الحالية والحصة المتبقية لبيانات الاعتماد قبل اختيار الوجهات.