帖子发布帖子
返回 Sofia

帖子

发布帖子

正式应用可立即发布、定时发布或存为草稿，测试应用只做模拟。加上 ?dry_run=true 则只检查、不写入。

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

此请求将作用于你的真实账户。

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

其他任何错误，以错误结构返回。