投稿を公開する

投稿は 1 つの店舗に属し、1 つ以上のネットワーク（ターゲット）に公開されます。各ターゲットに、独自の文章、メディア、形式、状態があります。

投稿の種類：今すぐ、予約、下書き

ボディの 2 つのフィールドが、投稿をいつ、そして公開するかどうかを決めます。

投稿のボディ

ターゲットのメディア

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 を付けると、再試行しても 2 回公開されません。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 を登録して通知を受けてください。

ドライラン

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 も保護します。冪等性をご覧ください。