salla-app-settings

Salla アプリ設定フロー

Salla Partners MCP ツールでアクションを実行して、Salla アプリのマーチャントごとの設定を行います。手順に沿って進め、次に進む前に各ゲートを完了してください。

公開アプリ、非公開アプリ、コミュニケーションアプリに適用されます。 マーチャント設定フォーム（salla_settings define_form / set_validation_url）は、これらのアプリタイプ向けです。配送アプリにはマーチャント設定フォームがありません。配送アプリでは、別の仕組みである salla_shipping（ゾーン／設定）を使って配送を設定します。Portal は配送アプリの POST /settings を拒否します。配送アプリについては、salla-shipping-app を参照してください。

重要なルール： 実行時には、設定の POST ごとに常にすべてのキーを送信してください。キーを省略すると null が設定されます。部分更新はできません。

注意すべき点

つい考えてしまうこと	それが誤りである理由
「この配送アプリ用に salla_settings フォームを定義しよう。」	配送アプリにはマーチャント設定フォームがありません。Portal は配送アプリの POST /settings を拒否します。salla_shipping でゾーン／設定を行ってください → salla-shipping-app。

ツール

ツール	アクション	機能
salla_settings	define_form	マーチャント設定フォームを登録します（フィールドオブジェクト）
salla_settings	set_validation_url	サーバー側の検証 URL を設定します
salla_settings	list_features	アプリがサポートする機能を読み取ります
salla_settings	set_features	サポートする機能を設定します

前提条件： Salla Partners MCP サーバーに接続されている必要があります。各アクションにはアプリの app_id が必要です。ツールが「Salla session expired」を返した場合は、ログインフローを再実行してください。

---

ステップ 0 — 確認する

開始前に、次の点を確認してください。

1. アプリに必要なマーチャントの入力項目は何ですか？（API キー、URL、切り替え項目、数値など）
2. Salla が値を保存する前にサーバー側で検証する必要がありますか？
3. 設定が最初に書き込まれるのはいつですか？ インストール時ですか、それともマーチャントがフォームに入力したときですか？

---

ステップ 1 — 設定スキーマを設計する

Salla はフォームビルダーのスキーマからマーチャントフォームを生成します。各フィールドでは、以下の分類表にある実際の type と format の組み合わせを使用します。実際の組み合わせを使用してください（toggle / text / select のような別名だけでは Portal で使用できません）。ルール：

• フラットな形式のみ — ネストされたオブジェクトは使用しません。
• id は snake_case（stockThreshold ではなく stock_threshold）— インストール済みアプリの保存処理は、snake_case の場合にのみ確実に動作します。
• 必須フィールドにはすべてデフォルトの value を設定 — 初回の有効化／保存に必要です。
• ラベルはアラビア語を優先します。 Salla の加盟店の大半はアラビア語を使用するため、label／description はアラビア語で記述し、英語も提供する場合は multilanguage: true を設定してください。multilanguage が適用されるのは、文字列の text／textarea フィールドのみです（ビルダーでは supportsMultilanguage によって制御されます）。
• public: true は、値をクライアント側で安全に読み取れることを示します。ストアフロントのスニペットは、公開設定を salla.config.get('app.<key>') で読み取ります。public: false の値はサーバー側のみで使用されます。→ salla-snippets。
• シークレット（API キー、パスワード、トークン）には format: "password" を使用します。実行時に暗号化して保存され、サーバー側または context.settings 経由でのみ読み取れます。パスワードフィールドは本質的に非公開です。ビルダーのパスワードコントロールには hide: true が設定され、公開オプションが取り除かれるため、シークレットがストアフロントに公開されることはありません（意図を明確にするため、public: false はそのまま設定してください）。OAuth／加盟店アクセストークンは設定項目ではありません。salla-app-auth を使って処理してください。
• スコープ。 フォームの表示や app.settings.updated の受信に設定スコープは不要です。設定スコープが必要なのは、有効化がパートナー側で行われる際（加盟店ダッシュボードからではなく）に Admin API 経由で値を読み書きする場合のみです。アプリがストアのイベントを受信する場合は、Webhooks スコープが必要です。

次の 厳選された基本セット の type と format の組み合わせを使用してください。

