Listings APIListings API
登入

Social

所有 Social 端點：品牌、託管連結網址、單篇與大量發布、排程、洞察資料，以及規範這一切的連線數量上限。

Social API 可將內容發布至 Facebook、Instagram、X、LinkedIn 和 Pinterest。整個模型由兩種物件構成。品牌是您發布內容時使用的身分：包含名稱、時區，以及附加至該品牌的社群帳號。連線是某個品牌在某個平台上的一個已授權社群帳號。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用於連結單一平台的託管網址。取得連結網址
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，且不會有任何變更。品牌建立時間滿 90 天後，封存會立即生效，並同時封存該品牌的所有連線。

這些連線會立即停止發布，但其占用的名額仍會計入用量，直到計費週期結束，與手動中斷連線的處理方式完全相同。封存無法在當天釋出容量。

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。該帳號會立即停止發布，但其占用的名額要等到計費週期結束後才會歸還至可用名額。在同一計費週期內，將同一帳號重新連結至同一品牌會沿用該名額，不會產生任何費用；若將其連結至其他品牌，則會占用第二個名額。

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 中至少有一個項目。

請從兩種方式中擇一排程貼文，切勿同時使用。scheduledAt 是含有時區偏移量的 ISO-8601 時間戳記。scheduleDate 和 scheduleTime 必須一起傳送，並依品牌的時區解讀。同時傳送兩種排程設定，或將排程時間設為過去的時間，都會傳回 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

取得單一貼文在單一管道上的互動次數和留言。管道為必填項目，因為發布至三個平台的貼文會有三組獨立的資料。

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"        }      ]    }  }'

大量操作在您的速率限制中僅計為一次請求，因此是處理大批資料的高效率方式。

輪詢大量作業

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 端點。