Listings APIListings API
登录

Social

Social 的所有端点：品牌、托管连接链接、单条和批量发布、定时发布、洞察数据，以及约束所有这些功能的连接数上限。

Social API 可将内容发布到 Facebook、Instagram、X、LinkedIn 和 Pinterest。整个模型由 2 种对象构成。品牌是您发布内容时使用的身份，包含名称、时区和关联的社交账号。连接是某个品牌在某个平台上的 1 个已授权社交账号。API 套餐不限制品牌数量，品牌也不产生费用。套餐按连接数计量，因此设计时需要考虑连接数上限这一约束。

连接账号的操作无法在您的服务器上完成。最终用户必须在平台上授权，因此您需要请求一个托管链接，并将用户重定向至该链接。发布是异步的：每次创建调用都会在帖子被接受后立即返回，您需要通过轮询获取各渠道的结果。

端点概览

方法路径功能参考文档
POST/social/brands创建品牌。创建品牌
GET/social/brands获取该账户的一页品牌。列出品牌
GET/social/brands/{brandId}获取单个品牌及其完整详情。获取品牌
POST/social/brands/update修改现有品牌的字段。更新品牌
POST/social/brands/archive归档品牌及其连接。归档品牌
POST/social/brands/{brandId}/connections/link获取用于连接单个平台的托管 URL。获取连接链接
GET/social/brands/{brandId}/connections获取连接到某个品牌的社交账号。列出品牌的连接
POST/social/connections/disconnect移除单个连接。断开连接
POST/social/posts将单条帖子保存为草稿、安排定时发布或立即发布。创建社交帖子
GET/social/posts/{postId}获取单条帖子及其在各渠道的发布状态。获取社交帖子
GET/social/brands/{brandId}/posts获取某个品牌的一页帖子。列出品牌的帖子
POST/social/posts/cancel取消尚未发布的帖子。取消定时帖子
GET/social/posts/{postId}/insights获取单个渠道的互动次数和评论。获取帖子洞察数据和评论
POST/social/bulk-posts单次请求最多创建 500 条帖子。批量创建帖子
GET/social/bulk-posts/{bulkJobId}获取批量任务的状态及各行的结果。获取批量发帖任务
GET/social/limits获取连接数上限及已用额度。获取 Social 套餐限额和用量

各处都会用到的值

字段可接受的值
platforms[] 和 channelFACEBOOK, INSTAGRAM, TWITTER (X), LINKEDIN, PINTEREST
actionDRAFT, SCHEDULE, PUBLISH

平台值为大写的枚举名称。发送 "instagram" 会被拒绝。TWITTER 代表 X；产品更名时，枚举名称并未更改。

创建品牌

POST /social/brands

profileName 和 timezone 为必填项。时区是一个对象，其中关键字段是 tzCode：它是 IANA 标识符，用于解释该品牌帖子中的每个 scheduleDate 和 scheduleTime。其余 3 个键仅用作显示标签。

Shell
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"      },      "categories": ["Furniture Store"],      "siteUrl": "https://jennyhome.example"    }  }'

请保存返回的品牌 ID。它是其他所有品牌端点中的 brandId 路径占位符，也是您发布内容时请求体中的 socialProfileId 字段。

列出和读取品牌

GET /social/brands 返回一页品牌。GET /social/brands/{brandId} 返回单个品牌及其完整详情。

Shell
curl -H "Authorization: API $LISTINGSAPI_KEY" \  "https://listingsapi.com/api/v4/social/brands?page=1&size=25"

如果使用某个 ID 时返回 SY95043，则该 ID 对应的品牌不属于此账户，或已被归档。

更新品牌

POST /social/brands/update

品牌 id 应放在请求体中，作为 input.profileId，而不是放在路径中。仅发送您要更改的字段；省略的字段会保留当前值。

Shell
curl -X POST https://listingsapi.com/api/v4/social/brands/update \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"profileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902", "bio": "Handmade furniture for real homes."}}'

归档品牌

POST /social/brands/archive

品牌必须已存在 90 天才能归档。不满 90 天时，调用会被拒绝并返回 SY95051，且不会发生任何更改。品牌存在时间达到要求后，归档会立即生效，并同时归档该品牌的所有连接。

这些连接会立即停止发布，但其占用的名额仍会计入用量，直到计费周期结束，与手动断开连接的处理方式完全相同。归档无法在当天释放可用名额。

