1. 文档适用对象

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

2. 快速接入（3分钟）

1. 登录 https://app.socialecho.net 并创建团队。

2. 在「团队管理」中创建 Team API Key。

3. 按 Bearer 鉴权方式调用 API（Authorization: Bearer se_xxx）。

4. 先调用 /v1/team 验证鉴权与团队上下文，再调用其他业务接口。

5. 统一按“HTTP=200 且 JSON.code=200”判定成功。

3. 环境与鉴权

字段	说明
生产环境 Base URL	https://api.socialecho.net
测试环境 Base URL	https://api-dev.socialecho.net
鉴权方式	Bearer Token（Team API Key）
请求头	Authorization: Bearer se_your_team_api_key
可选请求头	X-Lang: zh_CN/en；X-Team-Id: 团队ID
频率限制	单个 API Key 最多 120 次请求/分钟

推荐成功判定口径：

1. HTTP 状态码 = 200

2. 响应 JSON 中 code = 200

3. 其他情况均按失败处理并走重试/告警

4. 通用错误处理策略

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

5. 接口清单

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

获取当前 API Key 可访问的团队信息。建议先调用该接口，确认团队上下文后再拉取业务数据。

请求参数

参数名	位置	必填	类型	说明
X-Lang	header	否	string（枚举：zh_CN, en）	返回语言。`zh_CN` 或 `en`。默认 `zh_CN`
X-Team-Id	header	否	integer	目标团队 ID。多团队账号建议显式传入，避免上下文歧义

请求示例（cURL）

curl --request GET 'https://api.socialecho.net/v1/team' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'X-Lang: zh_CN' \
  --header 'X-Team-Id: 1024'

响应示例

示例：ok

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

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

获取社媒账号列表。用于后续贴文查询、报表聚合等接口的 account_id 选择。

请求参数

参数名	位置	必填	类型	说明
X-Lang	header	否	string（枚举：zh_CN, en）	返回语言。`zh_CN` 或 `en`。默认 `zh_CN`
X-Team-Id	header	否	integer	目标团队 ID。多团队账号建议显式传入，避免上下文歧义
page	query	否	integer	页码，从 1 开始
type	query	否	integer（枚举：1, 2）	账号类型。1=自有账号，2=竞品账号

请求示例（cURL）

curl --request GET 'https://api.socialecho.net/v1/account?page=1&type=1' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'X-Lang: zh_CN' \
  --header 'X-Team-Id: 1024'

响应示例

示例：ok

{
  "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"
      },
      {
        "id": 163956,
        "title": "TestEnv-TestPag2",
        "app": "Facebook",
        "type": 1,
        "status": "normal",
        "account": "TestEnv-TestPag2",
        "authorization_at": "2026-03-30 09:35:10"
      }
    ]
  }
}

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

按账号范围分页获取贴文列表。可用于构建“最近发布内容”或“内容稽核”工作流。

请求参数

参数名	位置	必填	类型	说明
X-Lang	header	否	string（枚举：zh_CN, en）	返回语言。`zh_CN` 或 `en`。默认 `zh_CN`
X-Team-Id	header	否	integer	目标团队 ID。多团队账号建议显式传入，避免上下文歧义
page	query	否	integer	页码，从 1 开始
account_ids	query	否	string	账号 ID 列表（CSV 格式，逗号分隔）

请求示例（cURL）

curl --request GET 'https://api.socialecho.net/v1/article?page=1&account_ids=163956,163955,28' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'X-Lang: zh_CN' \
  --header 'X-Team-Id: 1024'

响应示例

示例：ok

{
  "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
        }
      }
    ]
  }
}

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

按时间范围获取数据报表，可按 day / app / account 维度聚合，适合用于看板和日报机器人。

请求参数

参数名	位置	必填	类型	说明
X-Lang	header	否	string（枚举：zh_CN, en）	返回语言。`zh_CN` 或 `en`。默认 `zh_CN`
X-Team-Id	header	否	integer	目标团队 ID。多团队账号建议显式传入，避免上下文歧义
start_date	query	是	string	开始日期，格式 `YYYY-MM-DD`
end_date	query	是	string	结束日期，格式 `YYYY-MM-DD`
account_ids	query	否	string	账号 ID 列表（CSV 格式，逗号分隔）
time_type	query	否	integer（枚举：1, 2）	时间口径。1=新增贴文，2=历史全量贴文
group	query	否	string（枚举：, day, app, account）	聚合维度（空=总量，day/app/account=分组）

请求示例（cURL）

curl --request GET 'https://api.socialecho.net/v1/report?start_date=2026-01-01&end_date=2026-03-24&account_ids=163956,163955,28&time_type=1&group=day' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'X-Lang: zh_CN' \
  --header 'X-Team-Id: 1024'

响应示例

示例：total

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

示例：grouped_by_day

{
  "code": 200,
  "message": "success",
  "data": {
    "scope": {
      "start_date": "2026-01-01",
      "end_date": "2026-01-03",
      "time_type": 1,
      "group": "day"
    },
    "rows": [
      {
        "key": "2026-01-01",
        "exposure": 1200,
        "like": 50,
        "comment": 20,
        "share": 8
      },
      {
        "key": "2026-01-02",
        "exposure": 1100,
        "like": 45,
        "comment": 18,
        "share": 7
      }
    ]
  }
}

6. 对接建议

1. 先获取账号列表，再将 account_id 传给贴文与报表接口，避免传空范围。

2. 涉及分页接口时，统一循环 page 并在 total/per_page 达到末页后停止。

3. 在工作流平台（n8n、Zapier、Dify）中，将失败分支区分为鉴权失败与限流失败。

4. 建议记录请求时间、团队ID、接口名、HTTP状态码、业务code，便于线上排障。

7. 常见问题（FAQ）

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

Q2：account_ids 传什么格式？
A：推荐 CSV（如 163956,163955,28），便于多种工作流工具拼接。

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

Q4：是否必须传 X-Team-Id？
A：非必须；多团队上下文场景建议传，避免歧义。