Social

Social の全エンドポイント：ブランド、ホスト型の接続リンク、単一および一括での公開、予約、インサイト、そしてこれらすべてに適用される接続数の上限です。

Social API は Facebook、Instagram、X、LinkedIn、Pinterest に投稿を公開します。モデル全体は 2 つのオブジェクトで構成されます。ブランドは投稿の発信元であり、名前、タイムゾーン、および関連付けられたソーシャルアカウントで構成されます。接続は、1 つのブランドに属する、1 つのプラットフォーム上の認可済みソーシャルアカウントです。API プランではブランド数に制限はなく、費用もかかりません。プランで使用量として計測されるのは接続数なので、接続数の上限を考慮して設計する必要があります。

アカウントの接続は、お使いのサーバーからは実行できません。エンドユーザーがプラットフォーム上で認可する必要があるため、ホスト型のリンクをリクエストし、ユーザーをそのリンクにリダイレクトします。公開処理は非同期です。作成呼び出しは、投稿が受け付けられるとすぐに応答を返すため、チャネルごとの結果をポーリングします。

エンドポイント一覧

各所で使用する値

プラットフォームの値には、大文字の列挙名を使用します。"instagram" を送信すると拒否されます。TWITTER は X を表し、製品名が変わった際も列挙名は変更されませんでした。

ブランドを作成する

POST /social/brands

profileName と timezone は必須です。タイムゾーンはオブジェクトであり、重要なフィールドは tzCode です。これは、このブランドの投稿に含まれるすべての scheduleDate と scheduleTime の解釈に使用する IANA 識別子です。残りの 3 つのキーは表示用のラベルです。

curl -X POST https://listingsapi.com/api/v4/social/brands \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "profileName": "Jenny Home",      "timezone": {        "label": "(GMT-05:00) Eastern Time",        "tzCode": "America/New_York",        "name": "Eastern Standard Time",        "utc": "-05:00"      },      "categories": ["Furniture Store"],      "siteUrl": "https://jennyhome.example"    }  }'

返されたブランドの id を保存してください。これは、他のすべてのブランド用エンドポイントではパス内の brandId トークンとして、公開時にはリクエストボディの socialProfileId フィールドとして使用します。

ブランドの一覧表示と取得

GET /social/brands はブランドを 1 ページ分返します。GET /social/brands/{brandId} は 1 つのブランドをすべての詳細情報とともに返します。

curl -H "Authorization: API $LISTINGSAPI_KEY" \  "https://listingsapi.com/api/v4/social/brands?page=1&size=25"

指定した id に対して SY95043 が返される場合、そのブランドはこのアカウントに属していないか、すでにアーカイブされています。

ブランドを更新する

POST /social/brands/update

ブランドのIDはパスではなく、リクエストボディにinput.profileIdとして指定します。変更するフィールドのみを送信してください。省略したフィールドは現在の値を保持します。

curl -X POST https://listingsapi.com/api/v4/social/brands/update \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"profileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902", "bio": "Handmade furniture for real homes."}}'

ブランドをアーカイブする

POST /social/brands/archive

ブランドをアーカイブするには、作成から90日が経過している必要があります。90日未満の場合、呼び出しはSY95051で拒否され、何も変更されません。作成から90日が経過していれば、アーカイブは即座に適用され、そのブランドのすべての接続も同時にアーカイブされます。

それらの接続からの公開は即座に停止しますが、手動で接続を解除した場合と同様に、スロットは請求期間の終了まで使用数にカウントされます。アーカイブは、すぐに空き容量を増やす手段にはなりません。

curl -X POST https://listingsapi.com/api/v4/social/brands/archive \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902"}}'

接続用リンクを取得する

POST /social/brands/{brandId}/connections/link

接続を追加する方法はこれだけです。レスポンスには、expiresIn秒間有効な、ホストされたurlが含まれます。エンドユーザーをそのリンクにリダイレクトすると、ユーザーはプラットフォームで認可を行い、結果がクエリ文字列に含まれた状態でredirectUrlに戻ります。キャンセルと成功を区別するにはerrorUrlを渡し、この往復を通じて独自の相関値を引き継ぐにはstateを渡します。

