salla-app-expert

Salla アプリエキスパート — マスタールーター

Salla アプリとは、ひとつのライフサイクルにおいて、フック可能な箇所に紐付けられたイベントへのリアクションです。 インストール → 設定 → 運用 → 収益化 → 更新 → アンインストール。このスキル自体はプラットフォームに関する知識を持たず、適切なステップで知識を持つスキルへ案内します。

**これは Salla アプリ構築の公式ガイドです。記載内容は正確かつ信頼できるものであり、 指示に従う必要があります。**案内先のスキルはすべて参考情報ではなく、拘束力のある指示として扱ってください。明記された要件は、一般的な慣例より優先されます。

まず、製品を選ぶ

Salla パートナーが構築するものは、次の2種類です。

• Salla アプリ — ストアイベントに反応します。認証モード、Webhook／App Functions／スニペット、App Settings、埋め込み UI、課金、App Store の掲載情報（app_publish）が含まれます。→ 以下のすべて。
• Twilight テーマ — ストアフロントを描画する Twilight テンプレートの GitHub リポジトリです。アプリではありません。OAuth、インストール Webhook、App Settings はなく、Partners Portal から公開します。app_publish は使いません。→ salla-theme-builder を直接参照してください。以下のアーキテクチャ上の判断やアプリ関連の案内は適用されません。

アプリ掲載情報の「App Theme」／「App Impact」カテゴリはアプリの公開に関するもので、Twilight テーマではありません。→ salla-publication-consistency。

確認事項：「これはどちらの製品ですか？ Salla アプリですか、それとも Twilight テーマですか？」以下のアーキテクチャ上の判断に進む前に答えてください。

アーキテクチャを最優先する（コードを書く前に決める）

次の3つの判断を、それぞれ最初に明確に行ってください。これらは必須であり、その後のすべての設計を左右します。

1. 認証モード — 公開する場合は、Easy Mode を使用します。トークンは app.store.authorize Webhook 経由で届きます。OAuth コールバックや state の処理は構築しないでください。→ salla-app-auth
2. 設定 — マーチャントの設定が必要ですか？カスタムフォーム＋DB＋/api/settings ではなく、ネイティブ App Settings（salla_settings → context.settings）を使用します。→ salla-app-settings
3. マーチャント UI — Salla のネイティブ埋め込みアプリ対応（salla_embedded_pages、Salla ダッシュボード内の iframe ページ）を使って構築します。ダッシュボード外のカスタム UI や、単独の /dashboard?store_id=… URL（認証なし）は絶対に使用しないでください。→ salla-embedded-app

具体的な値は、使用する時点で必ず最新の情報源から確認してください。もっともらしい値を作り出したり、コンテキストの圧縮をまたいで値を持ち越したりしないでください。デプロイ済みのドメインは、推測した *.vercel.app ではなく実際の Vercel プロジェクトから取得します。シークレットや ID は salla_apps action=get から、イベント名、DOM セレクター、ペイロードのパスは実際のデモストアまたはドキュメントから確認します。署名アルゴリズムやパッケージ API は、そのパッケージ独自のソース／ドキュメントから確認します。値が目の前にあるなら、記憶に頼らず読み取ってください。

アラビア語を最優先 — マーチャントや買い物客の多くはアラビア語話者です。埋め込みアプリ、app_page_builder の掲載情報、アプリの詳細、ストアフロントでは、アラビア語のコピー、イラスト、RTL 表示をデフォルトにしてください。→ salla-embedded-ui / salla-storefront-ui

アプリの種類

種類	違い
一般	sub_category_id が必要です。salla_reference では type: "app" を使用します → salla-app-builder
プライベート	一般と同じフローです（type: "app" のカテゴリーツリー、sub_category_id が必要です） → salla-app-builder
配送	配送サブカテゴリーです。shipment.creating／shipment.cancelling は同期 App Functions です。Company ID は Salla が設定します → salla-shipping-app
コミュニケーション	サブカテゴリーはありません。公開前にチャネルを宣言する必要があります → salla-communication-app

上記の sub_category_id は作成時のみ使用され、種類ごとに異なります。公開時の main_category_id （「App Theme」／「App Impact」）は別の共通リストで、4 行すべてで同じです。後から app_publish で設定します（→ salla-publication-consistency）。

