取得 Social 方案限制與用量

回報您的 Social 方案允許的額度，以及您已使用的額度。請在核發連線連結前讀取此資訊，以便在額度用盡時告知客戶，而不是在寫入失敗後顯示 SY95042。

usage.connections 恰好等於 usage.connectionsActive + usage.connectionsReleased。

已釋出的名額會保留至週期結束

中斷管道連線會立即使其離線，但不會歸還名額。在一個計費週期內，上限計算的是您曾使用過的不重複連線數，無論這些連線是否仍維持連線，因此名額會持續被占用，直到訂閱續訂。以下 3 項影響值得在程式碼中處理：

• 剩餘額度是 maxConnections - usage.connections，絕不是 maxConnections - usage.connectionsActive。若改用使用中的連線數，會讓客戶誤以為還有額度，而下一次的連線連結將傳回 SY95042。
• 將同一帳號重新連結至同一品牌是免費的。如果客戶重新連結先前在本週期內從該品牌中斷連線的粉絲專頁，就會重複使用原本保留的名額：connectionsActive 增加、connectionsReleased 減少，而 connections 不變。將同一個粉絲專頁連結至不同品牌會占用另一個名額，而原本的名額仍會保留至續訂時。
• connectionsReleased 是您的續訂額度預測。此值恰好就是週期更替時歸還至共用額度的名額數，可向正在考慮等待續訂或今天就購買套組的客戶顯示此資訊。

這與計費模式的其他部分一致：購買的額度立即可用，放棄的額度則在週期結束時移除。請參閱方案與加購項目。

使用案例：在您的初始設定流程中預先檢查。在向客戶提供「連結帳號」按鈕前，請將 usage.connections（計費數量，而非 connectionsActive）與 maxConnections 比較。如果沒有剩餘額度，請向客戶顯示加購或升級的方式，以免讓 POST /social/brands/{brandId}/connections/link 失敗。品牌沒有對應的檢查：使用 POST /social/brands 建立品牌時，絕不會遇到額度不足的情況。

使用案例：估算下一次加購所需的數量。連線套組每組 5 個連線，因此 maxConnections - usage.connections 可直接告訴您還能連結多少個社群網路，而 ceil((needed - headroom) / 5) 就是需要購買的套組數。

注意事項。

• 品牌數量無上限，且不計量。對於 listingsAPI 帳戶，brands 會傳回 null。先前將此值視為整數上限的用戶端程式碼，必須處理 null，且不應顯示「剩餘 0 個品牌」。
• 連線額度由整個帳戶共用，並非每個品牌各自擁有的額度。只要共用額度還有剩餘，每個品牌就能依需求建立連線，最多連結其支援的 5 個社群網路。請參閱方案與加購項目。
• 此端點僅涵蓋 Social 訂閱。地點上限屬於 Listings 訂閱，並由 POST /locations 另行檢查；當帳戶完全沒有 Listings 方案時，該端點會傳回 SY10155。
• 自助服務帳戶的連線上限為 250 個，無論購買多少套組都一樣。若要超過此上限，帳戶必須轉用 Enterprise。
• 有剩餘額度並不保證能連結 Instagram。Instagram 僅允許連結已連結至 Facebook 粉絲專頁的商業帳號或創作者帳號；個人帳號會在 Meta 的同意畫面遭到拒絕，而非受到此上限阻擋。如果客戶在此仍有剩餘額度，但 Instagram 的連線連結仍然失敗，就需要轉換帳號類型，而不是增加額度。
• 數值會即時更新，但釋出連線不代表退款。使用中斷連線端點或封存品牌後，下次讀取時就會在此反映結果：usage.connectionsActive 減少，usage.connectionsReleased 則增加相同數量。usage.connections 維持不變，因為名額會保留至週期結束。這 2 種釋出方式的行為完全相同。