Shell
curl -X POST https://listingsapi.com/api/v4/social/brands/archive \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902"}}'

POST /social/brands/{brandId}/connections/link

这是添加连接的唯一方式。响应中包含一个托管的 url，有效期为 expiresIn 秒。将最终用户重定向至该地址，用户在平台上授权后，会返回您的 redirectUrl，结果包含在查询字符串中。传入 errorUrl 以区分取消和成功的情况，并传入 state，以在整个往返过程中携带您自己的关联值。

请注意，此请求体采用扁平结构，没有 input 封装层。

Shell
curl -X POST https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/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/failed"  }'
JSON
{  "data": {    "connectSocialAccount": {      "status": "success",      "url": "https://social.listingsapi.com/connect/start?token=bfac8e06-8d72-4810-9c50-ae7ee12a7b52",      "expiresIn": 900    }  }}

重定向前，请检查 status。failed 响应不会返回 url，而是将原因放在 title 中，最常见的原因是达到连接数量上限（SY95042），或账户未开通该平台（SY95044）。

列出品牌的连接

GET /social/brands/{brandId}/connections

返回关联到该品牌的社交账号，每个账户都包含向特定连接发布内容或断开该连接所需的 id。

Shell
curl -H "Authorization: API $LISTINGSAPI_KEY" \  https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/connections

断开连接

POST /social/connections/disconnect

使用上述列表中的连接 id。该社交账号会立即停止发布，但其占用的名额要等到计费周期结束后才会归还到可用名额池。在同一计费周期内，将同一社交账号重新连接到同一品牌会复用该名额，不产生任何费用；将其关联到其他品牌则会占用第 2 个名额。

Shell
curl -X POST https://listingsapi.com/api/v4/social/connections/disconnect \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"socialProfileConnectedChannelId": "b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7"}}'

发布帖子

POST /social/posts

一次调用会将相同内容发布到 platforms 中的所有平台。该品牌必须已建立与其中每个平台的连接，否则调用会返回 SY95045。Instagram 和 Pinterest 要求 mediaUrls 中至少包含 1 个条目。

请使用以下 2 种方式之一安排帖子的发布时间，切勿同时使用。scheduledAt 是带有时区偏移量的 ISO-8601 时间戳。scheduleDate 和 scheduleTime 需一起发送，并按品牌的时区解释。同时使用这 2 种方式，或安排的发布时间已在过去，都会返回 SY95046。

Shell
curl -X POST https://listingsapi.com/api/v4/social/posts \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",      "name": "Autumn collection launch",      "platforms": ["INSTAGRAM", "FACEBOOK"],      "content": "Our autumn collection lands today.",      "mediaUrls": ["https://cdn.example.com/social/autumn-collection.jpg"],      "action": "SCHEDULE",      "scheduleDate": "2026-10-02",      "scheduleTime": "09:30",      "clientReference": "campaign-4471-slot-01"    }  }'

将 clientReference 设置为您自己的标识符。该标识符会被存储并返回，让您无需保存 UUID 即可将帖子与您自己的记录进行核对。

读取单个帖子

GET /social/posts/{postId}

您可以通过此方式确定发布是否成功。帖子自身的 status 是汇总信息；实际结果需按渠道查看 connectedChannels，其中每个条目都包含自身的 status，平台接受后会包含 liveLink，未接受时则包含 reason 或 error。

JSON
{  "connectedChannels": [    {      "platform": "INSTAGRAM",      "status": "SUCCESS",      "liveLink": "https://www.instagram.com/p/CxYz1234abc/",      "error": null    }  ]}

收到 PUBLISH 后，请轮询此接口。某个渠道可能失败，而其他渠道成功，因此请检查每个条目，而不只是顶层的 status。

列出品牌的帖子

GET /social/brands/{brandId}/posts

返回该品牌的一页帖子，并提供按状态缩小范围的筛选条件。您可用它批量核对，而无需逐个轮询 id。

Shell
curl -H "Authorization: API $LISTINGSAPI_KEY" \  "https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/posts?page=1&size=25"

取消定时发布的帖子

POST /social/posts/cancel

取消尚未发布的帖子。已在平台上发布的帖子无法通过此端点撤回。

Shell
curl -X POST https://listingsapi.com/api/v4/social/posts/cancel \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"socialPostId": "a3f81c62-9d4e-4a17-b5c0-2e7f6d8a9b10"}}'