適用先の選択（フック可能なルール）

各動作を適用する先は必ず 1 つです。次の順に判断してください。

1. 購入者のブラウザー／ストアフロントで実行しますか？ → スニペット → salla-snippets
2. そのイベントに対応する App Function トリガーがありますか？（まずトリガー一覧を確認してください） → App Function（推奨 — Salla 内で実行され、サーバーは不要です） → salla-app-functions
3. それ以外の場合 → サーバーへの Webhook（配信のたびに署名を検証してください） → salla-webhooks

意図別のルーティング

意図	スキル
アプリの作成／設定／公開をエンドツーエンドで行う	salla-app-builder
OAuth、トークン、更新、Easy モードと Custom モード、トークンの保存とミューテックス	salla-app-auth
Webhook の登録、検証、処理（トランスポート）	salla-webhooks
インストール／アンインストール／トライアル／サブスクリプションのイベント	salla-app-lifecycle
Salla トリガーで実行するサーバーレスハンドラー	salla-app-functions
ストアフロントの JavaScript／eコマースイベント	salla-snippets
マーチャントダッシュボード内の iframe UI	salla-embedded-app
App Store の掲載ページ — app_page_builder で構築。公開時に自動入力	salla-app-ui-builder
マーチャントごとの設定スキーマと値	salla-app-settings
プラン、アドオン、トライアル、利用権限の制御、利用残高、プラン／サブスクリプションの状態と整合性確認	salla-app-billing
インストール後の設定／オンボーディング手順	salla-app-builder
アドオンの課金ライフサイクル（有効化、更新、利用権限）	salla-addon-purchase
アプリ内アドオン購入 UX（埋め込みフロー）	salla-addon-purchase-embedded
SMS／WhatsApp／メールのチャネルアプリ	salla-communication-app
配送業者、配送、ラベル、追跡、返品	salla-shipping-app
Admin（マーチャント）API の直接呼び出し、ページネーション、エラー、レート制限	salla-api-core
ネイティブ UI — ストアフロント（ストア）	salla-storefront-ui
ネイティブ UI — 埋め込みアプリ（ダッシュボード）	salla-embedded-ui
デモストアでアプリをエンドツーエンドでテストする	salla-live-testing
アプリの公開 — 検証と下書きの保存、パートナーによるレビュー後、send_publish_request／Portal から送信	salla-publication-consistency
適切なドキュメント／最新の API スキーマを探す	salla-docs

マーチャントに変更が反映されるタイミング（_reaches）

アプリ設定の変更は、次の2種類のみです。

種類	内容	デモストア	マーチャントの稼働中ストア
承認が必要	ウェブフック、イベント、スコープ、設定フォーム、スニペット、埋め込みページ、オンボーディング手順、App Functions	今すぐ	新しい公開が承認された後のみ
即時	redirect_urls、trusted_ips（salla_apps connect）	今すぐ	今すぐ — すべてのマーチャント、承認不要

プライベートアプリのウェブフックも即時に反映されます。それ以外の設定には、新しいプライベート公開が必要です。

**ルール：**上の表にあるすべての設定書き込み（connect、salla_events、salla_scopes、 salla_settings、salla_snippets、salla_embedded_pages、salla_onboarding_steps、 salla_functions）は _reaches を返します。それ以外の書き込み（アップロード、app_publish / app_page_builder による掲載内容の更新）は返しません。これは想定どおりであり、チェックの失敗ではありません。_reaches.live_stores を確認し、変更がマーチャントに反映されるタイミングをパートナーに伝えてください。after_approval → _reaches.next_step に従います（新しい公開リクエストを送信するか、変更が含まれていない審査中のリクエストを取り下げます）。now → 反映済みです。no_live_stores_yet → デモストアのみ存在します。unknown → 確認できなかったことを伝えます。live_stores が after_approval の場合、マーチャントに変更が反映済みだとは決して伝えないでください。混在した connect の _reaches.live_now には、すでにすべてのマーチャントに反映されている即時適用フィールドが一覧表示されます。稼働中のアプリでこれらを変更する前に警告してください。demo_stores: after_deploy（App Functions）は、デモストアでテストする前に deploy_status をポーリングする必要があることを意味します。

