# SocialEcho OpenAPI - 開發者 LLM 參考

本機器可讀文件面向整合 SocialEcho OpenAPI 的開發、測試、實施、自動化工程師與 AI 智能體。

- 開發者 LLM：https://www.socialecho.net/llms-developers.txt?lang=tc
- 官方開發文件：https://www.socialecho.net/en/helpcenter/docs/socialecho-openapi-docs
- API Base URL：https://api.socialecho.net
- 來源核實日期：2026-07-16

## 快速開始

1. 登入 https://app.socialecho.net，建立或選擇團隊。
2. 在團隊管理中建立 Team API Key。
3. 在請求中加入 `Authorization: Bearer se_your_team_api_key`。
4. 先呼叫 `GET /v1/team`，驗證認證狀態與團隊上下文。
5. 查詢貼文、報告、發布內容、Reddit 社群或 Pinterest 圖板前，先透過 `GET /v1/account` 取得帳號 ID。

## 認證與傳輸

- 認證方式：使用 Team API Key 的 Bearer Token。
- 認證請求標頭：`Authorization: Bearer se_your_team_api_key`。
- JSON 請求：`Content-Type: application/json`。
- 可選語言標頭：`X-Lang: zh_CN` 或 `X-Lang: en`。
- 限流：每個 API Key 每分鐘 120 次請求。
- 不要在瀏覽器程式碼、公開儲存庫、日誌或傳送給不可信服務的提示詞中暴露 Team API Key。

重要傳輸規則：多個 GET 介面透過 JSON 請求本文接收參數，而非查詢字串。瀏覽器 `fetch` 無法可靠傳送 GET 請求本文，請使用 cURL、伺服器端 HTTP 用戶端或受支援的自動化連接器。

## 成功條件與錯誤處理

只有同時符合以下條件才視為成功：

- HTTP 狀態碼為 `200`。
- 回應 JSON 的 `code` 為 `200` 或 `0`。

即使 HTTP 狀態為 `200`，其他業務碼也應按失敗處理。

- `400 Bad Request`：檢查必填欄位、日期、陣列、MIME 類型與平台列舉值。
- `401 Unauthorized`：檢查 Team API Key 與 Bearer 標頭格式。
- `429 Too Many Requests`：將頻率限制在每分鐘 120 次以內，並按 1、2、4 秒等節奏進行指數退避重試。
- 逾時或網路失敗：重試 2 至 3 次，並記錄介面、請求時間、HTTP 狀態、業務碼與不含敏感資訊的關鍵參數。

## 可用介面

### GET /v1/team

回傳目前認證團隊資訊。設定密鑰後應先呼叫此介面。

- 請求本文：`{}`（可選）
- 可選標頭：`X-Lang`

```bash
curl --request GET 'https://api.socialecho.net/v1/team' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: zh_CN' \
  --data-raw '{}'
```

### GET /v1/account

列出已授權帳號或競品帳號。

- `page`：可選整數，頁碼。
- `type`：可選整數；`1` 表示已授權帳號，`2` 表示競品帳號。

```bash
curl --request GET 'https://api.socialecho.net/v1/account' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: zh_CN' \
  --data-raw '{"page":1,"type":1}'
```

### GET /v1/article

列出團隊或指定帳號的貼文。

- `page`：可選整數，頁碼。
- `account_ids`：可選整數陣列，SocialEcho 帳號 ID。

```bash
curl --request GET 'https://api.socialecho.net/v1/article' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: zh_CN' \
  --data-raw '{"page":1,"account_ids":[163956,163955,28]}'
```

### GET /v1/report

回傳指定日期範圍內的分析資料。

- `start_date`：必填字串，格式為 `YYYY-MM-DD`。
- `end_date`：必填字串，格式為 `YYYY-MM-DD`。
- `time_type`：必填整數；`1` 表示範圍內新建貼文，`2` 表示範圍內統計的全部歷史貼文。
- `account_ids`：可選整數陣列，帳號 ID。
- `group`：可選字串；空值表示彙總，可用 `day`、`app` 或 `account` 分組。