读取洞察数据和评论

GET /social/posts/{postId}/insights

获取单个帖子在单个渠道上的互动次数和评论。必须指定渠道，因为发布到 3 个平台的帖子会有 3 组独立的数据。

Shell
curl -H "Authorization: API $LISTINGSAPI_KEY" \  "https://listingsapi.com/api/v4/social/posts/a3f81c62-9d4e-4a17-b5c0-2e7f6d8a9b10/insights?socialConnectedChannelId=b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7"

批量创建帖子

POST /social/bulk-posts

在 input.posts 中接受 1 至 500 行数据。每行都是与 POST /social/posts 的 input 所接受的对象相同的对象，同一请求中的各行可以面向不同品牌。

创建任何内容之前，会先验证整个批次。如果任何一行验证失败，您会收到 SY95050 及逐行错误信息，且不会有任何内容加入队列，因此请修正后重新发送。超过 500 行会返回 SY95048，同样不会创建任何内容。有效批次会返回一个可供轮询的任务。

Shell
curl -X POST https://listingsapi.com/api/v4/social/bulk-posts \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "name": "October launch batch",      "posts": [        {          "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",          "name": "Launch day",          "platforms": ["FACEBOOK"],          "content": "Doors open at nine.",          "action": "SCHEDULE",          "scheduleDate": "2026-10-02",          "scheduleTime": "09:00"        }      ]    }  }'

批量操作在您的速率限制中计为 1 次请求，因此是处理大批量数据的高效方式。

轮询批量任务

GET /social/bulk-posts/{bulkJobId}

返回任务状态和逐行结果，包括为每行创建的帖子 id，以及加入队列后处理失败的行。任务不会永久保留；查询已过期的 id 时会返回 SY95047。

Shell
curl -H "Authorization: API $LISTINGSAPI_KEY" \  https://listingsapi.com/api/v4/social/bulk-posts/f47ac10b-58cc-4372-a567-0e02b2c3d479

检查限制和用量

GET /social/limits

请在创建连接之前读取此信息，而不是等到收到 SY95042 之后。将 usage.connections 与 maxConnections 进行比较：计费数量是当前已连接的数量加上本计费周期内此前已释放的数量。usage.connectionsActive 表示此刻处于连接状态的数量，usage.connectionsReleased 表示续订时将恢复的容量。

brands 返回的值为 null，表示无限制。API 套餐不按品牌数量计量。

Shell
curl -H "Authorization: API $LISTINGSAPI_KEY" \  https://listingsapi.com/api/v4/social/limits

您会遇到的错误

代码含义处理方法
SY90001账户未订阅 Social。请先添加 Social 产品，再调用这些端点。
SY95042已达到本计费周期的连接数量上限。将 usage.connections 与 maxConnections 进行比较。最近断开连接并不会解除此限制，因为该连接名额会一直占用到本计费周期结束。
SY95043此账户中没有该品牌，或者该品牌已归档。从列出品牌重新读取 id。
SY95044账户未启用该平台。选择账户已启用的平台，或联系支持团队。
SY95045该品牌没有与该平台的连接。引导用户通过连接链接建立连接，或从 platforms 中移除该平台。
SY95046定时发布时间或时区无效。发送 scheduledAt，或同时发送 scheduleDate 和 scheduleTime，切勿同时使用这两种方式。
SY95047没有该批量任务。从批量创建响应中重新读取 job.id。
SY95048超过 500 行。拆分批次。未创建任何内容。
SY95049重定向 URL 无效。redirectUrl 和 errorUrl 必须是绝对 https URL。
SY95050批量验证失败。读取逐行错误信息，修正这些行，然后重新发送整个批次。
SY95051品牌创建未满 90 天。等到品牌创建满 90 天后再归档。

完整列表请参阅错误代码参考。

后续步骤

阅读套餐和附加项，了解连接数量上限、包含 5 个连接名额的连接包与 90 天归档规则如何相互影响；阅读通过 webhook 响应事件，以接收 social_post.* 和 social_connection.* 事件来替代轮询。

Python SDK 通过 client.social.brands、client.social.connections、client.social.posts 和 client.social.bulk 提供这些端点的功能；请参阅 Social 资源。Node SDK 尚不支持 Social，因此请从 Node 直接调用 REST 端点。