Listings APIListings API
تسجيل الدخول
GET/api/v4/social/posts/{postId}

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

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

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

المعلمات

المسار

الاسمالنوعمطلوبالوصف
postIdstringمطلوبPost UUID, the `socialPostId` returned by POST /social/posts or the `socialPostId` of a row from the brand's post list.

الاستجابات

200The post, with per-channel publish state in `connectedChannels`.
Response
{  "data": {    "getSocialMediaPost": {      "name": "Autumn collection launch",      "status": "PUBLISHED",      "initialContent": "Our autumn collection lands today. Solid oak, hand-finished, made two blocks from the shop. Come see it in person this weekend.",      "initialMedia": ["https://cdn.example.com/social/autumn-collection.jpg"],      "initialVideo": [],      "globalPostSchedule": "2026-10-02T13:30:00Z",      "customDataFlag": false,      "approvalState": null,      "actionOn": null,      "comment": null,      "postAutomationId": null,      "connectedChannels": [        {          "id": "b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7",          "platform": "INSTAGRAM",          "socialPlatformId": 2,          "displayName": "Jenny Home",          "userName": "jennyhome",          "userImage": "https://cdn.listingsapi.com/social/channels/b81d5b3c/avatar.jpg",          "status": "SUCCESS",          "liveLink": "https://www.instagram.com/p/CxYz1234abc/",          "reason": null,          "error": null,          "archived": false        },        {          "id": "2d4e6f80-1c33-4b7a-8e05-9a1b2c3d4e5f",          "platform": "FACEBOOK",          "socialPlatformId": 1,          "displayName": "Jenny Home & Co.",          "userName": "jennyhomeco",          "userImage": "https://cdn.listingsapi.com/social/channels/2d4e6f80/avatar.jpg",          "status": "SUCCESS",          "liveLink": "https://www.facebook.com/jennyhomeco/posts/1029384756",          "reason": null,          "error": null,          "archived": false        },        {          "id": "7c5b9a12-8de4-4a31-b0f2-6e3d4c5b8a90",          "platform": "LINKEDIN",          "socialPlatformId": 4,          "displayName": "Jenny Home",          "userName": "jenny-home",          "userImage": null,          "status": "ERROR",          "liveLink": null,          "reason": "Authorization expired",          "error": "The LinkedIn authorization for this channel is no longer valid. Reconnect the channel and post again.",          "archived": false        }      ]    }  }}
401Unauthenticated, missing or invalid API key.
404No post with that ID on this account.

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

حالة استخدام: التحقق بعد النشر. النشر غير متزامن، لذا لا يخبرك POST /social/posts إلا بأن المنشور قد قُبل. استعلم دوريًا من نقطة النهاية هذه باستخدام socialPostId المُعاد واقرأ connectedChannels[]: تعني الحالة status: "SUCCESS" مع وجود liveLink أن المنشور أصبح متاحًا على تلك القناة، بينما تعني الحالة status: "ERROR" مع تعيين error أنه غير متاح عليها، وتوضح السبب. توقف عن الاستعلام الدوري بمجرد ألا تبقى أي قناة في الحالة SCHEDULED.

حالة استخدام: إظهار المنصات التي نُشر عليها منشور العميل. اعرض كل connectedChannels[].liveLink كرابط خارجي ليتمكن المستخدم من فتح المنشور على المنصة نفسها، وأظهر error ضمن عرض القنوات التي فشل النشر عليها بدلًا من اختزال المنشور بأكمله في حالة فشل واحدة.

قراءة حقول الحالة

هناك مستويان للحالة، ويجيب كل منهما عن أسئلة مختلفة.

الحقلالقيمالمعنى
statusDRAFT, PENDING, SCHEDULED, PUBLISHED, FAILED, ARCHIVED, REJECTEDالمنشور ككل.
connectedChannels[].statusSCHEDULED, SUCCESS, ERROR, ARCHIVEDما حدث على تلك المنصة وحدها.

قد تظهر الحالة العامة للمنشور على أنها PUBLISHED بينما تكون إحدى القنوات في الحالة ERROR. اعتمد دائمًا على connectedChannels[] في العرض؛ إذ إن status على مستوى المنشور هو ملخص.

ملاحظات.

  • globalPostSchedule هو وقت النشر الفعلي المحدد بتوقيت UTC. إذا حددت موعد النشر باستخدام scheduleDate + scheduleTime، فهذا هو الوقت الناتج عن تحويلهما وفق المنطقة الزمنية للعلامة التجارية، وهو ما يفيد في التحقق من أن المنطقة الزمنية كانت كما توقعت.
  • error رسالة مقروءة للبشر يمكن عرضها للعميل بأمان؛ أما reason فهو التسمية الداخلية الأقصر التي تقابلها. لا يحتوي أي منهما على رموز الوصول الخاصة بالمنصة أو معرّفات التتبع.
  • connectedChannels[].id هو UUID الخاص بالاتصال من اتصالات العلامة التجارية، وهو القيمة التي تتطلبها الإحصاءات بوصفها socialConnectedChannelId.
  • القناة التي تظهر بالحالة archived: true قد قُطع اتصالها بعد إنشاء المنشور. لن يُنشر عليها؛ راجع قطع الاتصال.
  • القناة التي تظل عالقة في الحالة ERROR بعد انتهاء صلاحية التفويض تحتاج إلى رابط اتصال جديد، وليس إلى إعادة محاولة نشر المنشور.
  • للحصول على أرقام التفاعل بدلًا من حالة التسليم، استدعِ GET /social/posts/{postId}/insights.
  • لعرض قائمة بمنشورات علامة تجارية بدلًا من جلب منشور واحد، استخدم GET /social/brands/{brandId}/posts.
Request
curl -X GET 'https://listingsapi.com/api/v4/social/posts/<postId>' \  -H "Authorization: API $LISTINGSAPI_KEY"
Run in playground