salla-addon-purchase

Salla 插件计费周期

插件是可购买的额外项目，由 Salla 在应用套餐的基础上计费。此技能负责其计费生命周期——定义 → 激活 → 续订 → 取消／过期 → 门控。商家在嵌入式应用内购买插件（购买体验 → salla-addon-purchase-embedded）；随后 Salla 通过 Webhook 驱动每次状态变更。激活由 Webhook 驱动：只有收到经过签名验证的 app.subscription.started 后，才解锁功能。

工具和 MCP

使用 Salla Partners MCP：在发布内容的 pricing 部分定义插件（app_publish action=set section=pricing、addons[]），然后通过 salla_apps action=connect 设置 webhook_url。下方的 app.subscription.* 事件属于应用事件——应用默认已订阅这些事件，因此它们会自动发送到该 webhook_url。无需调用订阅接口（salla_events action=subscribe 仅适用于店铺事件）。

计费由 Salla 负责——你无需收费。流程交接：购买体验（iframe）→ salla-addon-purchase-embedded · 定价／权益基本机制和门控 → salla-app-billing · Webhook 签名验证／幂等性 → salla-webhooks · 为这些事件触发的任何 API 调用获取 OAuth 作用域并存储商家令牌 → salla-app-auth。

---

第 1 步 — 定义插件

插件位于发布载荷的 addons[] 数组中——没有单独的定价端点。每个插件都有一个 item_slug，你需要在每个生命周期事件中用它进行匹配。完整载荷结构 → salla-app-billing 第 1 步。

门控条件：“发布载荷中已包含插件并完成发布，而且你知道它的 item_slug 吗？”

---

第 2 步 — 设置 Webhook URL（插件事件会自动发送）

插件生命周期依赖 app.subscription.* 应用事件——应用默认已订阅这些事件，因此只需设置 webhook_url（salla_apps action=connect），事件就会自动发送。无需调用订阅接口；你需要处理下方的事件。编码前，请通过 App Events 文档（https://docs.salla.dev/421413m0.md）确认准确的载荷结构。

事件	触发时机	操作
app.subscription.started	购买插件／首次激活	激活权益（第 3 步）
app.subscription.renewed	续订周期性插件	延长 end_date
app.subscription.expired	周期结束且未续订	撤销权益，重新门控功能
app.subscription.canceled	商家取消	标记为已取消；在 end_date 前继续提供访问权限

门控条件：“已设置 webhook_url（插件的 app.subscription.* 事件会自动发送到该 URL——无需调用订阅接口），并且已为上述每个事件接入处理程序吗？”

---

第 3 步 — 在 app.subscription.started 时激活（事实来源）

此 Webhook 是激活触发器。下方的字段名称（item_type、item_slug、subscription_id、end_date、features）仅作示例——在使用这些字段前，请通过 salla_events action=list 或 App Events 文档确认准确的载荷结构：

// Runs only AFTER the request is signature-verified and de-duplicated — see salla-webhooks.
if (
  payload.event === "app.subscription.started" &&
  payload.data.item_type === "addon"
) {
  const { item_slug, subscription_id, end_date, features } = payload.data;
  await entitlements.activateAddon(payload.merchant, {
    addonSlug: item_slug,
    subscriptionId: subscription_id,
    endDate: end_date,
    features: features ?? [],
  });
}

• 通过 item_slug 匹配插件（套餐的 item_slug: null；插件则有 slug）。
• 验证签名、快速响应 200、去重 → salla-webhooks。在此处进行的任何商家令牌 API 调用 → salla-app-auth。

门控条件：“激活是否由 started 和 item_type === "addon" 触发，并通过 item_slug 匹配、完成签名验证且具有幂等性？”

---

步骤 4 — 续订、取消、到期

让存储的权益与 Salla 保持同步——每个事件都是事实来源：

• renewed → 延长 end_date（周期性附加项；区分周期性和一次性）。
• canceled → 标记为已取消，并保留访问权限，直到 end_date。
• expired → 撤销权益，并重新限制附加项的功能。

external_recurring 附加项（support_renew: true）需要通过 YOUR 调用续订，不会自动续订： POST /apps/subscriptions/{subscription_id}/renew（offline_access；处理 not_renewable / auto_renew_disabled / payment_failed 403、rate_limit_exceeded 429）。由 Salla 管理的周期性 附加项会自动续订，你只会收到 renewed。完整的 OpenAPI 架构和错误约定 （事实来源）：https://docs.salla.dev/37396517e0.md · 端点详情 → salla-app-billing。

持久化模式、周期性与一次性附加项，以及如何将附加项叠加到套餐上 → salla-app-billing。

检查：“每个生命周期事件都会更新存储的权益；到期时会撤销访问权限吗？”

---

步骤 5 — 根据附加项权益限制功能

根据已持久化的权益（事实来源）限制仅限附加项使用的功能。限制模式 → salla-app-billing。在嵌入式 UI 中反映激活状态 → salla-addon-purchase-embedded。

检查：“附加项功能是否根据存储的权益进行限制，并在每个事件后重新检查？”

---

生命周期一览

define addon (publish addons[])  →  merchant buys in the embedded app
        (salla-addon-purchase-embedded)
                                   │  Salla bills + confirms payment
                                   ▼  (source of truth — webhooks)
app.subscription.started (addon)  → activate entitlement
        │
        ├─ app.subscription.renewed  → extend end_date
        ├─ app.subscription.canceled → keep until end_date
        └─ app.subscription.expired  → revoke + re-gate

---

关键资源

资源	URL / 技能
购买附加项（嵌入式 UX）	salla-addon-purchase-embedded 技能
附加项定义 / 定价	salla-app-billing 技能
权益跟踪与限制	salla-app-billing 技能
Webhook 签名 / 幂等性	salla-webhooks 技能
应用事件	https://docs.salla.dev/421413m0.md
合作伙伴门户	https://salla.partners
开发者社区（Telegram）	https://t.me/salladev