# SocialEcho OpenAPI - 开发者 LLM 参考

本机器可读文档面向集成 SocialEcho OpenAPI 的开发、测试、实施、自动化工程师与 AI 智能体。

- 开发者 LLM：https://www.socialecho.net/llms-developers.txt?lang=zh
- 官方开发文档：https://www.socialecho.cn/helpcenter/docs/socialecho-openapi-docs
- API Base URL：https://api.socialecho.net
- 来源核实日期：2026-08-24（官方文档更新于 2026-08-11）

## 快速开始

1. 登录 https://app.socialecho.net，创建或选择团队。
2. 在团队管理中创建 Team API Key（以 `se_` 开头）。
3. 在请求中添加 `Authorization: Bearer se_your_team_api_key`。
4. 首先调用 `GET /v1/team`，验证认证状态和团队上下文。
5. 判断结果时先看 HTTP 状态码，再看响应体中的业务 `code`。
6. 在查询贴文、报告、发布内容或平台专属资源前，先通过 `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`（默认 zh_CN）。
- 可选幂等追踪：请求可携带 `X-Request-Id`；服务端响应也会返回 `X-Request-Id`。
- 限流：每个 API Key 每分钟 120 次请求。
- 不要在浏览器代码、公开仓库、日志或发送给不可信服务的提示词中暴露 Team API Key。

重要传输规则：多数 GET 接口通过 JSON 请求体接收参数，而不是查询字符串。浏览器 `fetch` 无法可靠发送 GET 请求体，请使用 cURL、服务端 HTTP 客户端、SocialEcho CLI 或 n8n 节点等受支持的自动化连接器。TikTok Shop 的查询类接口同时接受相同参数的查询字符串形式。

## 响应格式、成功条件与错误处理

统一响应信封：`code`、`message`、`data`、`request_id`；失败时附加 `error` 对象（`type`、`reason`、`suggestion`）；分页响应附加 `meta`。

只有同时满足以下条件才视为成功：

- HTTP 状态码为 `2xx`。
- 响应 JSON 的业务 `code` 为 `0`。

失败使用 HTTP 4xx/5xx，业务码等于 HTTP 状态码 × 100：

- `400` / `40000`：请求错误。检查必填字段、日期、数组、MIME 类型和平台枚举值。
- `401` / `40100`：密钥缺失或无效。检查 Team API Key 和 Bearer 请求头格式。
- `403` / `40300`：无权限（例如无草稿权限）。
- `404` / `40400`：资源不存在或不属于当前团队。
- `405` / `40500`：请求方法错误。
- `409` / `40900`：状态冲突。
- `413` / `41300`：请求体过大。
- `419` / `41900`：认证超时。
- `422` / `42200`：参数校验或业务前置条件不满足。
- `429` / `42900`：触发限流或同步冷却（商品同步的响应含 `data.next_allowed_at` 或 `Retry-After`）。
- `500` / `50000`：服务端错误。
- `502` / `50200`：上游平台调用失败。
- `503`/`504` / `50300`/`50400`：服务不可用或网关超时。

重试策略：只对 `429`、`502`、`503`、`504` 与超时做自动重试（按 1、2、4 秒指数退避）；其余错误应先修正请求或权限再试。

已知注意事项：

- 上传接口传入不支持的 MIME 类型时，当前会返回 HTTP `500` / `50000`。
- 发布接口在提交阶段返回 `422`/`500` 时，不保证未创建发布记录——重试前先通过 `GET /v1/article` 核对，避免重复发布。

## 可用接口（共 12 个）

### GET /v1/team

返回当前认证团队信息（id、code、title、时区）。配置密钥后应首先调用此接口。

- 请求体：`{}`（可选）

```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' \
  --data-raw '{"page":1,"type":1}'
```

### GET /v1/oauth/links

获取各平台的 OAuth 授权链接，用于引导用户连接新账号。无业务参数。

- 返回：`data[].id`、`data[].title`、`data[].connections[].type`、`data[].connections[].url`。
- 平台 ID：Instagram 1、Facebook 2、TikTok 3、LinkedIn 4、YouTube 5、Telegram 6、X 7、Pinterest 8、Threads 10、TikTokShop 11。
- 连接类型示例：TikTokShop 为 `seller`/`creator`；Instagram 为 `instagram`/`facebook`。

### 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' \
  --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' \
  --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

返回 OSS 预签名上传信息。流程：获取上传地址 → 用 `PUT` 上传文件 → 发布时把返回的 `public_url`（而非有时效的 `upload_url`）写入 `attachments`。