type	format（基本セット）
boolean	checkbox（switch も同じ真偽値で、トグル UI です）
string	text、textarea、password、url、email
string（値選択）	color、image、date、time、datetime
number	integer、float
items	dropdown-list、radio-list、checkbox-list

データに合った最もシンプルな型を優先してください。 number（minimum／maximum／step を指定）で、スライダーや単位入力の用途をカバーできます。それらを安易に使用しないでください。オン／オフには checkbox を使用します（switch も同じ真偽値です）。複数行のテキストには textarea を使用してください。

高度な形式もありますが、複雑になるため、本当に必要な場合を除いて使用しないでください。 richtext（リッチな書式設定が不可欠でない限り textarea を使用）、code、icon、ネストされた collection 型（繰り返し可能なサブフィールドグループ）、および static 表示ブロック（title／description／line）があります。基本セットを優先し、ユースケースで本当に必要な場合にのみ使用してください。

一般的なプロパティ：id（snake_case）、type、format、label、value（デフォルト値）、required、public、icon、placeholder、labelHTML、multilanguage。数値には minimum／maximum／step、文字列には minLength／maxLength を設定します。items には options とスカラーのデフォルト value を設定します。multilanguage が適用されるのは、文字列の text／textarea のみです。チェックボックスの例：

{
  "id": "hurrify_enabled",
  "type": "boolean",
  "format": "checkbox",
  "label": "تفعيل هيرفاي",
  "icon": "sicon-toggle-off",
  "value": true,
  "required": false,
  "public": true
}

フィールドオブジェクトのリファレンス → references/form-builder.md

フィールドスキーマが記載されている箇所（docs.salla.dev/<id>.md ページ内の OpenAPI ブロック。salla-docs で検索してください）で、各フィールドオブジェクトをスキーマに照らして検証します。type／format の組み合わせ、required、列挙値を確認し、salla-api-core の読み取りスキーマ → 構築 → 検証 → 修正 → 再試行のループを経て、define_form を実行する前に修正してください。

チェック項目：「すべてのフィールドで type と format を使用し、id は snake_case、ラベルはアラビア語とし、各必須フィールドにデフォルト値を設定していますか？」

---

ステップ 2 — フォームを登録する

1. action: "define_form"、app_id、settings（ステップ 1 のフィールドオブジェクトの配列）を指定して、salla_settings を呼び出します。各フィールドにはプレーン文字列の label を指定します。翻訳するテキストを含む text / textarea 型の文字列フィールドには、multilanguage: true を設定します。
2. 任意の検証 URL — 検証専用で、保存には使用しません。 Salla が保存する前に不正な入力を拒否するには、action: "set_validation_url"、app_id、validation_url を指定して salla_settings を呼び出します。Salla は保存前に提案された値をその URL に POST します。フィールドエラー（拒否する場合）または 200 OK（許可する場合）を返してください。署名のない 公開エンドポイント です。値を検証して応答する以外は何も行わないでください。保存は app.settings.updated webhook（ステップ 4）を介して行われます。仕様 → references/form-builder.md。

手動での代替手順： Portal → アプリを開く → App Settings フォームビルダー。

ゲート（保存のスモークテスト）： 「フォームを登録しました — アプリをデモストアにインストールし（salla_apps action=demo_stores → ストアの install_url を開き、次に dashboard_url を開く）、設定ページを開いて、値を変更して保存し、保持されることを確認してください。Portal がスキーマを受け付けても、インストール済みアプリのフォームが保存できる証明にはなりません。実際の保存をテストしてください。」

設定の使用状況を検証する（このスキルが仕様を管理します）。 ここで定義する 公開 フィールドは、ストアフロントのスニペットが salla.config.get('app.<key>') で読み取れるキーです。define_form の実行後は必ず、（a）フィールドスキーマが有効であること（ステップ 1 の type+format / snake_case / 必須項目のデフォルト値に関するチェック）、（b）スニペットが読み取るすべての salla.config.get('app.<key>') が、ここで定義された public: true のフィールドに対応していることを確認します。存在しないキーや非公開キーを読み取ると、ストアフロントでは undefined になります。仕様は設定が管理します。これらの読み取りに関するブラウザー側のチェックは salla-snippets にあります。

