帖子

发布帖子

正式应用可立即发布、定时发布或存为草稿，测试应用只做模拟。加上 ?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
  正式模式：其显示的用户名

这个页面对你有帮助吗？