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`.

請求範例

可直接貼上的請求主體。請將預留位置 ID 與值換成您自己的。

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 中的頂層物件。品牌擁有您連結至該品牌的社群帳號，以及透過這些帳號發布的每一則貼文。在至少建立 1 個品牌之前，無法呼叫 Social API 中的其他功能，因此這是任何 Social 整合的第一個請求。

使用案例：協助客戶開始使用社群發布功能。當客戶在您的產品中註冊時，請為他們想要發布內容的每個商家各建立 1 個品牌。將傳回的 socialProfile.id 儲存至您自己的該商家紀錄中：它是 POST /social/brands/{brandId}/connections/link 和 GET /social/brands/{brandId}/posts 中的 brandId 路徑佔位符，也是您建立每則貼文時的 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 金鑰所對應的帳戶。無法在其他帳戶中建立品牌：主體中的任何帳戶識別碼都會被忽略。
  • 品牌 ID 是一般 UUID。它們並非 Locations 和地點 Posts 所使用的 Base64 relay ID，因此請勿將其編碼或解碼。同一個 ID 會作為 brandId 路徑佔位符及 socialProfileId 主體欄位出現：brandId 只會是 URL 佔位符，絕不會是主體欄位。
  • API 方案沒有品牌數量上限。品牌數量不限，也不計入用量，因此這項呼叫絕不會因為達到上限而遭拒，您也不需要在建立品牌前檢查剩餘額度。計入用量的是連線，也就是將某個社群網路上的 1 個社群帳號連結至 1 個品牌。請參閱方案與加購項目，瞭解連線級距與連線套組的價格，並在引導使用者透過連線連結完成連結之前，透過 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