帖文

發布帖文

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

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

發布帖文

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

授權

Authorizationstring必填

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

僅保存在此分頁中，且僅傳送到 api.sofia-post.com。取得 API 金鑰

查詢參數

dry_runstring

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

標頭

Idempotency-Keystring

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

請求本文

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

發布帖文

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"}'

{
  "status": "ready",
  "dryRun": true,
  "targets": [
    {
      "platform": "instagram",
      "handle": "bistrot_lumiere",
      "state": "ready"
    }
  ]
}

發布帖文

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

{
  "status": "ready",
  "dryRun": true,
  "targets": [
    {
      "platform": "instagram",
      "handle": "bistrot_lumiere",
      "state": "ready"
    }
  ]
}

一條帖文屬於一個商家，發往一個或多個平台，也就是它的目標。每個目標都有自己的文案、媒體、格式和狀態。

帖文類型：立即發布、排程或草稿

請求本文中有兩個欄位決定帖文何時發出，以及是否發出：

情形	請求本文	行為
立即發布	不帶 `scheduledAt`	帖文立即發出。
排程	`scheduledAt`：未來的 ISO 8601 日期時間	它會在 `scheduledAt` 發出。
草稿	`"status": "draft"`，不帶 `scheduledAt`	會被儲存，但不會發出。

帖文的請求本文

欄位	含義
`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`）

目標的媒體

targets[].media 的每一項，要麼按 id 指定媒體庫中的一個媒體，要麼是一個公開的 https url 加上它的 type（image 或 video）。Instagram 和 TikTok 要求有照片或影片。要向媒體庫新增媒體，參見匯入媒體。

複製帖文

沒有專門用於複製帖文的端點：先用 `GET /v1/posts/{id}` 讀取它，再把內容放進新的 POST /v1/posts 請求中重新傳送。

重新傳送之前，請移除 Sofia 自己填寫的欄位。至少包括：

帖文的 id 和 createdAt；
所讀取帖文的 status（它概括了傳送狀態）：設成你想要的值，或者省略；
每個目標中的：state、publishedAt、permalink 和 error。

保留 establishmentId，以及每個目標的 platform 和 accountId。讀取不會返回目標的文案和媒體：請重新提供。最後設定新的 scheduledAt（或省略它以立即發布，或傳送 "status": "draft"）。

你的第一條帖文

1. 檢查已連接的平台

帖文透過商家已連接的帳戶發出。請列出它們；如果缺少某個，請建立一個連接連結。參見已連接帳戶。

2. 新增媒體

Instagram 和 TikTok 要求有照片或影片。請從一個公開的 https URL 匯入一個；Sofia 會把它下載到媒體庫並返回它的 id。參見匯入媒體。

3. 用模擬檢查

加上 ?dry_run=true：Sofia 會按每個平台的真實規則和已連接帳戶進行判定，不會寫入任何內容。

curl -X POST 'https://api.sofia-post.com/api/v1/posts?dry_run=true' \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "establishmentId": "'$ESTABLISHMENT_ID'",
    "targets": [
      { "platform": "instagram", "text": "Tarte tatin du jour", "media": [{ "id": "'$MEDIA_ID'" }] },
      { "platform": "facebook", "text": "Tarte tatin du jour", "media": [{ "id": "'$MEDIA_ID'" }] }
    ]
  }'

{
  "status": "ready",
  "dryRun": true,
  "targets": [
    { "platform": "instagram", "accountId": "fecd0904-…", "handle": "sof_ia_officiel", "state": "ready" },
    { "platform": "facebook", "accountId": "a423b3a4-…", "handle": "Sofia post", "state": "ready" }
  ]
}

4. 發布

傳送同樣的請求本文，去掉 dry_run，並帶上 Idempotency-Key，這樣重試就不會重複發布。不帶 scheduledAt 時帖文立即發出；帶有未來的 scheduledAt 則會被排程。

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: $(uuidgen)" \
  -d @post.json

5. 跟蹤它

帖文先返回 publishing，之後每個平台變為 published 並帶有永久連結，或變為 failed 並帶有原因。用 `GET /v1/posts/{id}` 讀取它，或註冊一個 Webhook 來接收通知。

模擬（dry run）

POST /v1/posts?dry_run=true 會執行真實發布的各項檢查：每個平台的規則、已連接帳戶、媒體、日期和你的方案。它不會儲存任何內容，也不會傳送任何內容。

就緒

當每個平台都會接受這條帖文時，回應為 200，status: "ready"，並為每個目標給出將用於發布的帳戶。

被拒絕

否則，回應為 422 post_refused，每個原因對應一條詳情。每條詳情會指出它的平台、code，並說明需要修正什麼。

{
  "error": {
    "code": "post_refused",
    "message": "The post would not be published: x: the text is too long (300 characters, at most 280)",
    "details": [
      {
        "platform": "x",
        "code": "caption_too_long",
        "max": 280,
        "actual": 300,
        "message": "x: the text is too long (300 characters, at most 280)"
      }
    ],
    "docUrl": "https://www.sofia-post.com/developers/errors#post_refused"
  }
}

每個原因都列在錯誤中。

關於應用程式的測試模式，參見測試模式與模擬。Idempotency-Key 也保護 POST /v1/posts：參見冪等性。

授權

Authorizationstringheader必填
你的個人金鑰或 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

回應

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

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

這個頁面對你有幫助嗎？