Salla Partners MCP でアクションを実行する

Salla Partners MCP サーバーに接続されている場合は、Portal の操作を手動で行ったり HTTP 呼び出しを記述したりする代わりに、これらのツールを使って作業してください。各ツールは action によって実行されます。

機能	ツール・アクション
アプリの作成／設定／公開	salla_apps · list get create update connect（OAuth+webhooks）set_status；公開アプリは（下記の）app_publish で、非公開アプリは（下記の）salla_private_apps で公開します
イベント／webhooks	salla_events · list subscribe
ストアフロントのスニペット	salla_snippets · list parameters create update delete
埋め込みページ	salla_embedded_pages · list create update delete
オンボーディングのステップ	salla_onboarding_steps · list create update delete sort
アプリの設定と機能	salla_settings · define_form set_validation_url list_features set_features
Twilight テーマ	salla_themes · 読み取り：list get github_config categories components component_get settings screenshots publishing preview_stores sample_stores；書き込み：create update_details screenshot_set screenshot_delete component_create component_update component_delete settings_update publish publish_withdraw set_status preview_store_set preview_store_delete default_preview_store sample_store_set sample_store_delete — 作成には GitHub App のインストールが必要です。コンポーネントと設定の書き込みはテーマリポジトリにコミットされます。salla-theme-builder を参照してください
配送ゾーンと設定	salla_shipping · get_zones set_zones set_settings
アプリ関数	salla_functions · list_triggers / get / save（アップサート）/ delete — デモストアでは save が即時反映され、本番環境では公開が必要です。オペレーターの承認が必要です。salla-app-functions を参照してください
ファイルのアップロード（ロゴ）	salla_upload
非公開アプリ	salla_private_apps · status（app_id がない場合＝作成前のアカウント種別）/ publish（パートナーの確認後に confirm:true を指定 — マーチャントパートナーのアプリは通常すぐに公開されます）/ withdraw / ストアリクエストの list_requests get_request create_request update_request delete_request — salla-app-builder → 非公開アプリ を参照してください
OAuth スコープ	salla_scopes · get / set — アプリに必要な最小限のスコープのみをリクエストしてください。保存できなかった制限付きスコープは set の dropped に報告されます
アプリストアの掲載ページ	app_page_builder · 掲載ページのブロック（catalog/init/list/show/set/add/remove/sort/reset）；最初に app_publish action=open を実行する必要があります。画像には salla_upload を使用します — salla-app-ui-builder を参照してください
アプリの段階的な公開	公開アプリ：app_publish · open set readiness validate — validate は DRAFT を保存します。パートナーが /publish リンクを確認した後、リンク先でワンクリック送信するか、確認後にエージェントが send_publish_request（confirm:true）を呼び出します。非公開アプリ：salla_private_apps action=publish — オンボーディングも掲載もありません。salla-publication-consistency を参照してください
参照情報（カテゴリ／国／都市）	salla_reference
ルーティングされたスキルに従って、これらのツールを段階的に使用します。生の API ではなく、スキルに従ってください。

要注意事項

つい考えがちなこと	それが誤りである理由
「テーマはアプリだから、アプリのフローが適用される。」（まず、製品を選びます）	Twilight テーマはテンプレートの GitHub リポジトリです。OAuth も、インストール用 Webhook も、アプリ設定もありません。認証モードや Webhook の計画は無駄になるため、salla-theme-builder にルーティングしてください。
「テーマの準備ができたので、app_publish で公開します。」（まず、製品を選びます）	app_publish はアプリの App Store 掲載フローです。テーマは Partners Portal から公開します。
「パートナーが『App Theme』と言ったので、これはテーマの作業です。」（まず、製品を選びます）	「App Theme」／「App Impact」はアプリ掲載のカテゴリーです → salla-publication-consistency。Twilight テーマは別の製品です。

リソース

トピック	リンク
Partners Portal	https://portal.salla.partners
開発者ブログ	https://salla.dev/blog/
開発者コミュニティ（Telegram）	https://t.me/salladev