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

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

يعيد قائمة مقسّمة إلى صفحات بالعلامات التجارية الاجتماعية في حسابك، مع الملف التعريفي لكل علامة تجارية ومنطقتها الزمنية وعدد قنواتها المتصلة.

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

المعلمات

الاستعلام

الاسمالنوعمطلوبالوصفالافتراضي
filtersstringاختياريJSON-encoded filter object with two fields. `statuses` (array of strings, **required inside the object**) selects which brand states to return: `ACTIVE` or `ARCHIVED`. `profileName` (string, optional) is a case-insensitive substring match on the brand name. Omit the parameter entirely to return active brands.—
pageintegerاختياري1-based page number. Defaults to 1.—
sizeintegerاختياريRows per page. Defaults to 20.—

الاستجابات

200A page of brands plus `pageInfo` for paging.
Response
{  "data": {    "listSocialProfiles": {      "profiles": [        {          "id": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",          "profileName": "Jenny Home",          "archived": false,          "logo": null,          "profileLogo": null,          "siteUrl": "https://jennyhome.example",          "countryIso": "US",          "bio": "Handmade furniture for real homes.",          "businessIntent": "A family-run home furnishings store selling handmade furniture and textiles.",          "categories": ["Furniture Store", "Home Goods"],          "brandHashtags": ["jennyhome", "handmadefurniture"],          "competitorHashtags": [],          "connectedChannelCount": 3,          "timezone": {            "label": "(GMT-05:00) Eastern Time",            "tzCode": "America/New_York",            "name": "Eastern Standard Time",            "utc": "-05:00"          },          "contentPreferredLanguage": "en"        },        {          "id": "a90f7c22-5db1-4e83-9f40-2b7c6a1e5d33",          "profileName": "Jenny Home Eastside",          "archived": false,          "logo": null,          "profileLogo": null,          "siteUrl": null,          "countryIso": "US",          "bio": null,          "businessIntent": "general",          "categories": [],          "brandHashtags": [],          "competitorHashtags": [],          "connectedChannelCount": 0,          "timezone": {            "label": "(GMT-06:00) Central Time",            "tzCode": "America/Chicago",            "name": "Central Standard Time",            "utc": "-06:00"          },          "contentPreferredLanguage": "en"        }      ],      "pageInfo": {        "total": 11,        "hasNextPage": true,        "totalEngagementPosts": 0,        "totalPublishedPosts": 0      }    }  }}
401Unauthenticated, missing or invalid API key.

يسرد العلامات التجارية في حسابك، صفحة واحدة في كل مرة. كل صف هو كائن العلامة التجارية نفسه الذي يعيده GET /social/brands/{brandId} لعلامة تجارية واحدة، لذا تكفي القائمة عادةً لعرض أداة اختيار العلامة التجارية دون إرسال طلب ثانٍ وتلقّي استجابته.

حالة استخدام: أداة اختيار العلامة التجارية في واجهة المستخدم الخاصة بك. استدعِ هذه العملية مرة واحدة عندما يفتح المستخدم شاشة النشر لديك، واعرض profileName وlogo في كل صف. العلامة التجارية التي تكون قيمة connectedChannelCount فيها هي 0 ليس لديها حساب اجتماعي مرتبط بها بعد، ولا يمكنها النشر؛ ضع شارة عليها ووجّه المستخدم إلى رابط ربط الحساب. تنقّل بين الصفحات باستخدام page وsize ما دامت قيمة pageInfo.hasNextPage هي true.

حالة استخدام: مطابقة سجلاتك. مرّ على جميع الصفحات كل ليلة، وطابق id مع معرّفات العلامات التجارية التي خزّنتها عند الإنشاء. العلامة التجارية التي اختفت من القائمة الافتراضية قد أُرشفت؛ مرّر filters={"statuses":["ARCHIVED"]} لرؤيتها.

ملاحظات.

  • id هو UUID المجرّد المستخدم بوصفه رمز المسار brandId في مواضع أخرى من Social API، وبوصفه socialProfileId في أجسام الطلبات.
  • تُرسَل عوامل التصفية في صورة سلسلة نصية واحدة مرمّزة بصيغة JSON ضمن معامل الاستعلام filters، وليس في صورة معاملات منفصلة. طبّق عليها ترميز URL. إذا أرسلت filters أصلًا، فيجب أن يحتوي على statuses؛ ويمكن تضمين profileName معه اختياريًا.
  • يعتمد تقسيم النتائج إلى صفحات على الإزاحة (page / size)، وليس على المؤشر كما في نقطتي نهاية المواقع والتقييمات. يمثّل pageInfo.total العدد الإجمالي للعلامات التجارية المطابقة، وليس عددها في هذه الصفحة. pageInfo.totalEngagementPosts وtotalPublishedPosts عدّادان للمنشورات مشتركان مع قائمة المنشورات، وقيمة كل منهما هنا هي 0.
  • يحسب connectedChannelCount الاتصالات النشطة فقط؛ وتُستبعَد القناة من العدد فور قطع اتصالها. للحصول على القنوات نفسها، استدعِ GET /social/brands/{brandId}/connections.
  • timezone.tzCode هو معرّف IANA الذي يُحدَّد بالرجوع إليه توقيت كل جدول زمني لتلك العلامة التجارية؛ أما حقول المنطقة الزمنية الثلاثة الأخرى فهي تسميات للعرض.
  • لا يوجد حد أقصى لعدد العلامات التجارية للتحقّق من الالتزام به. عدد العلامات التجارية غير محدود في خطط API، لذا فإن طول هذه القائمة هو للمعلومات فقط. العدد الذي يخضع لحد أقصى هو عدد الاتصالات: اقرأه من GET /social/limits. تؤدي أرشفة العلامة التجارية إلى إيقاف اتصالاتها فورًا، لكن خاناتها تظل محسوبة ضمن maxConnections حتى نهاية فترة الفوترة، لذا قد تظل العلامة التجارية التي غادرت هذه القائمة تشغل خانات حتى التجديد.
Request
curl -X GET 'https://listingsapi.com/api/v4/social/brands' \  -H "Authorization: API $LISTINGSAPI_KEY"
Run in playground