Listings APIListings API
تسجيل الدخول
POST/api/v4/social/posts

إنشاء منشور على وسائل التواصل الاجتماعي

ينشئ منشورًا كمسودة، أو منشورًا مجدولًا، أو منشورًا يُنشر فورًا على حسابات Facebook وInstagram وX وLinkedIn وPinterest المتصلة بعلامة تجارية.

يتطلب مفتاح API. راجع المصادقة لمعرفة تنسيق الترويسة وتدوير المفاتيح.

المعلمات

النص الأساسي

الاسمالنوعمطلوبالوصف
inputobjectمطلوبWrapper object. Every field below is a property of `input`, the entire body must be nested under it.
input.socialProfileIdstringمطلوبUUID of the brand publishing the post, the same value used as the `brandId` path token elsewhere. Every platform in `platforms` must already have a connection on this brand.
input.namestringمطلوبInternal name for the post (not shown to the audience). Used to find it again in lists.
input.platformsarray of stringsمطلوبPlatforms to publish to: `FACEBOOK`, `INSTAGRAM`, `TWITTER` (X), `LINKEDIN`, `PINTEREST`.
input.contentstringمطلوبThe post body, published to every platform in `platforms`.
input.actionstringمطلوب`DRAFT` to save without publishing, `SCHEDULE` to publish at a future time (requires a schedule), or `PUBLISH` to publish now.
input.mediaUrlsarray of stringsاختياريPublic https image URLs to attach. Instagram and Pinterest require at least one.
input.videoUrlsarray of stringsاختياريPublic https video URLs to attach.
input.linkstringاختياريLink to attach to the post where the platform supports one.
input.scheduledAtstringاختياريPublish time as an ISO-8601 timestamp with an offset, e.g. `2026-10-02T09:30:00-04:00`. Required when `action` is `SCHEDULE` unless you send `scheduleDate` + `scheduleTime`. Never send both forms.
input.scheduleDatestringاختياريPublish date as `YYYY-MM-DD`, interpreted in the **brand's** timezone. Must be sent together with `scheduleTime`.
input.scheduleTimestringاختياريPublish time as `HH:MM` (24-hour), interpreted in the **brand's** timezone. Must be sent together with `scheduleDate`.
input.connectedChannelIdsarray of stringsاختياريRestrict publishing to specific connections by their `id` from the connections list. Defaults to the brand's active connection for each platform in `platforms`.
input.clientReferencestringاختياريYour own identifier for this post, stored and echoed back. Use it to reconcile the post against your own records without holding onto the returned UUID.

مثال على الطلب

نص جاهز للصق. استبدل المعرّفات والقيم النموذجية بقيمك.

Request body
{  "input": {    "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",    "name": "Autumn collection launch",    "platforms": ["INSTAGRAM", "FACEBOOK", "LINKEDIN"],    "content": "Our autumn collection lands today. Solid oak, hand-finished, made two blocks from the shop. Come see it in person this weekend.",    "mediaUrls": ["https://cdn.example.com/social/autumn-collection.jpg"],    "link": "https://jennyhome.example/autumn",    "action": "SCHEDULE",    "scheduleDate": "2026-10-02",    "scheduleTime": "09:30",    "clientReference": "campaign-4471-slot-01"  }}

الاستجابات

200Post accepted. Publishing runs asynchronously, poll GET /social/posts/{postId} for per-channel status.
Response
{  "data": {    "createSimpleSocialMediaPost": {      "success": true,      "error": [],      "socialPostId": "c47a1e58-2b93-4f10-a6d7-58e0c9b12345",      "status": "SCHEDULED"    }  }}
200Validation failed. Nothing was created. The status is still 200: read `success` and the `error` array.
Response
{  "data": {    "createSimpleSocialMediaPost": {      "success": false,      "error": [        {          "message": "SY95045: No connected channel for PINTEREST on this brand",          "code": "SY95045",          "contextInfo": [{ "key": "platform", "value": "PINTEREST" }]        },        {          "message": "SY95046: scheduleTime must be HH:MM in the brand's timezone",          "code": "SY95046",          "contextInfo": null        }      ],      "socialPostId": null,      "status": null    }  }}
401Unauthenticated, missing or invalid API key.
404No brand with that ID on this account (`SY95043`).

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

