API 概览

基础 URL https://api.sofia-post.com/api · OpenAPI 文档

Sofia API 让你的代码访问你的 Sofia 账号：你的 Workspace 中的商家、它们已连接的平台、媒体库、帖子和统计数据。这是基于 HTTPS 的 REST API；请求和响应都是 JSON。它可以让你：

• 发布：立即发布、定时发布或存为草稿，可同时发往一个或多个平台。
• 发布前校验：通过模拟告诉你每个平台是否会接受这条帖子，不会写入任何内容。
• 管理媒体：上传文件，或从 URL 导入到商家的媒体库中。
• 跟踪帖子：读取每个平台的状态、永久链接或失败原因。也可以通过已签名的 Webhook 通知你。
• 读取统计数据：Sofia 为每个已连接账号收集的最新数据。
• 连接平台：创建一个托管链接，让所有者连接尚缺的平台。

SDK 与集成

• `sofia` CLI：发布在 npm 上、名为 sofia-post 的 CLI，用来在终端中操控 Sofia。
• MCP 服务器：把 Sofia 接入你的 AI 智能体。
• Zapier：Sofia 集成使用你的个人密钥连接。它提供触发器「Post Published」和「Post Failed」、操作「Create Post」（发布、定时或保存草稿）以及搜索「Find Post」。它尚未提交到 Zapier 的公开目录。

身份验证

每次调用都在 Authorization 请求头中携带 Bearer 令牌。Sofia 每次调用都会重新读取与它关联的权限：被移出 Workspace 的人，或被撤销的授权，会让令牌从下一次请求起失效。

有两种身份验证方式：

API 密钥

如果你自动化的是自己的 Workspace，一个个人密钥就够了。在 Sofia 应用中，打开设置 › API，进入个人访问标签页，创建一个密钥。选择它的名称、有效期和权限。密钥只显示一次：请复制并保存在密钥保险库中，绝不要放进你的代码里。

在设置 › API › 个人访问中创建一个密钥。它以你的身份作用于你所有的 Workspace：你指定的商家决定 Workspace，你在其中的角色决定密钥能做什么。

把密钥放在 Authorization 请求头中，作为 Bearer 令牌发送：

curl https://api.sofia-post.com/api/v1/establishments \
  -H "Authorization: Bearer sofia_pk_live_…"

`GET /v1/me` 会告诉你密钥代表谁操作、它的 Workspace 和它的权限。

缺少所需权限（scope）的调用会返回 403 insufficient_scope。

OAuth2 令牌

如果是代表用户在其自己的 Workspace 上操作的 SaaS 产品，请注册一个 OAuth 客户端：每个人在自己选择的 Workspace 上授权你的应用。OAuth 访问令牌以 sofia_live_at_… 开头，有效期一小时，使用方式相同：

curl https://api.sofia-post.com/api/v1/establishments \
  -H "Authorization: Bearer sofia_live_at_…"

你要创建一个供其他 Sofia 账号连接的应用吗？它的 authorization code + PKCE 流程、client credentials 和 scope 在 OAuth2 中说明。

基础 URL

所有端点都位于同一个基础 URL 之下：

https://api.sofia-post.com/api/v1

速率限制

Sofia API 在三个时间窗口内统计请求：15 分钟、24 小时和 30 天。

请求头

每个响应都会告诉你剩余额度，采用 IETF 格式：

RateLimit: "15m";r=144;t=43, "24h";r=994;t=13543, "30d";r=9994;t=13543
RateLimit-Policy: "15m";q=150;w=900, "24h";q=1000;w=86400, "30d";q=10000;w=2592000

r 是剩余请求数，t 是窗口重置前的秒数，q 是配额，w 是窗口的秒数。

窗口用尽时

响应为 429 rate_limit_exceeded，带有 Retry-After 请求头，并在 details 中给出已用尽的窗口。请等待该时长后再重试。

高效使用 API

• 注册 Webhook，而不是循环轮询某条帖子。
• 使用最大为 100 的 limit 读取列表，以减少页数。
• 缓存不常变化的数据：平台、商家、已连接账号。

错误

每个错误都会返回一个 HTTP 状态码和同样的 JSON 信封。code 是你的代码读取的约定；message 是写给人看的，可能会变。

{
  "error": {
    "code": "invalid_request",
    "message": "The request is invalid",
    "details": [
      { "field": "targets[0].text", "code": "required", "message": "targets[0].text is required" }
    ],
    "docUrl": "https://www.sofia-post.com/developers/errors#invalid_request",
    "requestId": "2aab5943-6333-4caf-8478-25a85ebd4abf"
  }
}

• details 提供更多信息：被拒绝的字段、某个平台的原因、已用尽的限制窗口。
• docUrl 指向本页对该错误码的说明。
• requestId 标识这次请求：请把它提供给支持团队。

错误码

帖子被拒绝的原因

post_refused 会在 details[].code 中列出每个原因：

处理错误

• 请根据 code 来编写逻辑，不要依赖 message。
• 遇到 429，在 Retry-After 之后重试；遇到 5xx，使用指数退避重试。
• 不要原样重试 4xx：先修正请求。
• 每次失败都记录 requestId。

分页

列表（GET /v1/posts、GET /v1/media）按最新优先返回，一次一页。limit 设置每页大小，范围 1 到 100（默认 20）。

{
  "data": [ … ],
  "nextCursor": "WyIyMDI2LTEwLTI3VDE1OjExOjU5LjAxN1oiLCIx…"
}

把 nextCursor 作为 cursor 传入即可读取下一页。当没有 nextCursor 时，说明已经到末尾。

let cursor;
do {
  const url = new URL('https://api.sofia-post.com/api/v1/posts');
  url.searchParams.set('limit', '100');
  if (cursor) url.searchParams.set('cursor', cursor);
  const page = await globalThis.fetch(url, { headers: { Authorization: `Bearer ${key}` } }).then((r) => r.json());
  handle(page.data);
  cursor = page.nextCursor;
} while (cursor);

游标是不透明的：切勿自行构造或修改。Sofia 没有返回过的游标会返回 400 invalid_cursor。

幂等性

网络错误可能让你无法确定帖子是否已创建。请在 POST /v1/posts 和 POST /v1/media 中发送 Idempotency-Key 请求头，并用同一个密钥重试：Sofia 会返回第一次的响应，不会重复创建任何内容。

curl -X POST https://api.sofia-post.com/api/v1/posts \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d @post.json

• 每条新帖子使用一个新的随机密钥（UUID），同一条帖子的每次重试使用同一个密钥。
• 同一个密钥配上不同的请求体，会返回 422 idempotency_key_reused。
• 第一次请求仍在处理时，同一个密钥会返回 409 idempotency_in_progress：请稍后重试。

测试模式与模拟

模拟。在 POST /v1/posts 后加上 ?dry_run=true：Sofia 会执行真实发布的各项检查（每个平台的规则、已连接账号、媒体、日期和你的套餐），但不会保存或发送任何内容。响应的详情见发布页面。

测试模式。以测试模式创建的应用（令牌 sofia_test_at_…）可以读取你真实的 Workspace，但绝不会写入：它的帖子是模拟的，并按同样的规则判定，任何真实写入都会返回 403 live_mode_required。在设置 › API 中创建的密钥和客户端是正式模式；如需在不发布的前提下检查，请使用模拟。