- `content_type`：必填 MIME 类型。
- `title`：可选字符串，最长 255 字符。
- 图片类型：`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' \
  --data-raw '{"content_type":"image/png"}'
```

### GET /v1/pinterest/boards

发布 Pinterest 内容前，列出已连接账号可用的画板。

- `account_id`：必填整数，SocialEcho 账号 ID。

### GET /v1/tiktokshop/products

列出已同步的 TikTok Shop 商品。`status = 1` 表示可用于发布挂车。

- `account_id`：必填整数。
- `page`：可选整数。
- `per_page`：可选整数，1–100，默认 20。
- `keyword`：可选字符串，最长 500 字符。

### POST /v1/tiktokshop/products/sync

将商品刷新任务加入异步队列。「已排队」不等于「已完成」，请稍后通过商品列表确认。

- `account_id`：必填整数。
- 冷却：每个账号约 60 分钟；冷却期内返回 `429`，响应含 `data.next_allowed_at` 或 `Retry-After`。

### GET /v1/tiktokshop/music/genres

列出商业音乐曲库的风格枚举（如 `ALL`、`POP`、`BGM`）。无业务参数。

### GET /v1/tiktokshop/music/trending

获取商业曲库的热门音乐，返回 `uuid`、`title`、`artist`、`url`、`cover`、`duration`。

- `account_id`：必填整数。
- `country_code`：可选字符串。
- `genre`：可选字符串（取自音乐风格枚举）。
- `date_range`：可选字符串，`1DAY` / `7DAY` / `30DAY` / `90DAY`。

### POST /v1/publish/article

创建草稿、立即发布或定时发布跨平台内容。发布本身是异步的，成功仅代表创建了发布记录（返回 `data.id`）。

- `account_id`：必填整数，目标账号 ID。
- `type`：必填字符串，平台专用发布类型。
- `status`：必填整数；`0` 表示草稿，`1` 表示发布。
- `scheduled_at`：可选定时时间；当 `status=1` 且省略该字段时立即发布。
- `comment`：必填字符串数组，可为空数组。
- `content`：可选贴文正文（TikTok Shop 必填）。
- `extra`：必填对象，包含标题、画板或社区 ID、链接、TikTok 草稿标识、 等平台专用字段。
- `attachments`：必填对象数组；每项使用已上传文件的 `public_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`。
- TikTok Shop：`video`。
- Pinterest：`post`。

TikTok Shop 带货视频发布专项规则：

- `content` 必填，长度不超过 2200 个 UTF-16 代码单元。
- `extra.title` 必填，不超过 30 字符，仅限字母、数字与空格。
- `extra.product` 必填，须从商品列表接口返回值中原样复制（`id`、`uuid`、`title`、`thumb`）。
- `extra.music` 可选；一旦使用必须包含全部九个字段：`url`、`uuid`、`cover`、`title`、`artist`、`duration`、`selection`、`music_volume`、`original_sound_volume`；`selection` 取值 `none` / `trending_clip` / `full_track`。
- 附件仅限 1 个视频，不超过 500 MB。

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

## 推荐集成流程

1. 通过 `GET /v1/team` 验证密钥和团队。
2. 通过 `GET /v1/account` 获取已授权账号并保存返回的 SocialEcho 账号 ID；需要连接新账号时用 `GET /v1/oauth/links` 生成授权链接。
3. 分页接口持续增加 `page`，直到 `meta` 中的 `total` 和 `per_page` 表明已到最后一页。
4. 发布媒体前调用 `GET /v1/upload/url`，`PUT` 上传文件并把 `public_url` 写入 `attachments`。
5. 发布 Pinterest 前，先获取画板；发布 TikTok Shop 带货视频前，先同步并查询商品（如需配乐再查询音乐风格与热门音乐）。
6. 将最终请求体发送到 `POST /v1/publish/article`。
7. 通过 `GET /v1/article` 与 `GET /v1/report` 完成从发布到分析的数据闭环。

## 当前 API 范围

当前公开 OpenAPI 共 12 个接口，覆盖团队、账号、OAuth 授权链接、贴文、报告、上传地址、Pinterest 画板、TikTok Shop 商品与商业音乐、内容发布。来源文档没有把评论、私信接口、Webhook 或官方 MCP 服务器列为已上线能力，因此不应假设这些接口可用。

平台专用 `extra` 字段和发布限制可能变化，请以官方文档为准：https://www.socialecho.cn/helpcenter/docs/socialecho-openapi-docs