حالة استخدام: جدولة حملة من تقويمك الخاص. يعرف تطبيقك بالفعل ما يريد العميل قوله ومتى. لكل خانة زمنية، استدعِ نقطة النهاية هذه باستخدام action: "SCHEDULE" وإما scheduledAt أو scheduleDate + scheduleTime، ومرّر معرّف الخانة الزمنية الخاص بك بوصفه clientReference حتى تتمكن من مطابقة السجلات دون تخزين معرّف UUID المُعاد. اعرض العنصر على أنه قيد الانتظار إلى أن يفيد GET /social/posts/{postId} بأن المنشور أصبح ظاهرًا على جميع القنوات، ووفّر زر إلغاء مرتبطًا بـ POST /social/posts/cancel.

النشر غير متزامن

action: "PUBLISH" لا ينشر قبل أن يعيد الاستجابة. يقبل الاستدعاء المنشور، ويعيد socialPostId، ويسلّمه إلى مسار معالجة النشر. لمعرفة ما حدث فعليًا، استعلم دوريًا من GET /social/posts/{postId} واقرأ المصفوفة channels[] التي تعرض النتائج لكل قناة: تمثل قيمة status في كل عنصر نتيجة تلك المنصة وحدها. قد ينجح نشر منشور على Instagram ويفشل على LinkedIn في الطلب نفسه، لذا فإن channels[] هو المرجع للنتيجة الفعلية، أما status على مستوى المنشور فهو ملخص.

اختيار موعد للنشر

يتطلب action: "SCHEDULE" صيغة واحدة فقط من صيغتين، ولا يقبل الجمع بينهما مطلقًا:

الصيغةالحقوليُفسَّر وفقًا لـ
لحظة زمنية مطلقةscheduledAt، بصيغة ISO-8601 مع إزاحة زمنية (2026-10-02T09:30:00-04:00)الإزاحة الزمنية التي أرسلتها
وقت الساعة المحليscheduleDate (YYYY-MM-DD) و scheduleTime (HH:MM)المنطقة الزمنية للعلامة التجارية

يُرفض إرسال الصيغتين معًا، أو إرسال scheduleDate دون scheduleTime، أو إرسال scheduledAt دون إزاحة زمنية، مع إرجاع SY95046. يجب ألا يتضمن DRAFT وPUBLISH أي موعد للنشر على الإطلاق.

ملاحظات.

  • يجب تغليف جسم الطلب داخل كائن input.
  • تحقّق من success، وليس من حالة HTTP. تُعاد حالات فشل التحقق بصيغة HTTP 200 مع success: false وعنصر واحد في المصفوفة error لكل مشكلة. لا يُنشأ أي شيء عندما تكون قيمة success هي false.
  • تُحدَّد العلامة التجارية في جسم الطلب باستخدام socialProfileId. لا يُستخدم brandId إلا كعنصر في مسار URL، ولا يكون حقلًا في جسم الطلب مطلقًا.
  • يجب أن يكون لكل منصة في platforms اتصال قائم بالفعل بالعلامة التجارية. تفشل المنصة التي لا تملك قناة نشطة مع إرجاع SY95045؛ اقرأ اتصالات العلامة التجارية أولًا، ووجّه المستخدم إلى رابط اتصال لاستكمال أي اتصال مفقود.
  • قيم المنصات هي أسماء تعداد مكتوبة بأحرف كبيرة: FACEBOOK، INSTAGRAM، TWITTER، LINKEDIN، PINTEREST. يشير TWITTER إلى X؛ فقد احتفظت القيمة باسمها القديم، وتُرفض أي قيمة مكتوبة بأحرف صغيرة.
  • لن يقبل Instagram وPinterest منشورًا نصيًا فقط: أدرج عنصر mediaUrls واحدًا على الأقل عندما يكون أيٌّ منهما ضمن platforms.
  • معرّفات المنشورات هي معرّفات UUID عادية، وليست معرّفات Relay بترميز Base64 التي تستخدمها منشورات المواقع.
  • لإنشاء أكثر من بضعة منشورات دفعة واحدة، استخدم POST /social/bulk-posts، الذي يقبل بنية الصف نفسها ويتحقق من الدفعة بأكملها مسبقًا.

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

Request
curl -X POST 'https://listingsapi.com/api/v4/social/posts' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",      "name": "Autumn collection launch",      "platforms": [        "INSTAGRAM",        "FACEBOOK",        "LINKEDIN"      ],      "content": "Our autumn collection lands today. Solid oak, hand-finished, made two blocks from the shop. Come see it in person this weekend.",      "mediaUrls": [        "https://cdn.example.com/social/autumn-collection.jpg"      ],      "link": "https://jennyhome.example/autumn",      "action": "SCHEDULE",      "scheduleDate": "2026-10-02",      "scheduleTime": "09:30",      "clientReference": "campaign-4471-slot-01"    }  }'
Run in playground