Social

جميع نقاط نهاية Social: العلامات التجارية، وروابط الاتصال المستضافة، والنشر الفردي والجماعي، والجدولة، والإحصاءات، والحد الأقصى للاتصالات الذي يحكم كل ذلك.

تنشر Social API على Facebook وInstagram وX وLinkedIn وPinterest. يقوم النموذج بأكمله على كائنين. العلامة التجارية هي الهوية التي تنشر باسمها: اسم، ومنطقة زمنية، وحسابات تواصل اجتماعي مرتبطة بها. الاتصال هو حساب تواصل اجتماعي واحد مُصرَّح بالوصول إليه، مرتبط بعلامة تجارية واحدة على منصة واحدة. تتيح خطة API عددًا غير محدود من العلامات التجارية دون أي تكلفة. الاتصالات هي ما تقيس الخطة استخدامه، لذا فإن الحد الأقصى للاتصالات هو القيد الذي ينبغي مراعاته في التصميم.

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

نظرة سريعة على نقاط النهاية

قيم ستستخدمها في كل موضع

قيم المنصات هي أسماء enum مكتوبة بأحرف كبيرة. يُرفض إرسال "instagram". تشير TWITTER إلى X؛ لم يتغير اسم enum عندما تغير اسم المنتج.

إنشاء علامة تجارية

POST /social/brands

الحقلان profileName وtimezone مطلوبان. المنطقة الزمنية كائن، وtzCode هو الحقل المهم: فهو معرّف IANA المستخدم لتفسير كل قيمة من قيم scheduleDate وscheduleTime في منشورات هذه العلامة التجارية. المفاتيح الثلاثة الأخرى هي تسميات للعرض.

curl -X POST https://listingsapi.com/api/v4/social/brands \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "profileName": "Jenny Home",      "timezone": {        "label": "(GMT-05:00) Eastern Time",        "tzCode": "America/New_York",        "name": "Eastern Standard Time",        "utc": "-05:00"      },      "categories": ["Furniture Store"],      "siteUrl": "https://jennyhome.example"    }  }'

احتفظ بمعرّف العلامة التجارية المُعاد. فهو رمز المسار brandId في كل نقطة نهاية أخرى للعلامات التجارية، وحقل جسم الطلب socialProfileId عند النشر.

سرد العلامات التجارية وقراءتها

تُرجع GET /social/brands صفحة من العلامات التجارية. تُرجع GET /social/brands/{brandId} علامة تجارية واحدة بتفاصيلها الكاملة.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  "https://listingsapi.com/api/v4/social/brands?page=1&size=25"

إذا أُعيدت SY95043 عند استخدام معرّف، فإن العلامة التجارية التي يشير إليها إما غير تابعة لهذا الحساب أو مؤرشفة بالفعل.

تحديث علامة تجارية

POST /social/brands/update

يُوضَع معرّف العلامة التجارية في جسم الطلب ضمن input.profileId، وليس في المسار. أرسل فقط الحقول التي تغيّرها؛ فأي حقل تحذفه من الطلب يحتفظ بقيمته الحالية.

curl -X POST https://listingsapi.com/api/v4/social/brands/update \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"profileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902", "bio": "Handmade furniture for real homes."}}'

أرشفة علامة تجارية

POST /social/brands/archive

يجب أن يكون قد مضى 90 يومًا على إنشاء العلامة التجارية قبل أن يمكن أرشفتها. قبل انقضاء هذه المدة، يُرفض الاستدعاء مع SY95051 ولا يتغير شيء. بمجرد انقضاء المدة المطلوبة، تسري الأرشفة فورًا وتؤرشف جميع الاتصالات التابعة للعلامة التجارية في الوقت نفسه.

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

curl -X POST https://listingsapi.com/api/v4/social/brands/archive \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902"}}'

الحصول على رابط اتصال

POST /social/brands/{brandId}/connections/link