このリクエストボディはフラットな構造で、inputラッパーがないことに注意してください。

curl -X POST https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/connections/link \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "channel": "INSTAGRAM",    "redirectUrl": "https://app.example.com/social/connected",    "errorUrl": "https://app.example.com/social/failed"  }'

{  "data": {    "connectSocialAccount": {      "status": "success",      "url": "https://social.listingsapi.com/connect/start?token=bfac8e06-8d72-4810-9c50-ae7ee12a7b52",      "expiresIn": 900    }  }}

リダイレクトする前にstatusを確認してください。failedレスポンスはurlを返さず、理由をtitleに格納します。最も多い理由は、接続数の上限（SY95042）またはそのアカウントで利用できないプラットフォーム（SY95044）です。

ブランドの接続を一覧表示する

GET /social/brands/{brandId}/connections

ブランドに紐づくアカウントを返します。各アカウントには、特定の接続への公開や接続の解除に必要なidが含まれます。

curl -H "Authorization: API $LISTINGSAPI_KEY" \  https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/connections

接続を解除する

POST /social/connections/disconnect

上記の一覧にある接続のidを指定します。アカウントからの公開は即座に停止しますが、そのアカウントが使用していたスロットは、請求期間が終了するまで利用可能なスロットに戻りません。その期間内に同じアカウントを同じブランドに再接続すると、そのスロットが再利用され、費用はかかりません。一方、別のブランドに紐づけると、2つ目のスロットを使用します。

curl -X POST https://listingsapi.com/api/v4/social/connections/disconnect \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"socialProfileConnectedChannelId": "b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7"}}'

投稿を公開する

POST /social/posts

1回の呼び出しで、platforms内のすべてのプラットフォームに同じコンテンツを公開します。それらの各プラットフォームには、ブランド上に既存の接続が必要です。そうでない場合、呼び出しはSY95045を返します。InstagramとPinterestでは、mediaUrlsに少なくとも1つのエントリが必要です。

投稿の予約には2つの方法のいずれかを使用し、両方を同時に使用しないでください。scheduledAtはオフセット付きのISO-8601タイムスタンプです。scheduleDateとscheduleTimeは一緒に送信し、ブランドのタイムゾーンで解釈されます。両方の方法を同時に指定した場合、または過去の日時を予約日時に指定した場合は、SY95046が返されます。

curl -X POST https://listingsapi.com/api/v4/social/posts \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",      "name": "Autumn collection launch",      "platforms": ["INSTAGRAM", "FACEBOOK"],      "content": "Our autumn collection lands today.",      "mediaUrls": ["https://cdn.example.com/social/autumn-collection.jpg"],      "action": "SCHEDULE",      "scheduleDate": "2026-10-02",      "scheduleTime": "09:30",      "clientReference": "campaign-4471-slot-01"    }  }'

clientReferenceに独自の識別子を設定してください。この識別子は保存されて返されるため、UUIDを保持しなくても、自社の記録と投稿を照合できます。

1件の投稿を取得する

GET /social/posts/{postId}

この方法で、公開が成功したかどうかを確認できます。投稿自体のstatusは概要であり、実際の結果はconnectedChannels内にチャネルごとに記録されます。各エントリには、独自のstatus、プラットフォームに受け付けられた場合はliveLink、受け付けられなかった場合はreasonまたはerrorが含まれます。

{  "connectedChannels": [    {      "platform": "INSTAGRAM",      "status": "SUCCESS",      "liveLink": "https://www.instagram.com/p/CxYz1234abc/",      "error": null    }  ]}

PUBLISHの後に、このエンドポイントをポーリングしてください。他のチャネルが成功しても1つのチャネルが失敗することがあるため、最上位のstatusだけでなく、すべてのエントリを確認してください。

ブランドの投稿を一覧表示する

GET /social/brands/{brandId}/posts

