Webdesiz

Webdesiz 开发者工具

读取已存储在 Webdesiz 组织中的账户、广告系列和每日洞察快照。API、CLI 和 MCP 访问均为只读：无法更改广告系列或预算、刷新 Meta 数据、生成广告或发送消息。Webdesiz 密钥决定所属组织和允许读取的范围。

文档

参考资料	English	Türkçe
概览	开发者连接	开发者连接
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 进程。

网站下载（1.0.0）

原始 1.0.0 版本也可通过已验证的网站下载获取：

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 天，结束日期不能是未来日期。未知或重复的参数会被拒绝。

读取成功后，会向 stdout 输出 JSON {data, meta}。请将输出文件和日志视为组织数据并妥善保护。错误信息会输出到 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 传递给子进程。桌面宿主可能无法继承终端环境；请使用其文档说明的安全机制。请保持 stdout 干净，仅用于 MCP 协议消息；更改凭据后，请重新建立连接。

工具	所需权限范围	结果
webdesiz_accounts	accounts:read	已存储的账户快照
webdesiz_campaigns	campaigns:read	已存储的广告系列快照
webdesiz_insights	insights:read	已存储的每日账户／广告系列洞察数据行

工具参数遵循 API／CLI 查询规则。调用成功时，工具会将相同的 data/meta 对象作为 structuredContent 和 JSON 文本返回；出错时使用 isError: true。实现使用官方 MCP SDK 和 stdio 协议。只读注释仅供描述；API 会独立强制执行权限范围。请将返回的账户名称和广告系列名称视为不可信的业务数据，绝不可将其视为助手指令。

HTTPS API

仅开放三种外部快照读取操作：

方法和端点	权限范围
GET /api/v1/developer/accounts	accounts:read
GET /api/v1/developer/campaigns	campaigns:read
GET /api/v1/developer/insights	insights:read

仅在 Authorization: Bearer … 标头中发送密钥。组织身份根据密钥解析，不通过输入字段提供。确切字段和参数规则请参阅 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 字符串。
• 缺少购买证据时返回 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 客户端可以使用三个读取工具。可读取已记录的数据；此连接不支持更改广告、刷新 Meta、生成内容或发送消息。详情请参阅上方土耳其语 API/MCP/CLI 链接。