هذه هي الطريقة الوحيدة لإضافة اتصال. تتضمن الاستجابة url مستضافًا وصالحًا لمدة expiresIn ثانية. أعد توجيه المستخدم النهائي إليه، ليمنح التفويض على المنصة، ثم يُعاد إلى redirectUrl لديك مع النتيجة في سلسلة الاستعلام. مرّر errorUrl لتمييز حالات الإلغاء عن حالات النجاح، وstate لتمرير قيمة الربط الخاصة بك خلال إعادة التوجيه ذهابًا وإيابًا.

تذكّر أن جسم هذا الطلب مسطّح، دون غلاف input.

curl -X POST https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/connections/link \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "channel": "INSTAGRAM",    "redirectUrl": "https://app.example.com/social/connected",    "errorUrl": "https://app.example.com/social/failed"  }'

{  "data": {    "connectSocialAccount": {      "status": "success",      "url": "https://social.listingsapi.com/connect/start?token=bfac8e06-8d72-4810-9c50-ae7ee12a7b52",      "expiresIn": 900    }  }}

تحقّق من status قبل إعادة التوجيه. لا تُرجع استجابة failed أي url، وتضع السبب في title، وغالبًا ما يكون بلوغ الحد الأقصى للاتصالات (SY95042) أو منصة غير متاحة للحساب (SY95044).

عرض قائمة اتصالات علامة تجارية

GET /social/brands/{brandId}/connections

يُرجع الحسابات المرتبطة بالعلامة التجارية، مع id لكل حساب، وهو ما تحتاج إليه للنشر عبر اتصال محدد أو لقطعه.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/connections

قطع اتصال

POST /social/connections/disconnect

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

curl -X POST https://listingsapi.com/api/v4/social/connections/disconnect \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"socialProfileConnectedChannelId": "b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7"}}'

نشر منشور

POST /social/posts

ينشر استدعاء واحد المحتوى نفسه على كل منصة في platforms. يجب أن يكون لكل منصة من هذه المنصات اتصال قائم بالفعل بالعلامة التجارية، وإلا فسيُرجع الاستدعاء SY95045. يتطلب Instagram وPinterest عنصرًا واحدًا على الأقل في mediaUrls.

جدوِل المنشور بإحدى طريقتين، ولا تستخدمهما معًا أبدًا. scheduledAt هو طابع زمني بتنسيق ISO-8601 يتضمن إزاحة زمنية. يُرسَل scheduleDate وscheduleTime معًا، ويُفسَّران وفق المنطقة الزمنية للعلامة التجارية. يؤدي إرسال الطريقتين معًا، أو تحديد موعد جدولة في الماضي، إلى إرجاع SY95046.

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"],      "content": "Our autumn collection lands today.",      "mediaUrls": ["https://cdn.example.com/social/autumn-collection.jpg"],      "action": "SCHEDULE",      "scheduleDate": "2026-10-02",      "scheduleTime": "09:30",      "clientReference": "campaign-4471-slot-01"    }  }'

اضبط clientReference على المعرّف الخاص بك. يُخزَّن هذا المعرّف ويُرجَع، مما يتيح لك مطابقة المنشور مع سجلاتك دون الاحتفاظ بـ UUID.

قراءة منشور واحد

GET /social/posts/{postId}

بهذه الطريقة تعرف ما إذا كان النشر قد نجح. يمثّل status الخاص بالمنشور ملخصًا؛ أما النتيجة الفعلية فتظهر لكل قناة في connectedChannels، حيث يتضمن كل عنصر status الخاص به، وliveLink بمجرد أن تقبل المنصة المنشور، وreason أو error عندما لا تقبله.

{  "connectedChannels": [    {      "platform": "INSTAGRAM",      "status": "SUCCESS",      "liveLink": "https://www.instagram.com/p/CxYz1234abc/",      "error": null    }  ]}

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

عرض قائمة منشورات علامة تجارية

GET /social/brands/{brandId}/posts

صفحة من منشورات العلامة التجارية، مع عوامل تصفية لتضييق النتائج بحسب الحالة. استخدمها لمطابقة السجلات على دفعات بدلًا من الاستعلام الدوري عن المعرّفات واحدًا تلو الآخر.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  "https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/posts?page=1&size=25"

