/api/v4/social/brands/{brandId}/connections/linkالحصول على رابط اتصال
يُرجع عنوان URL مستضافًا قصير الصلاحية يرشد المستخدم النهائي خلال خطوات ربط منصة اجتماعية واحدة بعلامة تجارية.
المعلمات
المسار
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| brandId | string | مطلوب | Brand UUID the connection will be attached to. |
النص الأساسي
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| channel | string | مطلوب | Platform to connect: `FACEBOOK`, `INSTAGRAM`, `TWITTER` (X), `LINKEDIN` or `PINTEREST`. |
| redirectUrl | string | مطلوب | Absolute https URL in your application the user is returned to when the flow finishes. Must be a URL you control. |
| errorUrl | string | اختياري | Absolute https URL the user is returned to if they cancel or the platform rejects the authorization. Defaults to `redirectUrl` when omitted. |
| state | string | اختياري | Opaque string echoed back on the return URL unchanged. Use it to correlate the return with the session that started the flow; it is not validated or interpreted. |
مثال على الطلب
نص جاهز للصق. استبدل المعرّفات والقيم النموذجية بقيمك.
{ "channel": "INSTAGRAM", "redirectUrl": "https://app.example.com/social/connected", "errorUrl": "https://app.example.com/social/connect-failed", "state": "sess_9f2c1e64"}الاستجابات
200Link generated. Redirect the end user to `url`; `expiresIn` is how many seconds it stays valid.
{ "data": { "connectSocialAccount": { "status": "success", "url": "https://social.listingsapi.com/connect/start?token=bfac8e06-8d72-4810-9c50-ae7ee12a7b52", "title": null, "token": null, "expiresIn": 900 } }}200The link could not be issued. `status` is `failed` and `title` carries the reason: most often the account is at its connection cap (`SY95042`, counted on billable connections, so recent disconnects have not freed room) or the platform is not enabled for the account (`SY95044`).
{ "data": { "connectSocialAccount": { "status": "failed", "url": null, "title": "SY95042: Connection limit reached for this account", "token": null, "expiresIn": null } }}401Unauthenticated, missing or invalid API key.
404No brand with that ID on this account (`SY95043`).
يُصدر عنوان URL قصير الصلاحية يربط منصة اجتماعية واحدة بعلامة تجارية واحدة. لا تتعامل أبدًا مع بيانات اعتماد OAuth الخاصة بالمنصة: أعد توجيه المستخدم النهائي إلى url المُرجع، ليُكمل خطوات شاشة الموافقة الخاصة بالمنصة ويختار الصفحة أو اللوحة أو المؤسسة التي سينشر فيها، ثم يُعاد توجيهه إلى redirectUrl الخاص بك.
هذه هي عملية الكتابة الوحيدة في Social التي تستخدم جسم طلب مسطّحًا. تُغلَّف كل عملية كتابة أخرى في Social API بكائن input؛ أما هذه العملية فلا. أرسل channel وredirectUrl، واختياريًا errorUrl وstate، في المستوى الأعلى.
حالة استخدام: ربط القنوات ذاتيًا داخل منتجك. اعرض على المستخدم المنصات الـ5، وعندما يختار إحداها، استدعِ نقطة النهاية هذه باستخدام channel لتلك المنصة وstate يحدد جلسته. أعد توجيهه إلى url. عندما يعود إلى redirectUrl الخاص بك مع status=success، استعلم دوريًا عن GET /social/brands/{brandId}/connections حتى تظهر القناة الجديدة، ثم أتح له إنشاء منشوره الأول باستخدام POST /social/posts.
الوجهة التي يُعاد المستخدم إليها
عند انتهاء التدفق، يُوجَّه المستخدم إلى redirectUrl الخاص بك (أو errorUrl) مع إلحاق معاملات الاستعلام التالية:
https://app.example.com/social/connected ?status=success &brandId=6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902 &platform=INSTAGRAM &state=sess_9f2c1e64 &connectedAccountId=b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7ملاحظات.
- تنتهي صلاحية الرابط. يتضمن
expiresInمدة صلاحيته بالثواني. وهو مخصص للاستخدام مرة واحدة: أصدره لحظة نقر المستخدم على «اتصال»، وليس مسبقًا، ولا تخزّنه أبدًا. إذا ترك المستخدم التدفق دون إكماله، فاستدعِ نقطة النهاية هذه مجددًا للحصول على عنوان URL جديد. - يُنشأ سجل الاتصال بشكل غير متزامن. يعود المستخدم إلى
redirectUrlالخاص بك قبل إنشاء صف الاتصال بلحظة، لذا قد تُرجع قراءة قائمة الاتصالات فور عودته نتيجة لا تتضمنه، وهذا أمر طبيعي. استعلم دوريًا عن قائمة الاتصالات لبضع ثوانٍ بدلًا من اعتبار أول قراءة فارغة فشلًا. - يتطلب Instagram حساب أعمال أو حساب منشئ محتوى مرتبطًا بصفحة Facebook. لا يمكن ربط حساب Instagram شخصي، ولن تعرض شاشة الموافقة الخاصة بالمنصة حسابًا من هذا النوع. إذا واجه مستخدموك هذه الحالة، فاطلب منهم تحويل الحساب في تطبيق Instagram وربطه بالصفحة التي يديرونها، ثم أعد إصدار الرابط.
TWITTERهو X. بقيت قيمة التعدادTWITTERللحفاظ على التوافق مع الإصدارات السابقة؛ أما المنتج فهو X. قيم المنصات هي أسماء تعداد بأحرف كبيرة — ويُرفض إرسال"instagram".- يجب أن يكون كل من
redirectUrlوerrorUrlعنوان URL مطلقًا يستخدمhttps. يُرفض عنوان URL النسبي أو الذي يستخدمhttpمعSY95049. - الاتصالات هي المورد الذي يُقاس استخدامه. يستهلك كل ربط سعة من مجموعة واحدة مشتركة على مستوى الحساب — 20 اتصالًا في Social Launch، و125 في Social Growth، بالإضافة إلى 5 اتصالات لكل حزمة اتصالات بسعر 25 دولارًا شهريًا، حتى حد أقصى قدره 250 عبر الخدمة الذاتية. أما العلامات التجارية نفسها فعددها غير محدود، لذا فإن هذا الاستدعاء هو دائمًا الذي تنفد سعته، وليس إنشاء علامة تجارية أبدًا. عندما تمتلئ المجموعة، يُرجع طلب الرابط
status: "failed"معSY95042. راجع الخطط والإضافات واطّلع على السعة المتبقية لديك منGET /social/limits. - هذا هو النظير في Social لـرابط اتصال Facebook على مستوى الموقع، لكنهما منتجان منفصلان، ولا تظهر الاتصالات المنشأة في أحدهما في الآخر.
عملية كتابة: لم تُنفَّذ على الحساب الفعلي. أُنشئ الطلب والاستجابة المعروضان استنادًا إلى مخطط API.
curl -X POST 'https://listingsapi.com/api/v4/social/brands/<brandId>/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/connect-failed", "state": "sess_9f2c1e64" }'