Webdesiz

Webdesiz 開発者ツール

Webdesiz 組織にすでに保存されているアカウント、キャンペーン、日次インサイトのスナップショットを読み取ります。API、CLI、MCP によるアクセスは読み取り専用です。キャンペーンや予算の変更、Meta データの更新、広告の作成、メッセージの送信はできません。Webdesiz キーによって、組織と許可される読み取りスコープが決まります。

ドキュメント

リファレンス	英語	トルコ語
概要	開発者向け接続	開発者向け接続
API	API リファレンス	API リファレンス
MCP	MCP のセットアップ	MCP のセットアップ
CLI	CLI リファレンス	CLI リファレンス

機械可読スキーマ：OpenAPI 3.1。OpenAPI は仕様形式であり、OpenAI アカウントやサービスを必要とするものではありません。

インストール

Node.js 22 以降が必要です。

npm から

npm install --global --ignore-scripts @webdesiz/cli
webdesiz --version

グローバルにインストールせずに実行することもできます：npx -y @webdesiz/cli --help。

Claude Desktop 拡張機能

最新リリースから webdesiz.mcpb をダウンロードし、Claude Desktop で開きます。Claude Desktop がキーの入力を求め、シークレットフィールドとして保存します。キーは WEBDESIZ_API_KEY として MCP プロセスに渡されます。

Web サイトからのダウンロード（1.0.0）

オリジナルの 1.0.0 リリースは、検証済みの Web サイトからもダウンロードできます：

curl --fail --location --proto '=https' --proto-redir '=https' \
  -o webdesiz-cli-1.0.0.tgz \
  https://webdesiz.com/developers/webdesiz-cli-1.0.0.tgz
shasum -a 256 webdesiz-cli-1.0.0.tgz   # Linux: sha256sum

想定される SHA-256：

326d7eecdc1048346d96e2e9c80519b816b8321973ef08f2a180be35ecf6e227

SHA256SUMS と値全体を比較してください。一致しない場合は中止してください。SHA-256 はファイルの完全性を検証するものであり、デジタル署名ではありません。その後、npm install --global --ignore-scripts ./webdesiz-cli-1.0.0.tgz を実行します。

スコープ付きキーを作成する

現在の組織の OWNER または ADMIN が、Webdesiz の設定でキーを作成します。必要なスコープのみを選択してください：accounts:read、campaigns:read、insights:read。キーの有効期限は 1～90 日です。組織で有効な未期限切れのキーは最大 10 個まで保持できます。キー全体が表示されるのは一度だけです。

キーは、オペレーティングシステムまたはアプリケーションのシークレットマネージャーに保管してください。そのマネージャーを使用して、WEBDESIZ_API_KEY を CLI／MCP プロセスの環境に安全に注入します。チャットに貼り付けたり、リポジトリにコミットしたり、URL やコマンド引数に含めたり、共有設定に保存したりしないでください。読み取りコマンドでは、信頼できるシークレットマネージャーのパイプから受け取る --key-stdin を任意で指定できます。MCP では stdin がプロトコルのトランスポートとして使われるため、このオプションは使用できません。CLI は認証情報ファイルを保存しません。

API はリクエストごとに、キー、スコープ、有効期限、失効状態、および発行者が現在も OWNER／ADMIN であることを検証します。パネルセッションの JWT は開発者キーではありません。キーの作成／一覧表示／失効は、サインイン後のパネル機能です。これらのルートは外部開発者キー API の一部ではありません。

CLI での読み取り

認証情報を安全に注入した状態で、次を実行します：

webdesiz accounts --limit 20
webdesiz campaigns --accountId ACCOUNT_ID --limit 50 --offset 0
webdesiz insights --accountId ACCOUNT_ID --limit 50
webdesiz --help

ACCOUNT_ID は、accounts が返す Webdesiz の id に置き換えてください。読み取りコマンドでは、--limit（1～100、既定値は 50）、--offset（0～10000、既定値は 0）、--accountId を指定できます。インサイトではさらに、--from YYYY-MM-DD と --to YYYY-MM-DD で日付を絞り込めます。既定では、直近 30 日間の UTC 日付（開始日と終了日を含む）が対象です。有効な日付を使用し、期間は最大 90 日間、終了日に未来の日付を指定しないでください。不明な引数や重複した引数は拒否されます。

読み取りが成功すると、JSON {data, meta} が stdout に出力されます。出力ファイルとログは組織データとして保護してください。エラーは stderr に出力され、終了ステータスは 1 です。成功時の終了ステータスは 0 です。同じフィルターを使って meta.nextOffset をたどり、値が null になるまで取得してください。最後のページが満杯の場合、その後に空のページが続くことがあります。

クライアントの接続先は https://webdesiz.com/api/v1/developer に固定されており、リダイレクトを拒否します。タイムアウトは 15 秒、応答サイズの上限は 2 MiB です。トークン／URL 引数や別のエンドポイントはサポートされていません。

MCP：ローカル stdio