```bash
curl --request GET 'https://api.socialecho.net/v1/report' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: zh_CN' \
  --data-raw '{"start_date":"2026-01-01","end_date":"2026-03-24","time_type":1,"group":"day","account_ids":[163956,163955,28]}'
```

### GET /v1/upload/url

回傳媒體檔案上傳資訊。常用流程為：取得上傳網址 → 上傳檔案 → 發布時將回傳 URL 寫入 `attachments`。

- `content_type`：必填 MIME 類型。
- 圖片類型：`image/jpeg`、`image/jpg`、`image/png`、`image/gif`、`image/webp`、`image/bmp`。
- 影片類型：`video/mp4`、`video/avi`、`video/mov`、`video/wmv`、`video/flv`、`video/webm`、`video/mkv`、`video/3gp`、`video/quicktime`。

```bash
curl --request GET 'https://api.socialecho.net/v1/upload/url' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: zh_CN' \
  --data-raw '{"content_type":"image/png"}'
```

### GET /v1/reddit/communities

發布 Reddit 內容前，列出已連接帳號可用的社群。

- `account_id`：必填整數，SocialEcho 帳號 ID。

### GET /v1/pinterest/boards

發布 Pinterest 內容前，列出已連接帳號可用的圖板。

- `account_id`：必填整數，SocialEcho 帳號 ID。

### POST /v1/publish/article

建立草稿、立即發布或排程發布跨平台內容。平台專用欄位必須結合目前產品介面與官方 OpenAPI 文件驗證。

- `account_id`：必填整數，目標帳號 ID。
- `type`：必填字串，平台專用發布類型。
- `status`：必填整數；`0` 表示草稿，`1` 表示發布。
- `scheduled_at`：可選排程時間；當 `status=1` 且省略此欄位時立即發布。
- `comment`：必填字串陣列，可為空陣列。
- `content`：可選貼文本文。
- `extra`：必填物件，包含標題、圖板或社群 ID、連結、TikTok 草稿標記、Reddit flair 等平台專用欄位。
- `attachments`：必填物件陣列；每項使用已上傳檔案 URL，例如 `{ "url": "https://..." }`。

OpenAPI 中的常用 `type`：

- Facebook：`reels`、`post`、`stories`。
- Instagram：`reels`、`post`、`stories`。
- YouTube：`shorts`、`video`。
- X：`short_post`、`long_post`。
- LinkedIn：`post`。
- TikTok：`video`、`photo`。
- Pinterest：`post`。
- Reddit：`text`、`link`、`media`。

```bash
curl --request POST 'https://api.socialecho.net/v1/publish/article' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: zh_CN' \
  --data @publish-payload.json
```

## 建議整合流程

1. 透過 `GET /v1/team` 驗證密鑰與團隊。
2. 透過 `GET /v1/account` 取得已授權帳號並保存回傳的 SocialEcho 帳號 ID。
3. 分頁介面持續增加 `page`，直到 `total` 與 `per_page` 表示已到最後一頁。
4. 發布媒體前呼叫 `GET /v1/upload/url`，上傳檔案並將結果 URL 寫入 `attachments`。
5. 發布 Reddit 或 Pinterest 前，先取得社群或圖板。
6. 將最終請求本文傳送到 `POST /v1/publish/article`。
7. 透過 `GET /v1/article` 與 `GET /v1/report` 完成從發布到分析的資料閉環。

## 目前 API 範圍

目前公開 OpenAPI 涵蓋團隊、帳號、貼文、報告、上傳網址、Reddit 社群、Pinterest 圖板與內容發布。來源文件沒有把留言、私訊介面或官方 MCP 伺服器列為已上線介面，因此不應假設這些介面可用。

平台專用 `extra` 欄位與發布限制可能變更，請以官方文件為準：https://www.socialecho.net/en/helpcenter/docs/socialecho-openapi-docs