SuperAPI AI 工具集

paddle-catalog-setup

编程与开发

查看项目

更新于 10-16 03:14

技能介绍

用途:当用户开始 Paddle 集成、账户中还没有其他 Paddle 技能(checkout-web、pricing-pages、sandbox-testing、webhooks)所依赖的产品和价格时,用本技能创建它们。通常每个项目只需一次;之后仅在新增产品或价格时再用。

建模前先与用户确认,不要猜测:产品是所售之物(如 Pro plan),价格是计费方式(如 $10/月);一个产品可有多个价格,通常每个计费周期一个,并可为不同市场设置价格覆盖。每个产品需选税务类别(saas、digital-goods、ebooks、standard、website-hosting、professional-services、training-services、implementation-services),默认 saas 或 standard,其他类别需在仪表盘获批。每个价格需选计费模型:循环订阅需计费周期(MCP 用 billing_cycle,SDK 用 billingCycle),一次性价格省略;试用期仅限订阅,一次性价格会被 API 拒绝。金额为最低货币单位的字符串:USD/EUR/GBP 用分("1000" = $10.00),JPY、KRW、CLP 为零小数货币用整数单位("1200" = ¥1,200)。开发默认 sandbox,sandbox 与 production 完全隔离,ID 形如 pro_01h... 与 pri_01h...,创建后需记录价格 ID 供应用使用。

方法优先级:一、Paddle MCP 服务器(paddle-sandbox 或 paddle-live),用 search 确认方法名与参数,再用 execute 执行一个 async 函数,在一次调用内链式创建产品与全部价格;方法路径为 camelCase,请求体与响应字段为 snake_case;每次 execute 上限 50 次 API 调用、30 秒超时、32KB 代码。二、Node SDK 种子脚本:需 PADDLE_API_KEY(至少 product.write 与 price.write 权限),安装 @paddle/paddle-node-sdk,编写脚本由用户运行一次,例如 npx tsx scripts/seed-paddle-catalog.ts,SDK 全程 camelCase。三、仪表盘手动:进入 Paddle > Catalog > Products 新建产品与价格,再复制 pri_... ID。若某方法中途失败(如权限不足),应降级到下一方法而非重试。

完成后验证:通过 MCP 的 client.products.list({ include: ["prices"] }) 或 SDK 的 paddle.products.list({ include: "prices" }) 确认存在,核对 ID、名称与税务类别,并建议下一步用新价格 ID 完成 checkout-web。

常见陷阱:环境混用、金额单位混淆、价格漏传产品 ID、一次性价格加试用期、循环价格漏计费周期、MCP 中 camelCase 与 snake_case 混用、把依赖调用拆到多次 execute、区域覆盖缺少合理基础价、缺少写权限、未告知用户就写入 ID。相关文档包括创建产品、设置本地化价格、Products/Prices API 参考及 Paddle MCP 安装指南。