用途:为 Salla 应用设置商家付费方式,并维护每位商家套餐状态的可靠视图。计费由 Salla 负责,开发者只响应事件并可读取订阅端点,不自行扣款。
主要能力:套餐与附加项在发布内容的定价区块中定义,使用 app_publish action=set section=pricing 设置,再用 app_publish action=validate 校验,没有独立定价端点。plan_type 取值为 free、once、recurring、on_demand;addons 最多 5 个,name、price、slug 均为必填,全部价格为 SAR(无币种字段)。试用为顶层 plan_trial 与 trial_description。
使用方式:用 salla_apps action=connect 设置 webhook_url,app.subscription.* 与 app.trial.* 应用事件会自动投递,无需对 app.* 事件调用 salla_events action=subscribe(该动作仅用于店铺事件)。从验证过的事件驱动套餐状态,按 item_type 区分 plan 与 addon,持久化 end_date ?? renew_date,并在 expired/canceled 时标记失效。对账用 GET https://api.salla.dev/admin/v2/apps/{app_id}/subscriptions(OAuth,offline_access)。按量计费用 POST https://api.salla.dev/admin/v2/apps/balance 回写余额。外部循环续费用 POST /apps/subscriptions/{subscription_id}/renew,需处理 not_renewable、subscription_not_active、auto_renew_disabled、payment_failed(403)、rate_limit_exceeded(429)等错误。
限制与安全:必须校验 webhook 签名并做幂等,授权变更仅以验证过的服务端事件或对账结果为准;余额须服务端计算并在自有鉴权路径后提交。store_type !== "live" 时跳过计费逻辑。具体请求/响应结构与错误契约以官方 OpenAPI 文档为准。