貼文

發布貼文

正式應用可立即發布、定時發布或存為草稿，測試應用只做模擬。加上 ?dry_run=true 則只檢查、不寫入。

POSThttps://api.sofia-post.com/api/v1/posts

POST/v1/posts

API 金鑰或存取權杖僅保存在此分頁中，且僅傳送到 api.sofia-post.com。dry_run (query)Idempotency-Key (header)請求本文

此請求將作用於你的真實帳號。

curl -X POST 'https://api.sofia-post.com/api/v1/posts' \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"establishmentId":"cmvy2k3m40001ms4rest00000","targets":[{"platform":"instagram","text":"Tarte tatin du jour","format":"post","accountId":"cmvy2k3m40001ms4rig000000"}],"scheduledAt":"2026-11-02T10:00:00.000Z"}'

授權

Authorizationstring必填
你的個人金鑰或 OAuth 存取權杖，以 Bearer <token> 傳送。

查詢參數

dry_runstring
true：執行傳送時會做的全部檢查（網路規則、帳號、媒體、建立、正式訂閱），不寫入任何內容。回傳 200 ready 或 422 post_refused。
允許的值： truefalse

標頭

Idempotency-Keystring
用相同請求本文重放時回傳相同回應，不會再建立一條貼文。試執行不會消耗該金鑰。

請求本文

application/json

establishmentIdstring必填
門市，須在權杖授權的 Workspace 內（GET /v1/establishments）
targetsobject[]必填
每個目標一個網路
顯示子屬性
- platformstring必填
  目標網路
  允許的值： instagramfacebookxlinkedintiktok
- textstring必填
  在此網路上發布的文案
- mediaobject[]
  附加的媒體
  顯示子屬性
  - idstring
    門市媒體庫中某個媒體的識別碼（否則用 url 和 type）
  - urlstring
    媒體的公開位址（正式模式下為 https）；不提供識別碼時使用
  - typestring
    按位址提供的媒體的類型
    允許的值： imagevideo
- formatstring
  格式（post、reel、story、carousel 等）；預設為該網路會採用的格式
- accountIdstring
  正式模式：負責發布的已連結帳號，在門市於該網路有多個帳號時使用（GET /v1/establishments/:id/accounts）
scheduledAtstring<date-time>
排程時間（ISO 8601），須為未來時間；省略則立即發布。不能與 status 為 draft 同時使用
statusstring
draft：草稿（僅限正式模式），建立時不帶日期，不傳送任何內容；用 PATCH /v1/posts/:id 排程
允許的值： draft

回應

200application/json

試執行：所有檢查均已通過。

statusstring必填
始終為 ready
允許的值： ready
dryRunboolean必填
始終為 true
允許的值： true
targetsobject[]必填
已檢查的目標
顯示子屬性
- platformstring必填
  目標所在的網路
- statestring必填
  始終為 ready
  允許的值： ready
- accountIdstring
  正式模式：將發布的帳號
- handlestring
  正式模式：其顯示的使用者名稱

201application/json

正式：publishing 或 scheduled。測試：simulated。

idstring必填
貼文的識別碼，可用 GET /v1/posts/:id 讀回
statusstring必填
建立時貼文的狀態
允許的值： draftpublishingscheduled
establishmentIdstring必填
貼文所屬的門市
targetsobject[]必填
貼文的目標
顯示子屬性
- platformstring必填
  目標所在的網路
- accountIdstring必填
  負責發布的帳號
- statestring必填
  建立時目標的狀態
  允許的值： draftpublishingscheduledfailed
scheduledAtstring<date-time>
貼文預計發布的時間

400

請求本文格式錯誤。

401

權杖缺失、未知、已過期或已被撤銷。

402

subscription_required（正式模式，試執行也包括在內）。

403

權杖沒有 posts:write scope。

404

establishment_not_found：不在權杖所屬 Workspace 內。

422application/json

post_refused：某個網路、門市或建立會拒絕；media_import_refused（正式模式）並附原因；idempotency_key_reused。

4XXapplication/json

其他任何錯誤，以錯誤結構回傳。