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

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

ينشئ علامة تجارية اجتماعية، وهي الحاوية التي تملك الحسابات الاجتماعية المتصلة والمنشورات المنشورة منها. عدد العلامات التجارية غير محدود في خطط API.

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

المعلمات

النص الأساسي

الاسمالنوعمطلوبالوصف
inputobjectمطلوبWrapper object. Every field below is a property of `input`, the entire body must be nested under it.
input.profileNamestringمطلوبDisplay name of the brand. Shown wherever the brand is listed and used as the default author name in the composer.
input.timezoneobjectمطلوبThe brand's timezone as `{ label, tzCode, name, utc }`, all strings. `tzCode` is the one that matters: it is the IANA identifier the API validates and uses to interpret every `scheduleDate` / `scheduleTime` on this brand's posts. The other three are display labels.
input.businessIntentstringاختياريOne or two sentences describing what the business does, used to tailor content suggestions. Defaults to `general` when omitted.
input.categoriesarray of stringsاختياريBusiness categories for the brand, e.g. `["Furniture Store"]`. Defaults to an empty list.
input.siteUrlstringاختياريThe brand's website. Used to enrich content suggestions; setting it also queues a one-off read of the site.
input.logostringاختياريPublic https URL of the brand logo.
input.countryIsostringاختياريTwo-letter ISO country code for the brand, e.g. `US`.
input.biostringاختياريShort brand bio.
input.brandHashtagsarray of stringsاختياريHashtags that belong to the brand, offered as suggestions in the composer.
input.competitorHashtagsarray of stringsاختياريCompetitor hashtags to track alongside the brand's own.
input.contentPreferredLanguagestringاختياريPreferred language for generated content, e.g. `en`.

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

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

Request body
{  "input": {    "profileName": "Jenny Home",    "timezone": {      "label": "(GMT-05:00) Eastern Time",      "tzCode": "America/New_York",      "name": "Eastern Standard Time",      "utc": "-05:00"    },    "businessIntent": "A family-run home furnishings store selling handmade furniture and textiles.",    "categories": ["Furniture Store", "Home Goods"],    "siteUrl": "https://jennyhome.example",    "countryIso": "US",    "bio": "Handmade furniture for real homes.",    "brandHashtags": ["jennyhome", "handmadefurniture"]  }}

الاستجابات

200Brand created. `socialProfile.id` is the `brandId` every other Social endpoint takes.
Response
{  "data": {    "createSocialProfile": {      "success": true,      "error": null,      "socialProfile": {        "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": 0,        "timezone": {          "label": "(GMT-05:00) Eastern Time",          "tzCode": "America/New_York",          "name": "Eastern Standard Time",          "utc": "-05:00"        },        "contentPreferredLanguage": "en"      }    }  }}
200Validation failed. The status is still 200: read `success`.
Response
{  "data": {    "createSocialProfile": {      "success": false,      "error": {        "message": "SY90003: timezone.tzCode is not a valid IANA identifier",        "code": "SY90003",        "contextInfo": null      },      "socialProfile": null    }  }}
401Unauthenticated, missing or invalid API key.

ينشئ علامة تجارية: الكائن الأعلى مستوى في Social API. تملك العلامة التجارية الحسابات الاجتماعية التي تربطها بها وكل منشور يُنشر من تلك الحسابات. لا يمكن استدعاء أي شيء آخر في Social API حتى توجد علامة تجارية واحدة على الأقل، لذا فهذا هو الطلب الأول في أي تكامل مع Social API.

حالة استخدام: تهيئة عميل للنشر على وسائل التواصل الاجتماعي. عندما يسجّل عميل في منتجك، أنشئ علامة تجارية واحدة لكل نشاط تجاري يريد النشر نيابةً عنه. خزّن socialProfile.id المُعاد مع سجلك الخاص لذلك النشاط التجاري: فهو رمز المسار brandId في POST /social/brands/{brandId}/connections/link وGET /social/brands/{brandId}/posts، وحقل جسم الطلب socialProfileId في كل منشور تنشئه. ثم وجّه المستخدم إلى رابط الاتصال المستضاف لكل منصة يريد النشر عليها.

ملاحظات.

  • يجب تغليف جسم الطلب داخل كائن input. تُغلَّف كل عملية كتابة في Social API بهذه الطريقة، باستثناء واحد: يتلقى رابط الاتصال جسم طلب مسطحًا.
  • تحقّق من success، وليس من حالة HTTP. يُعاد فشل التحقق من الصحة — بسبب غياب profileName أو وجود timezone.tzCode غير معروف — على هيئة HTTP 200 مع success: false والسبب في error. لا تعتبر الاستدعاء ناجحًا إلا عندما تكون قيمة success هي true.
  • لا يُطلب سوى profileName وtimezone. القيمتان الافتراضيتان للحقلين businessIntent وcategories هما general وقائمة فارغة، على الترتيب، لذا يمكن لأي تكامل لا يتضمن ما يعادل هذين الحقلين إغفالهما تمامًا.
  • timezone.tzCode ليس عنصرًا شكليًا. يُفسَّر توقيت المنشور المجدول باستخدام scheduleDate + scheduleTime وفق المنطقة الزمنية للعلامة التجارية، وليس المنطقة الزمنية للجهة المستدعية ولا UTC. لا يؤدي تغييره لاحقًا إلى تغيير توقيت المنشورات المجدولة بالفعل.
  • تنتمي العلامة التجارية دائمًا إلى الحساب المرتبط بمفتاح API. لا توجد طريقة لإنشاء علامة تجارية في حساب آخر: يُتجاهل أي معرّف حساب في جسم الطلب.
  • معرّفات العلامات التجارية هي UUIDs عادية. وهي ليست معرّفات Relay بترميز Base64 المستخدمة في Locations وPosts الخاصة بالمواقع، لذا لا تُجرِ عليها أي ترميز أو فك ترميز. يظهر المعرّف نفسه بوصفه رمز المسار brandId وحقل جسم الطلب socialProfileId: أما brandId فهو دائمًا رمز في URL، ولا يكون أبدًا حقلًا في جسم الطلب.
  • لا يوجد حد لعدد العلامات التجارية في خطة API. العلامات التجارية غير محدودة ولا يُقاس استخدامها، لذا لا يُرفض هذا الاستدعاء أبدًا بسبب حد أقصى، ولا تحتاج إلى التحقق من السعة المتبقية قبل إنشاء علامة تجارية. ما يُقاس استخدامه هو الاتصالات — كل اتصال هو حساب اجتماعي واحد مرتبط بعلامة تجارية واحدة على شبكة واحدة. راجع الخطط والإضافات للاطلاع على شرائح الاتصالات وسعر حزمة الاتصالات، وGET /social/limits لمعرفة سعة الاتصالات المتبقية لديك قبل توجيه مستخدم إلى رابط اتصال.

عملية كتابة: لم تُنفَّذ على الحساب الفعلي. أُنشئ الطلب والاستجابة المعروضان استنادًا إلى مخطط API.

Request
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"      },      "businessIntent": "A family-run home furnishings store selling handmade furniture and textiles.",      "categories": [        "Furniture Store",        "Home Goods"      ],      "siteUrl": "https://jennyhome.example",      "countryIso": "US",      "bio": "Handmade furniture for real homes.",      "brandHashtags": [        "jennyhome",        "handmadefurniture"      ]    }  }'
Run in playground