ブランドの投稿をページ単位で取得し、状態で絞り込むためのフィルターを使用できます。IDを1つずつポーリングする代わりに、一括で照合するために使用します。

curl -H "Authorization: API $LISTINGSAPI_KEY" \  "https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/posts?page=1&size=25"

予約投稿をキャンセルする

POST /social/posts/cancel

まだ公開されていない投稿をキャンセルします。プラットフォームですでに公開されている投稿は、このエンドポイントでは取り消せません。

curl -X POST https://listingsapi.com/api/v4/social/posts/cancel \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"socialPostId": "a3f81c62-9d4e-4a17-b5c0-2e7f6d8a9b10"}}'

インサイトとコメントを取得する

GET /social/posts/{postId}/insights

1つのチャネル上の1つの投稿について、エンゲージメント数とコメントを取得します。3つのプラットフォームに公開された投稿には、それぞれ別の数値があるため、チャネルの指定は必須です。

curl -H "Authorization: API $LISTINGSAPI_KEY" \  "https://listingsapi.com/api/v4/social/posts/a3f81c62-9d4e-4a17-b5c0-2e7f6d8a9b10/insights?socialConnectedChannelId=b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7"

投稿を一括作成する

POST /social/bulk-posts

input.postsで1〜500行を受け付けます。各行は、POST /social/postsがinputとして受け付けるものと同じオブジェクトであり、同じリクエスト内でも行ごとに異なるブランドを対象にできます。

何かを作成する前に、バッチ全体が検証されます。いずれかの行が検証に失敗すると、行ごとのエラーとともにSY95050が返され、何もキューに追加されないため、修正して再送信してください。500行を超える場合はSY95048が返され、この場合も何も作成されません。有効なバッチの場合は、ポーリングするためのジョブが返されます。

curl -X POST https://listingsapi.com/api/v4/social/bulk-posts \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "name": "October launch batch",      "posts": [        {          "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",          "name": "Launch day",          "platforms": ["FACEBOOK"],          "content": "Doors open at nine.",          "action": "SCHEDULE",          "scheduleDate": "2026-10-02",          "scheduleTime": "09:00"        }      ]    }  }'

一括処理はレート制限上で1リクエストとしてカウントされるため、大規模なバッチを効率的に処理できます。

一括処理ジョブをポーリングする

GET /social/bulk-posts/{bulkJobId}

各行に対して作成された投稿のIDや、キューへの追加後に失敗した行を含む、行ごとの結果とジョブのステータスを返します。ジョブは無期限には保持されず、保持期間を過ぎたIDを指定するとSY95047が返されます。

curl -H "Authorization: API $LISTINGSAPI_KEY" \  https://listingsapi.com/api/v4/social/bulk-posts/f47ac10b-58cc-4372-a567-0e02b2c3d479

上限と使用量を確認する

GET /social/limits

SY95042が返された後ではなく、接続を作成する前にこの情報を確認してください。usage.connectionsをmaxConnectionsと比較してください。これは課金対象の数で、現在接続されている数と、この期間中にすでに解放された数の合計です。usage.connectionsActiveは現時点で有効な数で、usage.connectionsReleasedは更新時に回復する容量です。

brandsはnullとして返され、無制限を意味します。APIプランでは、ブランド数は従量課金の対象ではありません。

curl -H "Authorization: API $LISTINGSAPI_KEY" \  https://listingsapi.com/api/v4/social/limits

発生するエラー

完全な一覧はエラーコードリファレンスにあります。

次の手順

接続数の上限、5接続単位のパック、90日間のアーカイブ制限の関係についてはプランとアドオンを、ポーリングの代わりにsocial_post.*とsocial_connection.*のイベントを受信する方法についてはWebhookでイベントに対応を参照してください。

Python SDKでは、これらのエンドポイントをclient.social.brands、client.social.connections、client.social.posts、client.social.bulkとして利用できます。詳細はSocialリソースを参照してください。Node SDKはまだSocialに対応していないため、NodeからRESTエンドポイントを直接呼び出してください。