連線 API

連線 API 可列出並檢查品牌下已連線的社群媒體帳號（Instagram、Threads、Bluesky、Facebook Page、TikTok、YouTube）。發佈內容前，請使用此 API 取得目標 connection_id 並驗證權限。

📌 端點

方法	路徑	說明	必要權限範圍
`GET`	`/v1/brand/connections`	列出已連線的 SNS 帳號，並提供選填的平台篩選	`connections:read` 或 `*`
`GET`	`/v1/brand/connections/{connection_id}`	檢索連線詳細資訊與即時授權診斷	`connections:read` 或 `*`

📋 列出連線 (`GET /v1/brand/connections`)

檢索品牌下所有已連線的 SNS 帳號。

查詢參數

參數	類型	必要性	說明
`sns_type`	`string`	選填	按 `instagram`、`threads`、`bluesky`、`facebook_page`、`tiktok` 或 `youtube` 篩選

請求範例

curl -X GET "https://api.ankk.app/v1/brand/connections?sns_type=instagram" \
  -H "Authorization: Bearer spk_live_xxxxxxxx"

回應範例 (`200 OK`)

{
  "items": [
    {
      "id": "conn_01jm8x9k2example",
      "sns_type": "instagram",
      "platform": "meta.instagram",
      "display_name": "ACME Official",
      "username": "acme_official",
      "profile_image_url": "https://example.com/profiles/acme.jpg",
      "status": "connected",
      "created_at": "2026-08-01T10:00:00Z"
    }
  ]
}

🔍 取得連線詳細資訊 (`GET /v1/brand/connections/{connection_id}`)

取得連線詳細資訊與即時的發佈授權診斷結果。

請求範例

curl -X GET "https://api.ankk.app/v1/brand/connections/conn_01jm8x9k2example" \
  -H "Authorization: Bearer spk_live_xxxxxxxx"

回應範例 (`200 OK`)

{
  "id": "conn_01jm8x9k2example",
  "sns_type": "instagram",
  "platform": "meta.instagram",
  "display_name": "ACME Official",
  "username": "acme_official",
  "profile_image_url": "https://example.com/profiles/acme.jpg",
  "status": "connected",
  "created_at": "2026-08-01T10:00:00Z",
  "publish_authorization": {
    "status": "scope_authorized",
    "required_scopes": ["instagram_business_basic", "instagram_business_content_publish"],
    "missing_scopes": [],
    "retryable": false
  }
}

授權狀態碼 (`publish_authorization.status`)

狀態	意義與操作
`scope_authorized`	已取得完整授權，可以發佈。
`scope_permission_unverified`	權限仍待驗證，可以嘗試發佈。
`scope_permission_missing`	缺少必要的權限範圍。需要在網頁介面進行重新授權。
`scope_review_disabled`	因平台應用程式審查狀態或開發者模式限制而被阻擋。
`unsupported`	此連線不支援此操作。

🔗 相關文件