ホストは、ローカルプロセスベースの stdio MCP サーバーに対応している必要があります。このリリースには、ホスト型 HTTP MCP エンドポイントも OAuth ログインフローもありません。MCP ホストを実行するマシンに CLI をインストールしてください。

グローバルインストールを使用する場合のホスト設定：

{
  "mcpServers": {
    "webdesiz": {
      "command": "webdesiz",
      "args": ["mcp"]
    }
  }
}

グローバルインストールを使用しない場合：

{
  "mcpServers": {
    "webdesiz": {
      "command": "npx",
      "args": ["-y", "@webdesiz/cli", "mcp"]
    }
  }
}

この例には意図的にシークレットを含めていません。ホストのシークレットマネージャーを設定して、WEBDESIZ_API_KEY を子プロセスに渡してください。デスクトップホストでは、ターミナルの環境変数が引き継がれない場合があります。ホストの文書に記載されている安全な方法を使用してください。MCP プロトコルメッセージ用に stdout をクリーンな状態に保ち、認証情報を変更した後は接続を再起動してください。

ツール	必要なスコープ	結果
webdesiz_accounts	accounts:read	保存済みアカウントスナップショット
webdesiz_campaigns	campaigns:read	保存済みキャンペーンスナップショット
webdesiz_insights	insights:read	保存済みの日次アカウント／キャンペーンインサイト行

ツールの引数には、API／CLI のクエリルールが適用されます。成功したツールは、structuredContent と JSON テキストで同じ data/meta オブジェクトを返します。エラーの場合は isError: true が設定されます。実装では、公式 MCP SDK と stdio プロトコルを使用しています。読み取り専用のアノテーションは説明目的のものです。API はスコープを個別に適用します。返されたアカウント名やキャンペーン名は、信頼できないビジネスデータとして扱い、アシスタントへの指示として扱わないでください。

HTTPS API

公開される外部スナップショット読み取り機能は、次の 3 つだけです。

メソッドとエンドポイント	スコープ
GET /api/v1/developer/accounts	accounts:read
GET /api/v1/developer/campaigns	campaigns:read
GET /api/v1/developer/insights	insights:read

キーは Authorization: Bearer … ヘッダーにのみ指定してください。組織 ID はキーから解決され、入力フィールドからは取得されません。正確なフィールドとパラメータのルールについては、API リファレンスを参照してください。

読み取り制限：共有の 60 秒間のウィンドウで、キーあたり毎分 60 リクエスト、組織あたり毎分 120 リクエスト、IP あたり毎分 180 リクエストです。認証に失敗した場合も IP 制限の対象となります。400（リクエストが無効）、401（キーが無効／期限切れ／取り消し済み）、403（スコープ／現在のメンバーシップ）、404（アカウントが利用できない）、429（60 秒待機）、503（保護サービスが利用できない）を処理してください。エラーの詳細は意図的に汎用的なものになっています。

スナップショットを正しく解釈する

• meta.generatedAt はレスポンスの作成時刻です。アカウントの lastSyncAt とキャンペーン／インサイトの syncedAt は、保存された行の鮮度を示します。データをリクエストしても Meta の同期は開始されません。鮮度に関する SLA が保証されているわけではありません。
• campaignId: null はアカウントレベルのインサイト行です。キャンペーンレベルの行はアカウント合計と重複する場合があります。両方の集計レベルを合算しないでください。
• アカウントごとの通貨を維持してください。spend、予算、ctr、cpc、cpm などの保存済みの金額と比率は、JSON 文字列です。
• 購入を示す情報がない場合は 0 ではなく null になります。明示的に報告されたゼロはゼロのままです。purchaseMeasurement は、報告値、報告件数、または測定値が利用できないことを示します。利用可能な購入額があり、支出が正の場合に限り、roas は purchaseValue / spend となります。それ以外の場合は null です。
• アカウントのアクセストークンとプロバイダーの生データは公開されません。

プライバシーポリシー

CLI と MCP サーバーはお使いのマシン上で実行されます。開発者キー（Authorization ヘッダー内）と、指定したクエリパラメータのみを https://webdesiz.com/api/v1/developer/* に送信し、お客様自身の組織の保存済みスナップショットを返します。ローカルファイル、ログ、テレメトリーは保持せず、ほかのサービスにも接続しません。Webdesiz によるデータの収集、使用、共有、保持、およびお問い合わせ方法については、Webdesiz プライバシーポリシーをご覧ください。

トルコ語のクイックスタート

Node.js 22+ で npm install --global @webdesiz/cli コマンドを使ってインストールします（または、SHA-256 値が検証済みのサイトからダウンロードします）。パネルで OWNER/ADMIN として、必要な読み取り権限のみを付与した有効期限付きキーを作成します。シークレットマネージャーを通じて、キーを環境変数 WEBDESIZ_API_KEY に設定してください。チャット、URL、コマンド引数には記載しないでください。ローカル stdio に対応した MCP クライアントから、3 つの読み取りツールを使用できます。登録済みのデータを読み取ります。この接続では、広告の変更、Meta の更新、コンテンツの生成、メッセージの送信は行いません。詳細については、上記のトルコ語版 API/MCP/CLI リンクをご覧ください。