菜单

SocialEcho OpenAPI 文档

1. 文档适用对象

本文档面向需要对接 SocialEcho 外部 API 的研发、测试、实施与自动化工程师。目标是让你在最短时间内完成可用对接。

2. 快速接入（3 分钟）

登录 https://app.socialecho.net 并创建团队。
在「团队管理」中创建 Team API Key。
使用 Bearer 鉴权调用 API（Authorization: Bearer se_xxx）。
先调用 GET /v1/team 验证鉴权与团队上下文，再调用其他业务接口。
成功判定见下文「环境与鉴权」中的推荐口径。

3. 环境与鉴权

字段	说明
Base URL	`https://api.socialecho.net`
鉴权方式	Bearer Token（Team API Key）
请求头	`Authorization: Bearer se_your_team_api_key`
可选请求头	`X-Lang: zh_CN` 或 `en`
频率限制	单个 API Key 最多 120 次请求/分钟

3.1 传输形态说明（与线上一版文档的差异）

当前导出的 OpenAPI 约定：多数接口为 GET，业务参数放在 Content-Type: application/json 的请求体中（而不是 QueryString）。
若你使用浏览器 fetch 发 GET + body，部分环境会限制；推荐使用 curl、服务端 HTTP 客户端或本仓库提供的 CLI / n8n 节点。

3.2 推荐成功判定口径

HTTP 状态码 = 200
响应 JSON 中 **code = 200 或 0**（以服务端实际返回为准；旧文档仅写 200，现已兼容 0）
其他情况均按失败处理并走重试/告警

4. 通用错误处理策略

情况	说明
400 Bad Request	参数缺失、参数格式错误（请优先检查日期格式与枚举字段）
401 Unauthorized	API Key 无效、过期或未正确放在 `Authorization` 头中
429 Too Many Requests	触发限流；建议增加节流与指数退避（1s/2s/4s）
超时/网络异常	建议重试 2～3 次，保留请求参数快照用于排查

5. 接口清单

以下示例 Base URL 均为 https://api.socialecho.net；将 se_your_team_api_key 替换为你的 Team API Key。

通用 curl 说明：对 GET 且带 JSON body 的接口，使用 --data-raw '<json>'（或 --data-binary）。请勿省略 Content-Type: application/json。

5.1 获取当前 API Key 可访问的团队信息（GET /v1/team）

建议先调用该接口，确认团队上下文后再拉取业务数据。

参数名	位置	必填	类型	说明
X-Lang	header	否	string	`zh_CN` 或 `en`，默认 `zh_CN`
（body）	body	否	object	空对象 `{}`

请求示例（cURL）

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 '{}'

响应示例

json 复制代码

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1024,
    "code": "TEAM_ABC123",
    "title": "SocialEcho QA Team",
    "timezone": "Asia/Shanghai"
  }
}

5.2 获取社媒账号列表（GET /v1/account）

参数名	位置	必填	类型	说明
X-Lang	header	否	string	返回语言
page	body	否	integer	页码；不传则可能返回全量（以服务端为准）
type	body	否	integer	`1` = 授权账号，`2` = 竞品账号

请求示例（cURL）

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

响应示例

json 复制代码

{
  "code": 200,
  "message": "success",
  "data": {
    "page": 1,
    "per_page": 10,
    "total": 2,
    "list": [
      {
        "id": 163751,
        "title": "esprit.vert.medic",
        "app": "Instagram",
        "type": 1,
        "status": "normal",
        "account": "@esprit.vert.medic",
        "authorization_at": "2026-03-30 09:34:44"
      }
    ]
  }
}

5.3 获取贴文列表（GET /v1/article）

参数名	位置	必填	类型	说明
X-Lang	header	否	string	返回语言
page	body	否	integer	页码
account_ids	body	否	integer[]	账号 ID 数组

请求示例（cURL）

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

响应示例

json 复制代码

{
  "code": 200,
  "message": "success",
  "data": {
    "page": 1,
    "per_page": 10,
    "total": 1,
    "list": [
      {
        "id": 987654,
        "uuid": "tE-9LwdHfNk",
        "app": "YouTube",
        "account_id": 163751,
        "content": "Example article content",
        "created_at": "2026-03-24 10:05:01",
        "url": "https://www.youtube.com/watch?v=tE-9LwdHfNk",
        "reports": {
          "exposure": 1021,
          "like": 40,
          "comment": 14,
          "share": 0
        }
      }
    ]
  }
}

5.4 获取报表数据（GET /v1/report）

参数名	位置	必填	类型	说明
X-Lang	header	否	string	返回语言
start_date	body	是	string	`YYYY-MM-DD`
end_date	body	是	string	`YYYY-MM-DD`
time_type	body	是	integer	`1` = 日期内新增贴文，`2` = 历史全部贴文
account_ids	body	否	integer[]	账号 ID 数组
group	body	否	string	不传=总量；`day` / `app` / `account` 为分组维度

