API 参考
获取 API 密钥Sofia API v1 的所有端点及其参数、权限范围和示例，并提供可用你自己的密钥逐个试用的 Playground。
基础 URL https://api.sofia-post.com/api · OpenAPI 文档
OAuth
GET
/v1/oauth/authorize发起授权在用户的浏览器中打开。未知客户端或未注册的 redirect_uri 返回 400，否则跳转到 Sofia 授权页面。GET/.well-known/oauth-authorization-server/api/v1/oauth获取服务器元数据返回 Sofia API 的 OAuth 2.0 授权服务器元数据（RFC 8414），方便客户端发现端点和支持的选项。POST/v1/oauth/token签发访问令牌client_credentials、authorization_code、refresh_token 可换取 3600 秒有效的令牌。账号
平台
门店
GET
/v1/establishments列出门店列出令牌所操作 Workspace 的门店。发布、列出媒体或读取数据洞察时，用其标识符作为 establishmentId。GET/v1/establishments/{id}/accounts列出已连接账号列出门店已连接的网络，不含令牌或网络密钥，只提供为账号命名并在发布时选作 accountId 所需的全部信息。POST/v1/establishments/{id}/connection-links创建连接链接返回托管链接，用户在 Sofia 上授权网络，因此网络令牌不会到达你的应用。链接有效期 30 分钟，仅限正式应用使用。GET/v1/establishments/{id}/insights获取门店数据洞察返回 Sofia 为每个已连接账号收集的最新有效数据。尚未收集到数据的账号显示 awaiting，绝不会显示为零。媒体
GET
/v1/media列出媒体按从新到旧分页列出门店的媒体库，附当前时间窗口内有效的签名 URL。在测试模式和正式模式下都可以使用，用于挑选已有素材。POST/v1/media导入或上传媒体把文件（multipart）或 Sofia 抓取的 https URL 添加到门店媒体库。需要正式应用和有效订阅。GET/v1/media/{id}获取媒体返回媒体库中的一项媒体，附当前时间窗口内有效的签名 URL，其标识符可在发布帖子时直接复用，无需重新上传文件。DELETE/v1/media/{id}移除媒体像应用一样，把媒体从其所属门店的媒体库中移除。文件本身不会被销毁，已排期的帖子仍然保留它的视觉素材，不受影响。帖子
GET
/v1/posts列出帖子按从新到旧列出令牌可访问门店的帖子，可按门店、状态、日期范围和作者筛选，分页返回，并用游标取得下一页，每页最多 100 条。POST/v1/posts发布帖子正式应用可立即发布、定时发布或存为草稿，测试应用只做模拟。加上 ?dry_run=true 则只检查、不写入。GET/v1/posts/{id}获取帖子返回帖子及各网络的状态、发布后的链接和失败时的错误。正式模式可读 Workspace 内任何帖子，测试模式读模拟帖子。PATCH/v1/posts/{id}编辑帖子任何网络开始发送前，可替换 targets、设置 scheduledAt，或在 draft 与 scheduled 之间切换，其余字段不变。DELETE/v1/posts/{id}删除帖子像应用一样删除帖子：已排期的不再发送，已发布的会从各网络上移除。测试应用没有任何真实内容，因此没有东西可删除。Webhook
GET
/v1/webhooks列出 webhook列出应用的 webhook，不含签名密钥；该密钥只在注册 webhook 时返回一次，之后无法再次获取，请自行妥善保存。POST/v1/webhooks注册 webhook注册 Sofia 以带签名 JSON 事件调用的 https URL，失败最多重试五次。密钥仅显示一次，最多 10 个。DELETE/v1/webhooks/{id}删除 webhook删除 webhook。之后它不再收到任何内容，包括仍在等待重试的投递；调用成功后不返回响应体，删除后也无法恢复。POST/v1/webhooks/{id}/test发送测试事件像其他事件一样投递带签名的 webhook.test 事件，无需等待接收方，便于校验签名。每分钟最多发送五次。