salla-addon-purchase

Salla アドオンの課金サイクル

アドオンとは、アプリのプランに加えて Salla が課金する追加の購入可能な機能です。このスキルはアドオンの課金ライフサイクル（定義 → 有効化 → 更新 → キャンセル／期限切れ → 利用制御）を担います。マーチャントは埋め込みアプリ内で購入します（購入 UX → 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 です。自分で課金することはありません。連携先：購入 UX（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.* イベントはそこに自動配信され、購読呼び出しは不要です）。また、上記の各イベントに対するハンドラーを用意しましたか？」

---

ステップ 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。403 の not_renewable / auto_renew_disabled / payment_failed、429 の rate_limit_exceeded に対応してください）。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 スキル
App Events	https://docs.salla.dev/421413m0.md
Partners Portal	https://salla.partners
開発者コミュニティ（Telegram）	https://t.me/salladev