请求示例（cURL）

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

响应示例（汇总）

json 复制代码

{
  "code": 200,
  "message": "success",
  "data": {
    "scope": {
      "start_date": "2026-01-01",
      "end_date": "2026-03-24",
      "time_type": 1,
      "group": ""
    },
    "totals": {
      "exposure": 120345,
      "like": 4512,
      "comment": 893,
      "share": 326
    }
  }
}

5.5 获取 OSS 上传地址（GET /v1/upload/url）

用于获取文件上传到 OSS 所需的 URL（具体字段以服务端返回为准）。一般流程：先取上传 URL → 上传文件 → 将返回的文件 URL 用于发布接口的 attachments。

参数名	位置	必填	类型	说明
X-Lang	header	否	string	返回语言
content_type	body	是	string	待上传文件的 MIME 类型，须为下方枚举之一；需与实际上传文件类型一致

content_type 枚举：

图片：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

请求示例（cURL）

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

5.6 获取 Reddit 社区列表（GET /v1/reddit/communities）

发布 Reddit 内容前，可用于选择社区上下文。

参数名	位置	必填	类型	说明
X-Lang	header	否	string	返回语言
account_id	body	是	integer	社媒账号 ID

请求示例（cURL）

bash 复制代码

curl --request GET 'https://api.socialecho.net/v1/reddit/communities' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: zh_CN' \
  --data-raw '{"account_id":163751}'

5.7 获取 Pinterest 图版列表（GET /v1/pinterest/boards）

发布 Pinterest 内容前，可用于选择图版（board）。

参数名	位置	必填	类型	说明
X-Lang	header	否	string	返回语言
account_id	body	是	integer	社媒账号 ID

请求示例（cURL）

bash 复制代码

curl --request GET 'https://api.socialecho.net/v1/pinterest/boards' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: zh_CN' \
  --data-raw '{"account_id":163751}'

5.8 发布贴文（POST /v1/publish/article）

跨平台发布。type、extra、attachments 等字段与平台强相关，请以控制台与联调结果为准。下列为 OpenAPI 中的核心字段说明摘要。

参数名	位置	必填	类型	说明
X-Lang	header	否	string	返回语言
account_id	body	是	integer	发布所用社媒账号
type	body	是	string	发布类型（按平台取值，如 Facebook `post`、YouTube `video` 等）
status	body	是	integer	`0` = 草稿，`1` = 发布
scheduled_at	body	否	string	定时时间；`status=1` 时可填，不填则立即发布
comment	body	是	string[]	评论数组（可为空数组）
content	body	否	string	正文内容
extra	body	是	object	扩展字段：标题、图版/社区 ID、链接、TikTok 草稿、Reddit flair 等（各平台不同）
attachments	body	是	object[]	附件列表，每项需包含已上传文件 URL：`{ "url": "https://..." }`

**type 取值示例（摘自 OpenAPI 说明）**
Facebook：reels / post / stories；YouTube：shorts / video；Instagram：reels / post / stories；X：short_post / long_post；LinkedIn：post；TikTok：video / photo；Pinterest：post；Reddit：text / link / media。

请求示例（cURL，请使用实际 JSON 文件）

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

publish-payload.json 需按目标平台补齐 extra（例如 Pinterest 的 category_id、Reddit 的 flair 等）。仓库内技能包附带示例可参考 publish-payload.example.json。

6. 对接建议

先获取账号列表，再将 account_id 传给贴文、报表、Reddit、Pinterest 等接口，避免传空范围。
涉及分页接口时，统一循环 page 并在 total/per_page 达到末页后停止。
在工作流平台（n8n、Zapier、Dify）中，将失败分支区分为鉴权失败与限流失败。
建议记录请求时间、接口名、HTTP 状态码、业务 code 与关键请求参数，便于线上排障。
发布类接口建议先走 GET /v1/upload/url 完成素材上传，再组装 attachments。

7. 常见问题（FAQ）

Q1：返回 HTTP 200，但业务失败怎么办？
A：以 JSON 中 code 是否为 200 或 0 为准，不要只看 HTTP 状态码。

Q2：account_ids 在 JSON body 里怎么传？
A：使用 整数数组（例如 [163956,163955,28]）。若你在旧集成里使用 CSV 查询参数，请改为与 OpenAPI 一致的 body 形态。

Q3：如何避免触发 429？
A：控制单 key 不超过 120 req/min，并配置节流与指数退避。

本地文档生成说明：结构与帮助中心原文对齐，接口定义与 默认模块.openapi.json（v1.1.0）一致。若与线上一致性校验冲突，以服务端与最新导出 OpenAPI 为准。

上一个

API说明

最近修改: 2026-04-27Powered by

大纲