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 中的顶层对象。品牌拥有您连接到它的社交账号，以及通过这些账号发布的每一篇帖子。在至少创建一个品牌之前，无法调用 Social API 中的任何其他功能，因此这是任何 Social 集成中的第一个请求。

使用场景：为客户开通社交发布功能。当客户在您的产品中注册时，为其希望代为发布内容的每家企业各创建一个品牌。将返回的 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 套餐不限制品牌数量。品牌数量不限且不计量，因此，此调用绝不会因数量上限而被拒绝，您也无需在创建品牌之前检查剩余额度。计量的是连接数，即在一个社交网络上将一个社交账号关联到一个品牌所建立的连接。有关连接数档位和连接包价格，请参阅套餐和附加项；在引导用户打开连接链接之前，请调用 GET /social/limits，以读取您的剩余连接额度。

写入操作：未在实际账户中执行。所示请求和响应根据 API schema 构建。

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