salla-shipping-app

Salla 配送アプリのフロー

Salla Partners MCP ツールで操作を実行して配送アプリを構築します。 手順に沿って進め、次に進む前に各ゲートを完了してください。

配送アプリは公開する必要があります — このカテゴリでは非公開アプリはサポートされていません (https://docs.salla.dev/422995m0.md)。

2 つのアプリモデル — まず選択してください

Salla には明確に異なる 2 つの配送アプリモデルがあります (https://docs.salla.dev/422988m0.md)。作成と OAuth は共通ですが、セットアップ、ライフサイクル、テストの方法は異なります。

モデル	内容	ライフサイクルを管理する場所
配送管理（運送業者／AWB）	1 つの配送会社と連携します。最新の Salla AWB モデルです — Salla Partners 内にアプリ関数を記述し（バックエンドの構築やホスティングは不要）、配送業者の API を呼び出して AWB を生成し、Salla に返します。	references/shipment-cycle.md
注文フルフィルメント	複数の配送業者にまたがって機能します — 注文を受け取り、最適な配送業者／支店を自動割り当てしてから、割り当てられた配送アプリを動作させます。	references/fulfillment-cycle.md

Salla AWB は、推奨される配送管理モデルです — サーバー、デプロイ、ポーリングの保守が不要で、加盟店のAWB 作成画面（注文 → 配送ラベルを作成）に配送サービスが標準で表示されます。ロジックは Salla のアプリ関数ランタイムで実行され、Salla Shipping API に直接アクセスできます (https://docs.salla.dev/1792089m0.md)。

AWB の配送業者一覧への掲載／Shipping Company ID： 配送管理（AWB）アプリを加盟店の AWB 配送業者オプションに掲載するには、[email protected] にメールしてください (https://docs.salla.dev/1792111m0.md)。**Shipping Company ID** は Salla のみが割り当てます — 自分で設定することはできません。

ツール

ツール	アクション	機能
salla_reference	categories	type=shipping → sub_categoriesからsub_category_idを選択します。公開用のmain_category_id／categoriesは、同じ呼び出しのmain_categories／categoriesから取得します（配送カテゴリではなくApp Theme）
salla_upload	—	ロゴをアップロードします → ファイルのid
salla_apps	create / get / connect / set_status	OAuth／ウェブフックを作成して設定します。getは現在のsearch_optionsの選択内容を含むアプリの状態を読み取ります。配送アプリは公開アプリのため、app_publishで公開します
app_publish	open / set / validate	公開アプリ：公開内容を検証します（DRAFTを保存します。パートナーはPortalで送信します）
salla_events	list / subscribe	非同期の配送イベントを購読します
salla_functions	list_triggers / save / preview	同期配送用のApp Functionsを実装してテストします
salla_shipping	get_zones / set_zones / set_policy_options / list_zone_countries / list_zone_cities / list_search_options	配送料金ゾーンと、ポリシーオプション／配送機能の検索オプションを設定します。これらは、現在のライブ版Shipping Settingsページで管理される2つの項目です

前提条件： Salla Partners MCPサーバーに接続している必要があります。すべての手順でapp_idを引き継いでください。ツールから「Salla session expired」が返された場合は、ログインフローを再実行してください。

---

ステップ0 — 確認

開始前に、以下を確認してください。

1. どのモデルですか？（ライフサイクルをどのリファレンスが管理するかが決まります。上の表を参照してください）
   • 配送管理／AWB — 1つの配送業者と連携します。AWBを生成するshipment.creating／shipment.cancelling App Functionsを作成します
   • 注文配送 — 複数の配送アプリから最適な配送業者／支店を自動割り当てします
2. どの配送業者またはプロバイダーと連携しますか？
3. 代金引換（COD）に対応していますか？
4. 配送業者が対応する地域／配送ゾーンはどこですか？

---

ステップ 1 — アプリを作成する

1. カテゴリーを解決します：salla_reference action=categories type=shipping → sub_categories。 sub_category_id は、sub_categories から選んだ配送サブカテゴリーでなければなりません。配送以外のサブカテゴリーは拒否されます。（現在、Fulfillment / Other / Drop-shipping の ID は 45 / 46 / 54 です。これらの ID は例示用です。ハードコードせず、必ず最新の値を読み取ってください。）同じ呼び出しの main_categories/categories を、公開時の main_category_id/categories に再利用しないでください。これらは配送に限定されない別個の「アプリテーマ」／「アプリへの影響」リストです → step-basic-information.md。
2. ロゴをアップロードします：salla_upload（正方形の 1:1、250×250 px 以上）→ ファイルの id。
3. アプリを作成します：salla_apps action=create で type = shipping、sub_category_id、name、short_description（50–200）、app_url、email、logo を指定します。アプリは公開に設定してください（このカテゴリーで対応しているのは公開のみです）。

結果として app_id が返されます。（AWB の配送業者オプションに表示するには、[email protected] にメールしてください。上記のモデルのセクションを参照してください。）

手動での代替手段： Portal → My Apps → Create App（Public、カテゴリーは Shipping App）。 詳細な手順：https://docs.salla.dev/422995m0.md

確認ポイント：「アプリを作成しました — salla_apps action=get で app_id を確認してください。」

---

ステップ 2 — OAuth、スコープ、Webhook の接続

1 回の salla_apps action=connect 呼び出しで OAuth と Webhook を設定します（有効なスコープのスラッグは salla_apps action=get から読み取ってください。スコープカタログを取得するエンドポイントはありません）。

• scopes — 配送と注文へのアクセス（slug → "read" | "read_write"）。アプリに必要な最小限のスコープをリクエストしてください。書き込みが必要でない限り read_write より read を選び、使用しない広範なスコープはリクエストしないでください。
• redirect_urls、webhook_url、webhook_security_strategy: "signature"

Webhook の署名シークレットは connect では生成されません。Partner Portal（https://portal.salla.partners/apps/{app_id}）で作成／ローテーションし、デプロイ前に salla_apps action=get（webhook_secret フィールド）で現在の値を読み取ってください。HMAC 検証用に保存します。

OAuth、トークンの保存／更新、マーチャントごとの更新ロックについては → salla-app-auth。Webhook の署名検証（生のボディに対して X-Salla-Signature を検証し、無効な署名は拒否して、シークレットを決してログに記録しないこと）と冪等性については → salla-webhooks。これらの処理はそれぞれに任せ、ここで再実装しないでください。

確認ポイント：「_partial なしで接続が適用されました。Webhook URL は稼働していて、200 を返しますか？」

---

ステップ 3 — 配送ゾーンと設定を構成する

配送アプリにはマーチャント向け設定フォームがありません。 salla_settings define_form は呼び出さないでください。このフォームは公開／非公開／コミュニケーションアプリ用であり、Portal は配送アプリへの POST /settings を拒否します。配送設定は、以下の salla_shipping のゾーンと検索オプションです。配送業者の認証情報は Shipping Settings URL 経由で設定します。設定フォームの概念自体については → salla-app-settings。

このステップで扱うのは、現在の Shipping Settings ページで管理できる内容だけです。それ以外は扱いません。 より新しい、機能が豊富な配送設定モデル（国別の会社タイプ、有効なサービス種別、構造化された所要時間）がバックエンドの機能フラグの背後にありますが、まだリリースされておらず、マーチャント向けページもありません。これを前提に構築しないでください。また、salla_shipping にこれらのアクションがないことも想定内です。このフラグがリリースされた場合は、このステップに新しいサブステップが追加されます。それまでは、ゾーンと検索オプションだけが設定可能です。

salla_shipping で管理するのは、独立した 2 つの項目です。ゾーンと、2 つのオプショングループをまとめた設定一式です。それぞれ別の呼び出しで保存するため、2 つの独立したサブフローとして扱ってください。

3a — 料金ゾーン（必須）

ゾーンは、国と複数の都市を対象とする料金ルールです。ゾーンごとの作成／更新／削除エンドポイントはありません — set_zones は常にゾーンリスト全体を1回の呼び出しで置き換えます。ゾーンを追加するには、既存のすべてのゾーンと新しいゾーンを再送信します。ゾーンを編集するには、変更したゾーンを含むすべてのゾーンを再送信します。ゾーンを削除するには、そのゾーン以外のすべてのゾーンを再送信します。

1. 現在の状態を取得します： salla_shipping action=get_zones、app_id。注： 新しく作成された配送アプリには、事前設定済みのデフォルトゾーン（すべての国 → すべての都市、固定料金）がすでに含まれています。レスポンスが空でないからといって、すでに設定済みとは限りません。

2. ゾーンを書き込む前に、実際の国／都市 ID を確認します。 これらは salla_reference の ID ではありません — ゾーンは独自の ID 空間を使用します。

   • salla_shipping action=list_zone_countries、app_id → 実際の国 ID。
   • salla_shipping action=list_zone_cities、app_id、country_id（検索する場合は任意で keyword）→ その国の実際の都市 ID。
   • id: -1 の「すべての国」／「すべての都市」センチネルは、どちらのリストにも返されません — 実環境で確認済みです。API が返すのは実際の ID のみです。-1 は、実際の配送設定ページで表示用にクライアント側が先頭に追加する慣例値です。加盟店が「すべての地域」を意味する場合は、リストのレスポンスから探すのではなく、ゾーンの country／city に直接指定してください。
   • ここで salla_reference／一般的な国 ID を使用してもエラーにはなりません — ポータルは書き込みを黙って受け入れますが、何も実行しません。そのため、バグのようにしか見えません。推測はせず、必ず list_zone_countries／list_zone_cities（または -1 センチネル）から country／city を取得してください。

3. ゾーンの各項目について、加盟店／パートナーに確認し、ビジネス上の判断を勝手に行わないでください。 料金、配送対象、配送期間、代金引換への対応は、加盟店／パートナーだけが把握している事実です。アプリやそのカテゴリから推測できるものではありません。

   • get_zones（手順1）に事前設定済みのデフォルトゾーンしか表示されない場合は、初回設定です。以下の聞き取りをすべて行ってください。実際のゾーンがすでに存在する場合は、その内容を要約し、最初からすべて聞き直すのではなく、何を変更するのか（国の追加、料金の編集、ゾーンの削除など）を具体的に確認してください。
   • 初回の聞き取りは国ごとに1つずつ行います。まず追加する国／地域を確認し、その ID を特定して（手順2）、そのゾーンの料金タイプ（固定または重量別の変動制）、金額、配送期間の文言、代金引換に対応するかどうか（対応する場合は手数料も）を尋ねてください。内容を確認してから、「ほかに追加する国はありますか？」と尋ね、加盟店が終了と言うまで繰り返します。国が1つだけという回答で聞き取りを終えたと判断しないでください。
   • 加盟店が国の追加を終えたと言った後に（最初の国の後ではありません。以下の判断は、実際の配送対象リストが完成して初めて意味を持ちます）、事前設定済みの「すべての国／すべての都市」を対象とする包括ゾーンを残すか削除するか、明示的に確認してください — どちらかを黙って判断してはいけません。残すと、リストにない国にも（おそらく誤った）デフォルト料金が適用されます。削除すると、リストにない国には料金が適用されません。
   • 加盟店に代わって、もっともらしい料金、配送期間、代金引換のデフォルト値を決めないでください。聞いていない場合は質問し、推測を送信しないでください。

4. 送信します： salla_shipping action=set_zones、app_id、shipping（ゾーンオブジェクトの配列）。各ゾーンの項目：

   フィールド	必須？	備考
   id	新しいゾーンの場合は省略／0	既存のゾーンをその場で更新するためのゾーン ID です。
   country	✅ 常に必須	list_zone_countries から取得します（または「すべて」の場合は -1）。
   city（配列）	✅ 常に必須	list_zone_cities から取得します（または「すべて」の場合は [-1]）。
   cities_excluded（配列）	任意	国／都市の選択範囲に含まれる都市のうち、除外する都市です。国／都市が「すべて」を示す値の場合は意味を持ちません。
   fees.type	✅ 常に必須	"fixed" | "rate" | "automatic"。
   fees.amount	✅ type: "fixed" の場合に必須	一律料金です。1～9999 である必要があります — Portal に到達する前に set_zones によって適用されます（下記参照）。
   fees.amount_per_unit、fees.up_to_weight、fees.per_unit	✅ type: "rate" の場合に必須	変動料金制：しきい値を超えた重量に対する単位ごとの料金です。3 つすべてを同時に指定する必要があります。amount_per_unit／per_unit は 0 より大きく、up_to_weight は 1～9999、すべて上限は 9999 です。
   duration	✅ 常に必須	"2-3 business days" などの自由形式のテキストです — 構造化された値ではありません。
   cash_on_delivery.status	✅ 常に必須（ブール値）	—
   cash_on_delivery.fees	✅ cash_on_delivery.status: true の場合に必須	0 より大きく、上限は 9999 です。

   この呼び出しはゾーンリスト全体を置き換えます — 保持するゾーンをすべて含めてください。

厳格に適用されるビジネスルール — ゾーンの country／city は、作成後に変更できません。
既存のゾーンの国や都市は変更できず、変更できるのは料金、期間、代金引換のみです。set_zones は、送信されたゾーンの id が既存のゾーンと一致していて、country／city が異なる場合は拒否します — ゾーンを「移動」しようとするのではなく、新しいゾーンを作成してください。 Portal は不正な手数料データを拒否せず、気づかれないまま破損させます。 ライブテストで確認済みです。"rate" タイプのゾーンで amount_per_unit／up_to_weight／per_unit が欠けていても作成され、3 項目すべてがデフォルトの 0 になります（エラーではなく、永久に送料無料のゾーンです）。fees.amount の負の値は気づかれないまま 0 に丸められます。また、範囲外の手数料（例：999999）を指定すると、Portal は不正なゾーンだけでなく、送信されたバッチ全体を気づかれないまま破棄し、それでも成功を報告します。set_zones はネットワーク呼び出しの前に、すべての手数料フィールドが上の表の範囲内であることを検証するようになりました。さらに、書き込みのたびにゾーン一覧を再取得し、送信内容が実際に反映されたことを確認します。「成功した」書き込みが完全に保存されていなければ、気づかれないまま成功と偽るのではなく、明確なメッセージを付けて呼び出しが失敗します。set_zones が「post-write zone count doesn't match」というメッセージで失敗した場合は、同じバッチをむやみに再送信しないでください。バッチ内の各ゾーンを個別に確認してください。

ゲート：「salla_shipping action=get_zones にゾーンが反映されている（国／都市／料金／代引きが正しい）。既存の id の country／city が変更されていない。また、set_zones が成功を返しており、書き込み後の不一致エラーではない。」

3b — ポリシーオプションと配送機能（必須）

これらは、1 つのカタログと 1 回の保存呼び出しを共有する、意味的に異なる 2 つのオプショングループです。それぞれに別々のフローを作らないでください。

• ポリシーオプション — 運送状／配送の詳細フィールド（梱包タイプ、商品タイプ、寸法など）で、「配送体験を簡単にするため、配送の詳細を特定するのに役立つ」ものです。これらは 配送そのもの を表します。
• 配送機能 — App Store の検索／絞り込み用メタデータ（「タイプや配送エリアによる配送アプリの検索に役立つ」もの）です。これらは加盟店がマーケットプレイスであなたのアプリを 見つける のに役立つものであり、配送データではありません。

1. カタログを取得する： salla_shipping action=list_search_options、app_id → 利用可能な各オプション。各項目は {id, slug, type, is_filter, is_shipping_policy, categories, name: {ar, en}, values: [{id, slug, name: {ar, en}}]}。 さらに、レスポンスの meta に shipping_category の ID が含まれます。次のように自分で分類します。

   • ポリシーオプション = is_shipping_policy === true のオプション。
   • 配送機能 = is_filter === true AND is_shipping_policy === false AND categories にレスポンスの shipping_category ID が含まれるオプション。 （これは、ライブの「配送設定」ページが同じカタログを絞り込む方法とまったく同じです。別の基準を導き出さないでください。）既知の問題： ライブテストでは、環境によって meta が空で返される（shipping_category ID がない）ことが確認されています。その場合、カテゴリ ID を推測しないでください。すべてのオプションの categories 配列が単一の共通 ID を持つか確認してください（実際には共通 ID を持っています。その共通 ID が配送カテゴリです）。結果が曖昧であれば、気づかれないまま回避するのではなく、ブロッカーとして報告してください。どちらのルールにも当てはまらないカタログ項目もあります（ライブで確認済み：included_destination_cities、destination_countries など、地理的な配送エリアを表す slug — is_filter: false AND is_shipping_policy: false）。これらは新しい未リリースの配送設定フローに属します（バックエンドの shipping_settings_page 機能フラグで制御されており、このスキルの対象外です。このステップの冒頭にある注記を参照してください）。ライブの「配送設定」ページも、同じ分類ルールに従ってこれらを無視します。加盟店にこれらについて尋ねないでください。これは仕様であり、分類ロジックのバグではありません。

   ライブで確認済みのカタログ（例示です。Salla はオプションを追加／削除する可能性があるため、必ず実際のレスポンスを確認してください。これらの slug を完全な一覧としてハードコードしないでください）：

   グループ	slug	アラビア語ラベル	意味
   ポリシーオプション	shipment_content_type	أنواع الشحن	荷物に含まれる商品の種類（例：電子機器）。
   ポリシーオプション	packaging_type	أنواع التغليف	荷物の梱包方法。
   ポリシーオプション	support_dimensions	أبعاد الشحنة	販売者が荷物の寸法を入力する必要があるかどうか。
   ポリシーオプション	support_number_of_box	عدد الصناديق	販売者が箱数を入力する必要があるかどうか。
   配送機能	delivery_service_type	طرق الاستلام والتسليم	配送業者が提供する集荷・配達方法。
   配送機能	shipping_cover_type	نطاق تغطية الشحن	地理的な配送範囲（例：国内／国際）。
   配送機能	company_type	نوع الشركة	配送業者の会社の種類／分類。
   配送機能	services	الخدمات	配送業者が提供するサービス。
   配送機能	support_change_name	الإسم المعروض للشركة	ディスカバリーメタデータではありません — 販売者向けの実際の設定項目です。販売者がストアフロントのチェックアウト画面で、配送業者名の表示を上書きできるかどうかを指定します。配送機能グループに含まれていますが、ほかの運用設定と同様に慎重に扱ってください。

2. 選択内容を作成する前に、各オプションのtypeを確認してください。

   • "multi_select"／"select" — そのオプションのvalues[]から、idで1つ以上の項目を選択します。
   • "boolean" — 単純なtrue／falseの値ではありません。slugが"true"または"false"の値オブジェクト1つを選択します（各ブール型オプションには、実際のvalues[]項目として両方が含まれています）。どちらも選択しない場合は「未回答」を意味します。
   • is_requiredが意味を持つのはポリシーオプションのみです。実際の配送設定ページでは、ポリシーオプションにのみオプションごとの「必須」チェックボックスが表示されます。配送機能には、UI上で同等のコントロールがありません。APIでは技術的にはどのオプションにもis_requiredを指定できますが、配送機能に設定しても、実際のマーチャント向け操作画面には同等の機能がありません。特別な理由がない限り、配送機能では未設定のままにしてください。

3. 実際のカタログを使ってマーチャント／パートナーにヒアリングしてください。利用する値を推測してはいけません。 各オプションの正しい値は、マーチャント／パートナーだけが知っているビジネス上の事実です（梱包方法、配送範囲、会社の種類など）。カタログが示すのは「選択可能な回答」であり、実際の回答ではありません。

   • まずsalla_apps action=getのsearch_optionsフィールドを確認してください。空または存在しない場合は初回設定なので、以下の手順で全項目をヒアリングします。すでに選択内容がある場合は、それを要約したうえで、すべてを再度尋ねるのではなく、変更点を具体的に確認してください。
   • 初回のヒアリングは、グループごとにまとめて行います。まず、4つのポリシーオプションをすべて1つのメッセージで提示し、手順1で取得した実際の各オプションのname.ar／name.enラベルとvalues[]の選択肢（作り出した選択肢は使わないでください）を使って、それぞれの値を尋ね、「必須」にするかどうかも明示的に確認します。次に、5つの配送機能をすべて2つ目のメッセージで提示し、同じく実際のラベルと値を使います。ただし、上記の違いにより「必須」かどうかは尋ねません。実際のカタログでいずれかのグループにオプションが1つもない場合、そのグループのメッセージは省略してください。
   • support_change_name（配送機能）は、専門用語ではなく平易な言葉で尋ねてください。実際の意味は「マーチャントが、自分のストアのチェックアウト画面で配送業者の表示名を変更できるようにしますか？」です。スラッグをそのまま読み上げるのではなく、このように尋ねてください。

4. 両方のグループを1回の呼び出しでまとめて送信してください。 salla_shipping action=set_policy_optionsにapp_idとsearch_options（{id, is_required?, values}の配列）を指定します。idは検索オプションのID、valuesは手順3で確認した選択済みのvalues[].id、is_requiredはオプションごとの任意の切り替え値です。ポリシーオプションと配送機能の項目を同じ配列に混在させてください。この区分は説明上のものであり、構造上のものではありません。この呼び出しは現在の選択内容を置き換えます。保持するすべてのオプション（両方のグループ）を含めてください。

5. 実際に保存された内容を確認してください。 salla_shippingには、アプリの_現在の_選択内容を読み戻すアクションがありません。action=list_search_optionsが返すのは静的なカタログ（選択可能なすべてのオプション／値）のみで、保存内容の影響は受けません。実際に選択されている内容を確認するには、salla_apps action=getを呼び出し、そのsearch_optionsフィールド（現在のアプリの{id, values}配列）を確認してください。現在の選択内容を確認できるのは、これだけです。呼び出しの間に内容を自分で記録しようとせず、再度読み込んでください。

ゲート：「salla_shipping action=set_policy_optionsが成功し、salla_apps action=getのsearch_optionsフィールドに、保持する予定だったすべてのオプションが表示されていること（指定漏れによる欠落がないこと）。」

注意すべき点 — 配送エリアとポリシーオプション

安易に考えがちなこと	それが誤りである理由
「聞かなくて済むように、妥当そうな料金／期間を設定しよう。」	料金は加盟店が決めるものであり、推測できるものではありません。もっともらしい数字でも、間違っていれば実際の料金設定ミスとなり、実際の顧客に影響します（3a）。
「国を1つ挙げていたから、それが配送対象のすべてだろう。」	加盟店は、促されなければ対象国の全リストを伝えないことがよくあります。配送エリアのヒアリングを終える前に、ほかにもあるか必ず明示的に確認してください（3a）。
「必須かどうかは聞かず、任意にしておこう。」	必須か任意かは加盟店にとってチェックアウトをブロックする実際の動作であり、形式的な項目ではありません。すべてのポリシーオプションについて明示的に確認してください（3b）。
「スラッグ名を見ればわかるので、加盟店向けに言い換える必要はない。」	support_change_name などは、スラッグだけでは本来の意味が伝わりません（たとえば、チェックアウトに表示される名前を上書きする設定です）。専門用語ではなく、平易な言葉で尋ねてください（3b）。

---

ポータルでは引き続き、配送設定 URL を設定します。これは、Salla が加盟店ダッシュボードに読み込むページで、配送業者の認証情報（API キー、アカウント番号）を収集します。これは上記の配送エリア／検索オプションとは別の概念です。この URL のページで収集するのは、ストアごとの配送業者認証情報であり、アプリ自体の設定ではありません。認証情報を表示または保存する前に、加盟店／セッションを認証し、暗号化して保存し、決してログに記録しないでください。（埋め込みページのセッション認証 → salla-embedded-app。）

セットアップガイド：https://docs.salla.dev/422996m0.md

---

ステップ 4 — アプリの主要機能（配送管理／AWB）

配送管理（AWB）アプリは、2つの同期 App Functions（salla_functions action=list_triggers カテゴリ merchant_actions）を実装し、3つの非同期イベント（merchant_events）をサブスクライブできます。App Functions は Salla のランタイム内で実行され、戻り値によって操作の内容を決定します。また、テストには App Function MCP プレビューを使用します。Webhook エンドポイントではありません。

トリガー	カテゴリ（MCPで確認済み）	戻り値の型	発生するタイミング	ハンドラーの処理
shipment.creating	merchant_actions（同期）	Promise<Shipment>	出荷または返品が作成されたとき（注文 → completed、または配送ラベルを作成／返品ラベルを作成）	配送業者の API を呼び出して AWB を生成し、Shipment（番号＋PDF ラベル＋ステータス）を返します
shipment.cancelling	merchant_actions（同期）	Promise<Resp>	出荷／返品がキャンセルされる前	配送業者の API を呼び出して無効化／キャンセルし、**Resp.success()**を返します（またはエラーを返して拒否します）
shipment.created	merchant_events（非同期）	—	出荷が作成された後	後続システムの状態を同期します（バックグラウンド）
shipment.cancelled	merchant_events（非同期）	—	出荷がキャンセルされた後	整合性を確認／通知します（バックグラウンド）
shipment.updated	merchant_events（非同期）	—	出荷の詳細が変更された後	トラッキング／ステータスを同期します（バックグラウンド）

save に指定する名前： 同期キャンセル関数は shipment.cancelling （merchant_actions、Resp を返す）です。AWB のドキュメントでは画面名が「Shipment Cancelled」となっていますが、これは変わりません（https://docs.salla.dev/1797616m0.md）。 shipment.cancelled は別個の非同期イベントです。salla_functions action=list_triggers で名前を確認してください（詳細 → references/shipment-cycle.md）。

shipment.creating は新規出荷と返品の両方を処理します。1 つの関数で、ペイロードの type フィールド（"shipment" と "return"）に応じて分岐します（https://docs.salla.dev/1792119m0.md）。

これらの同期トリガーは Webhook ではなく、App Functions です。
salla_functions action=save を使い（トリガーごとに関数を 1 つ）、salla_functions action=get から取得した変更できないラッパーを使用して実装します。ハンドラーのシグネチャ（それぞれの最初の行は変更できません）：

// shipment.creating — generate the AWB and return a Shipment
export default async (context: Shipments): Promise<Shipment> => {
  const { payload, settings, merchant } = context;
  const { data: shipment } = payload; // type: "shipment" | "return"

  const result = await callCarrierAwbApi(shipment); // your third-party API

  // setShipmentNumber() is REQUIRED; setPdfLabel/setStatus shape the AWB.
  // Return Shipment.error("…") on carrier failure.
  return Shipment.success()
    .setShipmentNumber(result.awb_number)
    .setPdfLabel(result.label_url)
    .setStatus(ShipmentStatusEnum.IN_TRANSIT);
};

// shipment.cancelling — void with the carrier, return Resp (NOT a Shipment)
export default async (context: Shipments): Promise<Resp> => {
  await voidWithCarrier(context.payload.data.shipping_number);
  return Resp.success().setData({});
};

App Function の仕組みは salla-app-functions ファミリーにあります。 V8 サンドボックスの制限、変更できないテンプレート／最初の行のルール、save／validate、同期処理の 5 秒制限 （各内部 async 呼び出しは 2 秒未満）、事前認証済み Admin API（Authorization ヘッダーは不要）、 Resp／Shipment ビルダーのランタイムについては、設計 → salla-app-functions-design、 ハンドラー本文 → salla-app-functions-handler、save／validate → salla-app-functions-validate、テスト／プレビュー → salla-app-functions-test を参照してください。 配送に関する詳細、つまり Shipment ビルダーの全メソッド一覧、ShipmentStatusEnum、 Shipments コンテキストのペイロード、3 つの AWB 処理フローについては、 references/shipment-cycle.md を参照してください。 保存する前に、取得した型定義でペイロードのフィールド名を確認してください。 テンプレートを取得してから（salla_functions action=get）、salla_functions action=save を実行するまでの間、ハンドラーの本文は salla-app-functions-handler に任せてください。本文の作成に加え、action=get の types 配列にあるすべての URL を取得し、.d.ts 定義から context.payload.data にある shipment.creating／shipment.cancelling のペイロードの正確なフィールド名（住所、荷物、重量、type: "shipment" | "return"）を読み取るルールもこのツールが担当します。sender_address／receiver_address／weight のような、運送業者 API 風のフィールド名を推測しないでください。

ゲート：「ハンドラーの本文は salla-app-functions-handler で作成し、context.payload.data のすべてのフィールドをトリガーから取得した types の .d.ts と照合して確認済みで、推測したフィールドはなく、salla_functions action=save を実行する前の状態ですか？」

App Function MCP プレビューでテストします（担当：salla-app-functions-test）。関数を保存し、salla_functions action=deploy_status が COMPLETED になるまでポーリングしてから、app_id、trigger、デモ用の store_id、トリガーのフォームフィールド（例：実際の shipment_id）を指定して salla_functions action=preview を実行します。

非同期イベント（shipment.created／shipment.cancelled／shipment.updated）は通常のストアイベントです。salla_events action=subscribe で登録してください（この操作はリスト全体を置き換えるため、有効にしたいイベントをすべて含めてください）。salla_events action=list で確認します。トランスポート（署名、高速な 200 応答、冪等性）→ salla-webhooks。

App Function は AWB を同期的に返します。運送業者の確認後に行う帯域外の更新（実際の送料、追跡情報、ステータス変更）は、パートナー起点の Update Shipment Details REST 呼び出し（PUT /shipments/{id}、加盟店の保存済み access_token を使用）で送信してください。トークンの保存／更新 → salla-app-auth。エンドポイントの形式、必須フィールド、ステータスの列挙型 → references/api-endpoints.md。PUT /shipments/{id} の本文は、文書化された OpenAPI スキーマ（エンドポイントの docs.salla.dev/<id>.md ページに記載。salla-docs で検索）と照合して検証し、それに依存する前に修正してください。その際は、salla-api-core のスキーマ読み込み → 構築 → 検証 → 修正 → 再試行のループを使用します。

ゲート：「デモストアで salla_functions action=preview を実行すると、shipment.creating（type: shipment と type: return の両方）に対して有効な Shipment が返り、shipment.cancelling に対して Resp.success() が返ります。また、AWB 番号／追跡情報が注文に表示されていますか？」

---

ステップ 5 — 注文のフルフィルメント（該当する場合）

ステップ 0 で選んだモデルが注文のフルフィルメント（https://docs.salla.dev/423000m0.md）の場合、フローは異なります。`shipment.creating` App Function は作成せず、order.created に反応して運送業者／支店を選び、出荷を割り当てます。これにより、割り当てられた Shipping App の shipment.creating 関数がトリガーされます。https://docs.salla.dev/423002m0.md に従って、スコープ（基本情報、注文、Webhook、配送）とイベント（order.created、shipment.created）を設定します。

割り当てから返品／キャンセルまでの全サイクル → references/fulfillment-cycle.md。

ステップ 6 — テストと公開

テスト： App Testing でデモストアに接続し、新規注文 → 料金リクエスト → ラベル → 追跡 → キャンセル → 返品をシミュレートします。エンドツーエンドのデモストア検証は salla-live-testing が担当します。デモ用／機密情報を含まないデータを使用してください。本番用の配送業者の認証情報、OAuth／ベアラートークン、Webhook 署名シークレット、実際の顧客の個人情報は、サードパーティのキャプチャ／検査ツールに含めないでください。完了したら実際の設定に戻してください。

公開： 配送アプリは公開アプリです（冒頭の注記を参照）→ app_publish を段階的に実行します（open → 各セクションを set → validate で DRAFT を保存します。その後、パートナーが Portal の /publish ページでワンクリック送信します。担当は salla-publication-consistency です）。特定のマーチャント向けに構築した配送業者アプリは type: "private" のアプリです。その場合は、代わりに salla-app-builder → プライベートアプリ を参照してください。sub_category_id は不要です。また、shippings スコープは無効のままです（Salla がアプリを許可リストに追加しない限り、通常のパートナーの場合）。マーチャントパートナーの場合は利用できません。type: "shipping" アプリには、次の 2 つのブロッカーがあります。

• sub_category_id は、sub_categories に含まれる配送サブカテゴリである必要があります （salla_reference action=categories type=shipping）。
• マーチャントの AWB 配送業者オプションに表示するには、Salla によるアプリの有効化が必要です — [email protected] までメールでお問い合わせください（https://docs.salla.dev/1792111m0.md）。

承認されると、アプリは https://apps.salla.sa/en の Shipping に掲載されます。

テストガイド：https://docs.salla.dev/422998m0.md · 公開ガイド：https://docs.salla.dev/422990m0.md

ゲート： 「公開済み — salla_apps action=get に期待するステータスが表示される。」

---

リソース

トピック	リンク
配送の概要（両方のモデル）	https://docs.salla.dev/422988m0.md
配送 API の一覧	https://docs.salla.dev/api-5578809
Salla AWB — はじめに	https://docs.salla.dev/1792089m0.md
AWB — アプリの作成	https://docs.salla.dev/1792111m0.md
AWB — アプリのセットアップ	https://docs.salla.dev/1792112m0.md
AWB 機能 — 配送の作成	https://docs.salla.dev/1792119m0.md
AWB 機能 — 配送のキャンセル	https://docs.salla.dev/1797616m0.md
配送管理 — 作成	https://docs.salla.dev/422995m0.md
配送管理 — セットアップ	https://docs.salla.dev/422996m0.md
配送管理 — アプリのサイクル	https://docs.salla.dev/422994m0.md
配送管理 — テスト	https://docs.salla.dev/422998m0.md
注文のフルフィルメント — 作成	https://docs.salla.dev/423001m0.md
注文のフルフィルメント — セットアップ	https://docs.salla.dev/423002m0.md
注文のフルフィルメント — アプリのサイクル	https://docs.salla.dev/423000m0.md
注文のフルフィルメント — テスト	https://docs.salla.dev/423003m0.md
Postman コレクション	https://www.postman.com/salla-app/workspace/salla-e-commerce-platform/collection/17687195-d700cd60-adf3-4b20-82ee-94851e88bd44
開発者コミュニティ	https://t.me/salladev