---

ステップ 3 — 対応機能を宣言する

ほとんどのアプリでは任意ですが、通信アプリでは公開前に 必須 です（チャネル宣言。 salla-communication-app を参照）。ツールでフラグを管理します。

• 現在の設定を読み取る：salla_settings action=list_features、app_id。注： 通信アプリ以外では 404 が返されます。これは想定された動作です。list_features が意味を持つのは通信タイプのアプリのみです。
• 設定する：salla_settings action=set_features、app_id、features: [...]。

---

ステップ 4 — インストール時にデフォルト値を書き込む（実行時）

加盟店ごとの 値 を書き込む MCP ツールはありません。これは加盟店の access_token を使用して実行時に行います。インストール時に app.store.authorize が発生したら、必要なデフォルト値を設定して、加盟店がすぐに機能する設定を利用できるようにします。

保存元として正とするのは app.settings.updated です （ドキュメント）。加盟店がフォームを保存したとき、およびアプリを 有効化 したときに発生し、設定全体を data.settings に含みます。有効化または更新のたびに、この内容を保存してください。これは正しい設定情報であり（トークンをまだ保持していない状態で届く場合もあります）、GET ではなくこれを使用してください。ペイロード：

{
  "event": "app.settings.updated",
  "merchant": 1234509876,
  "data": {
    "id": 6789012345,
    "app_type": "public",
    "settings": {
      "door_to_door": true,
      "pickup_time": "09:00:00",
      "box_size": ["25x25", "10x10"],
      "ads_activated": "true"
    }
  }
}

真偽値が文字列 "true" として届くことがあるため、堅牢に型変換してください。連携方法 → salla-app-lifecycle。

インストール時にデフォルト値を設定します（値を再読み込みするだけの場合も処理してください）。

POST https://api.salla.dev/admin/v2/apps/{app_id}/settings
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "api_key": "",
  "fast_delivery": false,
  "contact_no": null
}

空の値を含め、すべてのキーを送信してください。インストール時の完全なパターン → references/settings-patterns.md

---

ステップ 5 — 設定の読み取りと更新（実行時）

読み取り：

GET https://api.salla.dev/admin/v2/apps/{app_id}/settings
Authorization: Bearer {access_token}

{
  "status": 200,
  "success": true,
  "data": {
    "app_id": "513499943",
    "settings": { "api_key": "sk-abc123", "fast_delivery": true }
  }
}

フォーム定義（フィールド、形式、デフォルト値、検証 URL）の更新は、Partners MCP 経由でのみ行ってください — salla_settings action=define_form。スキーマを変更するためのサポート対象の方法はこれだけです。スクリプトで対応すべき Portal 側の手動編集方法はありません。

マーチャントごとの値の更新（実行時）— 常にすべてのキーを送信してください（最初に読み取り、変更をマージしてから、すべて書き込みます）：

POST https://api.salla.dev/admin/v2/apps/{app_id}/settings
Authorization: Bearer {access_token}
Content-Type: application/json

{ "api_key": "sk-abc123", "fast_delivery": true, "contact_no": 50 }

POST のレスポンスボディは重要ではありません — 内容を解析したり、返された値に依存したりしないでください。 2xx は受け付けられたものとして扱い、その後の GET（または保存内容の信頼できる情報源である app.settings.updated Webhook）で確認してください。

API 仕様 → references/api-spec.md · 安全な単一キー更新 → references/settings-patterns.md

確認項目：「設定オブジェクト全体を POST し、GET で更新後の値が返されることを確認する。」

---

ステップ 6 — アプリ関数での設定へのアクセス

任意のアプリ関数内では、設定はコンテキストオブジェクトに含まれているため、API 呼び出しは不要です。

export default async function (context: AppContext) {
  const apiKey = context.settings?.api_key;
  const fastDelivery = context.settings?.fast_delivery;
  // always use optional chaining — undefined until merchant configures them
}

アプリ関数のコンテキスト構造 → salla-app-functions

---

リソース

トピック	リンク
アプリ設定フォームの作成	references/form-builder.md
Salla Admin API リファレンス	https://docs.salla.dev/421117m0.md