انشر منشورًا

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

نوع المنشور: الآن أو مجدول أو مسودة

حقلان في الجسم يحددان متى يُنشر المنشور، وهل يُنشر:

جسم المنشور

وسائط هدف

يحدد كل مدخل في targets[].media وسيطًا من مكتبة الوسائط بـ id الخاص به، أو url عامًا بـ https مع type (image أو video). يتطلب Instagram وTikTok صورة أو فيديو. ولإضافة وسيط إلى مكتبة الوسائط، انظر استيراد وسيط.

تكرار منشور

لا يوجد endpoint مخصص لتكرار منشور: اقرأه بـ `GET /v1/posts/{id}`، ثم أعد إرسال محتواه في طلب POST /v1/posts جديد.

قبل إعادة إرساله، أزل الحقول التي تملؤها Sofia بنفسها. على الأقل:

• id وcreatedAt الخاصان بالمنشور؛
• status للمنشور المقروء (يلخّص حالة الإرسال): حدّد الحالة التي تريدها أو احذفه؛
• في كل هدف: state وpublishedAt وpermalink وerror.

أبقِ establishmentId، ولكل هدف platform وaccountId. لا تعيد القراءة نص الأهداف ولا وسائطها: قدّمها من جديد. وأخيرًا حدّد scheduledAt جديدًا (أو احذفه للنشر فورًا، أو أرسل "status": "draft").

منشورك الأول

1. تحقق من الشبكات المرتبطة

يُنشر المنشور عبر الحسابات المرتبطة بالمنشأة. اسردها؛ وإن نقص أحدها، فأنشئ رابط اتصال. انظر الحسابات المرتبطة.

2. أضف وسيطًا

يتطلب Instagram وTikTok صورة أو فيديو. استورد واحدًا من عنوان URL عام بـ https؛ تنزّله Sofia إلى مكتبة الوسائط وتعيد id الخاص به. انظر استيراد وسيط.

3. تحقق بمحاكاة

أضف ?dry_run=true: تحكم Sofia على كل شبكة بقواعدها الفعلية وبالحساب المرتبط، ولا تكتب شيئًا.

curl -X POST 'https://api.sofia-post.com/api/v1/posts?dry_run=true' \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "establishmentId": "'$ESTABLISHMENT_ID'",
    "targets": [
      { "platform": "instagram", "text": "Tarte tatin du jour", "media": [{ "id": "'$MEDIA_ID'" }] },
      { "platform": "facebook", "text": "Tarte tatin du jour", "media": [{ "id": "'$MEDIA_ID'" }] }
    ]
  }'

{
  "status": "ready",
  "dryRun": true,
  "targets": [
    { "platform": "instagram", "accountId": "fecd0904-…", "handle": "sof_ia_officiel", "state": "ready" },
    { "platform": "facebook", "accountId": "a423b3a4-…", "handle": "Sofia post", "state": "ready" }
  ]
}

4. انشر

أرسل الجسم نفسه دون dry_run، مع Idempotency-Key كي لا تنشر المحاولة الجديدة مرتين أبدًا. دون scheduledAt، يُنشر المنشور فورًا؛ ومع scheduledAt مستقبلي يُجدول.

curl -X POST https://api.sofia-post.com/api/v1/posts \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d @post.json

5. تابعه

يرد المنشور publishing، ثم تنتقل كل شبكة إلى published مع رابطها الدائم، أو إلى failed مع سببها. اقرأه بـ `GET /v1/posts/{id}`، أو سجّل webhook لتُنبَّه.

المحاكاة (dry run)

POST /v1/posts?dry_run=true ينفّذ فحوص منشور حقيقي: قواعد كل شبكة، والحساب المرتبط، والوسائط، والتاريخ، وباقتك. لا يحفظ شيئًا ولا يرسل شيئًا.

جاهز

حين تقبل كل شبكة المنشور، يكون الرد 200 مع status: "ready" ولكل هدف الحساب الذي سينشر.

مرفوض

وإلا يكون الرد 422 post_refused، مع تفصيل لكل سبب. يسمّي كل تفصيل شبكته وcode الخاص به، ويبيّن ما يجب تصحيحه.

{
  "error": {
    "code": "post_refused",
    "message": "The post would not be published: x: the text is too long (300 characters, at most 280)",
    "details": [
      {
        "platform": "x",
        "code": "caption_too_long",
        "max": 280,
        "actual": 300,
        "message": "x: the text is too long (300 characters, at most 280)"
      }
    ],
    "docUrl": "https://www.sofia-post.com/developers/errors#post_refused"
  }
}

كل سبب مدرج في الأخطاء.

لوضع الاختبار للتطبيقات، انظر وضع الاختبار والمحاكاة. ويحمي Idempotency-Key أيضًا POST /v1/posts: انظر قابلية التكرار الآمن.