إلغاء منشور مجدول

POST /social/posts/cancel

يلغي منشورًا لم يُنشر بعد. لا يمكن سحب منشور منشور بالفعل على منصة من خلال نقطة النهاية هذه.

curl -X POST https://listingsapi.com/api/v4/social/posts/cancel \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"socialPostId": "a3f81c62-9d4e-4a17-b5c0-2e7f6d8a9b10"}}'

قراءة الإحصاءات والتعليقات

GET /social/posts/{postId}/insights

أعداد التفاعلات والتعليقات لمنشور واحد على قناة واحدة. يجب تحديد القناة، لأن المنشور الذي يُنشر على ثلاث منصات تكون له ثلاث مجموعات منفصلة من الأرقام.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  "https://listingsapi.com/api/v4/social/posts/a3f81c62-9d4e-4a17-b5c0-2e7f6d8a9b10/insights?socialConnectedChannelId=b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7"

إنشاء منشورات على دفعات

POST /social/bulk-posts

يقبل من 1 إلى 500 صف في input.posts. كل صف هو الكائن نفسه الذي يقبله POST /social/posts بوصفه input، ويمكن أن تستهدف الصفوف علامات تجارية مختلفة في الطلب نفسه.

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

curl -X POST https://listingsapi.com/api/v4/social/bulk-posts \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "name": "October launch batch",      "posts": [        {          "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",          "name": "Launch day",          "platforms": ["FACEBOOK"],          "content": "Doors open at nine.",          "action": "SCHEDULE",          "scheduleDate": "2026-10-02",          "scheduleTime": "09:00"        }      ]    }  }'

تُحتسب العملية الجماعية طلبًا واحدًا ضمن حد معدل الطلبات، مما يجعلها الطريقة الفعالة للدفعات الكبيرة.

الاستعلام الدوري عن مهمة جماعية

GET /social/bulk-posts/{bulkJobId}

يُرجع حالة المهمة مع نتائج لكل صف، بما في ذلك معرّف المنشور الذي أُنشئ لكل صف وأي صف فشل بعد إدراجه في قائمة الانتظار. لا يُحتفظ بالمهام إلى الأبد؛ فالاستعلام عن معرّف انتهت مدة الاحتفاظ به يُرجع SY95047.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  https://listingsapi.com/api/v4/social/bulk-posts/f47ac10b-58cc-4372-a567-0e02b2c3d479

التحقق من الحدود والاستخدام

GET /social/limits

اقرأ هذا قبل إنشاء الاتصالات، بدلًا من قراءته بعد تلقي SY95042. قارن usage.connections بـ maxConnections: فهذا هو العدد الخاضع للفوترة، أي الاتصالات القائمة حاليًا مضافًا إليها الاتصالات التي أُزيلت سابقًا خلال هذه الفترة. يمثّل usage.connectionsActive الاتصالات النشطة في هذه اللحظة، ويمثّل usage.connectionsReleased مقدار السعة التي تُستعاد عند التجديد.

يُرجع brands القيمة null، مما يعني أنه غير محدود. لا يخضع عدد العلامات التجارية لقياس الاستخدام ضمن خطة API.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  https://listingsapi.com/api/v4/social/limits

الأخطاء التي ستواجهها

تتوفر القائمة الكاملة في مرجع رموز الأخطاء.

الخطوات التالية

اقرأ الخطط والإضافات لمعرفة كيفية تفاعل الحد الأقصى للاتصالات وحزم الاتصالات التي تضم 5 اتصالات وقاعدة الأرشفة بعد 90 يومًا، واقرأ الاستجابة للأحداث باستخدام webhooks لتلقي أحداث social_post.* وsocial_connection.* بدلًا من الاستعلام الدوري.

تغطي حزمة Python SDK نقاط النهاية هذه عبر client.social.brands وclient.social.connections وclient.social.posts وclient.social.bulk؛ راجع مورد Social. لا تغطي حزمة Node SDK منتج Social بعد، لذا استدعِ نقاط نهاية REST مباشرةً من Node.