المنشورات والجدولة

ينتمي المنشور إلى منشأة ويذهب إلى شبكة أو عدة شبكات، هي أهدافه (targets). لكل هدف نصه ووسائطه وصيغته وحالته.

نقاط النهاية

POST/v1/postsGET/v1/postsGET/v1/posts/{id}PATCH/v1/posts/{id}DELETE/v1/posts/{id}

جسم المنشور

الحقل	المعنى
`establishmentId`	المنشأة التي تنشر (`GET /v1/establishments`)
`targets[]`	إدخال واحد لكل شبكة: `platform` و`text` و`media` اختياري و`format` و`accountId`
`targets[].media[]`	وسائط من المكتبة بواسطة `id`، أو `url` عام عبر https مع `type` الخاص به (`image` أو `video`)
`targets[].accountId`	الحساب المستخدم عندما يكون للمنشأة عدة حسابات على تلك الشبكة
`scheduledAt`	تاريخ ووقت بصيغة ISO 8601 في المستقبل؛ إذا غاب خرج المنشور الآن
`status`	`draft` لحفظ مسودة لا تخرج (دون `scheduledAt` حينئذٍ)

الحالات

الحالة	المعنى
`draft`	محفوظ، لا يخرج
`scheduled`	سيخرج في `scheduledAt`
`publishing`	قيد الإرسال إلى الشبكة
`published`	منشور على الإنترنت، مع `permalink`
`failed`	رفضته الشبكة؛ ويوضح `error` السبب
`sent_to_inbox`	أُرسل إلى تطبيق الشبكة، حيث يُكمله المالك (TikTok)

تلخّص status المنشور حالات أهدافه. وتكون partial عندما تنشر شبكة وتفشل أخرى.

التعديل قبل الانطلاق

يعيد PATCH /v1/posts/{id} كتابة الأهداف، أو ينقل scheduledAt، أو يغيّر status: draft تُزيل الموعد وتبقي المحتوى، وscheduled تجدوله من جديد. بعد أن ترسل شبكة المنشور يُجاب بـ 409 post_not_editable.

bash

curl -X PATCH https://api.sofia-post.com/api/v1/posts/$POST_ID \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"status":"scheduled","scheduledAt":"2026-11-20T09:00:00Z"}'

الحذف

يُجيب DELETE /v1/posts/{id} بـ 204. وبينما ترسل شبكة المنشور يُجيب بـ 409 post_in_flight: أعد المحاولة بعد قليل.

عرض المنشورات

يعرض GET /v1/posts كل منشور يصل إليه الرمز، الأحدث أولًا، ويُرشَّح بـ establishmentId وstatus وfrom وto وcreatedBy (me أو app). يطابق المنشور status عندما تكون شبكة واحدة منه على الأقل في تلك الحالة. راجع الترقيم.