帖子与定时发布

一条帖子属于一家门店，发往一个或多个网络，即它的目标（targets）。每个目标都有自己的文本、媒体、格式和状态。

端点

POST/v1/postsGET/v1/postsGET/v1/posts/{id}PATCH/v1/posts/{id}DELETE/v1/posts/{id}

帖子的请求体

字段	含义
`establishmentId`	负责发布的门店（`GET /v1/establishments`）
`targets[]`	每个网络一项：`platform`、`text`，以及可选的 `media`、`format` 和 `accountId`
`targets[].media[]`	媒体库中的媒体（按 `id`），或公开的 https `url` 加上它的 `type`（`image` 或 `video`）
`targets[].accountId`	门店在该网络有多个账号时要使用的账号
`scheduledAt`	未来的 ISO 8601 日期时间；不填则立即发布
`status`	`draft` 表示保存为不会发出的草稿（此时不要带 `scheduledAt`）

状态

状态	含义
`draft`	已保存，不会发出
`scheduled`	将在 `scheduledAt` 发出
`publishing`	正在发送到网络
`published`	已上线，带有 `permalink`
`failed`	被网络拒绝；原因见 `error`
`sent_to_inbox`	已发送到该网络的应用，由所有者在其中完成发布（TikTok）

帖子的 status 汇总了它各个目标的状态。当一个网络已发布而另一个失败时，为 partial。

发出前编辑

PATCH /v1/posts/{id} 可重写目标、修改 scheduledAt 或更改 status：draft 会去掉时间但保留内容，scheduled 会重新定时。一旦有网络已发送该帖子，就会返回 409 post_not_editable。

bash

curl -X PATCH https://api.sofia-post.com/api/v1/posts/$POST_ID \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"status":"scheduled","scheduledAt":"2026-11-20T09:00:00Z"}'

删除

DELETE /v1/posts/{id} 返回 204。当某个网络正在发送该帖子时，返回 409 post_in_flight：请稍后重试。

列出帖子

GET /v1/posts 按从新到旧的顺序列出令牌可访问的所有帖子，可按 establishmentId、status、from、to 和 createdBy（me 或 app）筛选。只要帖子至少有一个网络处于该状态，就匹配 status。参见分页。