帖文與排程

一則帖文屬於一家門市，發往一個或多個網絡，也就是它的目標（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。請參閱分頁。