المنشورات

انشر منشورًا

تنشر التطبيقات الفعلية فورًا أو تجدول بموعد أو تحفظ مسودة، أما الاختبارية فتحاكي فقط. مع ?dry_run=true يفحص كل شيء ولا يكتب شيئًا.

POSThttps://api.sofia-post.com/api/v1/posts

POST/v1/posts

مفتاح API أو رمز وصوليبقى في هذا التبويب فقط، ويُرسل إلى api.sofia-post.com فقط.dry_run (query)Idempotency-Key (header)جسم الطلب

يؤثر هذا الطلب على حسابك الحقيقي.

curl -X POST 'https://api.sofia-post.com/api/v1/posts' \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"establishmentId":"cmvy2k3m40001ms4rest00000","targets":[{"platform":"instagram","text":"Tarte tatin du jour","format":"post","accountId":"cmvy2k3m40001ms4rig000000"}],"scheduledAt":"2026-11-02T10:00:00.000Z"}'

التفويضات

Authorizationstringمطلوب
مفتاحك الشخصي أو رمز وصول OAuth، يُرسل كـ Bearer <token>.

معاملات الاستعلام

dry_runstring
true: ينفّذ كل فحص كان الإرسال سينفذه (قواعد الشبكات والحسابات والوسائط والإنشاء والاشتراك الفعلي) ولا يكتب شيئًا. يعيد 200 ready أو 422 post_refused.
القيم المسموحة: truefalse

الترويسات

Idempotency-Keystring
عند إعادة الطلب بالجسم نفسه يعيد الاستجابة نفسها دون إنشاء منشور ثانٍ. التجربة الجافة لا تستهلك المفتاح.

الجسم

application/json

establishmentIdstringمطلوب
المنشأة، في مساحة عمل منحة الرمز (GET /v1/establishments)
targetsobject[]مطلوب
شبكة واحدة لكل هدف
عرض الخصائص الفرعية
- platformstringمطلوب
  الشبكة المستهدفة
  القيم المسموحة: instagramfacebookxlinkedintiktok
- textstringمطلوب
  النص المصاحب المنشور على هذه الشبكة
- mediaobject[]
  الوسائط المرفقة
  عرض الخصائص الفرعية
  - idstring
    معرّف وسائط من مكتبة المنشأة (وإلا url وtype)
  - urlstring
    العنوان العام للوسائط (https في الوضع الفعلي)؛ دون معرّف
  - typestring
    نوع الوسائط المعطاة بعنوان
    القيم المسموحة: imagevideo
- formatstring
  الصيغة (post وreel وstory وcarousel...)؛ افتراضيًا الصيغة التي تقدمها الشبكة
- accountIdstring
  في الوضع الفعلي: الحساب المتصل الذي ينشر، عندما تملك المنشأة عدة حسابات على هذه الشبكة (GET /v1/establishments/:id/accounts)
scheduledAtstring<date-time>
موعد الجدولة (ISO 8601)، في المستقبل؛ عند الغياب: النشر فورًا. غير مسموح مع status draft
statusstring
draft: مسودة (في الوضع الفعلي فقط)، تُنشأ بلا موعد ولا يُرسل شيء؛ يجدولها PATCH /v1/posts/:id
القيم المسموحة: draft

الاستجابة

200application/json

تجربة جافة: اجتازت كل الفحوص.

statusstringمطلوب
دائمًا ready
القيم المسموحة: ready
dryRunbooleanمطلوب
دائمًا true
القيم المسموحة: true
targetsobject[]مطلوب
الأهداف المفحوصة
عرض الخصائص الفرعية
- platformstringمطلوب
  شبكة الهدف
- statestringمطلوب
  دائمًا ready
  القيم المسموحة: ready
- accountIdstring
  في الوضع الفعلي: الحساب الذي سينشر
- handlestring
  في الوضع الفعلي: معرّفه المعروض (handle)

201application/json

فعلي: publishing أو scheduled. اختباري: simulated.

idstringمطلوب
معرّف المنشور، لإعادة قراءته بـ GET /v1/posts/:id
statusstringمطلوب
حالة المنشور عند الإنشاء
القيم المسموحة: draftpublishingscheduled
establishmentIdstringمطلوب
منشأة المنشور
targetsobject[]مطلوب
أهداف المنشور
عرض الخصائص الفرعية
- platformstringمطلوب
  شبكة الهدف
- accountIdstringمطلوب
  الحساب الذي ينشر
- statestringمطلوب
  حالة الهدف عند الإنشاء
  القيم المسموحة: draftpublishingscheduledfailed
scheduledAtstring<date-time>
وقت جدولة نشر المنشور

400

جسم مشوّه.

401

الرمز مفقود أو غير معروف أو منتهي الصلاحية أو ملغى.

402

subscription_required (في الوضع الفعلي، بما فيه التجربة الجافة).

403

لا يملك الرمز النطاق posts:write.

404

establishment_not_found: خارج مساحة عمل الرمز.

422application/json

post_refused: سترفض شبكة أو المنشأة أو الإنشاء؛ media_import_refused (في الوضع الفعلي) مع سببه؛ idempotency_key_reused.

4XXapplication/json

أي خطأ آخر، ضمن غلاف الخطأ.