VibeFox SMSA Express for PrestaShop — ヘルプ
要件
PrestaShop: 8.0 ～ 9.x。
PHP: 8.0 以降。古いバージョンの PHP ではモジュールはインストールできません。
SMSA Express 料金表: 料金表の料金は、お客様の SMSA アカウントまたは SMSA の営業チームから入手してください。ストアの既定通貨で入力してください。料金表が SAR、AED、その他の通貨の場合は、先に換算してください。
SMSA passKey（リアルタイム料金のみ）: リアルタイム料金は SMSA の Web サービス（SECOM、操作 getShipCharges）を使用します。passKey は依頼に応じて SMSA が発行します。SMSA のアカウントマネージャーに依頼するか、info@smsaexpress.com 宛てにアカウント番号を添えて、SMSA Web サービスへのアクセスを依頼してください。passKey は、SMSA の e コマースポータルの API キーとは異なる場合があります。このサービスには SMSA のテスト（サンドボックス）サーバーはありません。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
1. 管理画面で Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックします。後でモジュール一覧から VibeFox SMSA Express を探し、Configure をクリックすることもできます。
3. VibeFox ライセンスキーを、設定ページ上部のライセンスブロックにある License key に入力し、Activate をクリックします（ライセンスキーを参照）。
4. 料金表に SMSA Express の料金を入力し、Save をクリックします。
5. 任意: Live rates (API) で Live charges を有効にし、SMSA の passKey、発送元の都市と国を入力します。ストアの既定通貨が SAR でない場合は、為替レートも入力します。
インストール時にモジュールは、配送日数の表示テキストを SMSA Express courier とした SMSA Express 配送業者を作成します。配送業者はすべてのゾーンとすべての顧客グループに割り当てられます。ゾーン、顧客グループ、配送日数、ロゴ、サイズ制限は Shipping > Carriers で変更できます。そこで料金を設定しないでください。料金は常にモジュールから取得されます。
設定
すべての設定はモジュールのページにあります: Modules > Module Manager > VibeFox SMSA Express > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。保存するたびに、キャッシュされた SMSA の料金もクリアされます。数値でない値、負の数値、為替レート 0、3 文字でない通貨コード、Minimum weight が Maximum weight より大きい値は、エラーで拒否され、修正するまで何も保存されません。
リアルタイム料金を有効にすると、設定の上に表示される警告で、passKey、発送元の都市、為替レートが未入力であること、または料金表が空であることがわかります。モジュールがストアの重量単位を認識できない場合（この場合、商品の重量は kg として読み取られます）も警告が表示されます。International > Localization（Local units）で kg、g、lb、oz のいずれかを設定してください。
一般
Enable SMSA Express: すべてのゾーンで配送業者を一度に有効化または無効化します。これは Shipping > Carriers の配送業者のステータスと同じスイッチです。
Method title: カートとチェックアウトに表示される配送業者名。既定値: SMSA Express。必須、最大 64 文字。
Tax: 配送業者の税ルール、または No tax。料金（料金表と SMSA の料金）にすでに税が含まれている場合（例: サウジアラビアの付加価値税）は、No tax を選択してください。
リアルタイム料金（API）（任意。SMSA が料金を返さない場合は料金表が使われます）
Live charges: SMSA Express から配送料を取得します。既定値: オフ。
SMSA passKey: SMSA Web サービス（SECOM）のキー。保存後、このフィールドは空になり、Saved — leave empty to keep it と表示されます。変更する場合にのみ新しい値を入力してください。保存済みの passKey を削除するには、Remove the saved passKey にチェックを入れます。ログに "Invalid Passkey" と表示される場合、このサービスはそのキーを受け付けていません。SMSA に Web サービス用の passKey を依頼してください。
Ship-from city: 荷物を発送する都市。SMSA の表記に合わせて入力します（例: Riyadh、Jeddah、Dammam）。空欄にすると、Shop Parameters > Contact > Stores に設定されたショップの都市を使用します。
Ship-from country: 荷物を発送する国。既定ではショップの国です。
Shipment type: SMSA に配送タイプとして送信されます。DLV（既定）は標準配送です。SMSA から別のコードを指定された場合にのみ変更してください。
Currency of SMSA charges: SMSA は料金を通貨コード付きで返します。通常は SAR（既定）です。この通貨およびストアの既定通貨以外の料金は使用されません。
Exchange rate: SMSA の通貨 1 単位に相当する、ストアの既定通貨での価格（例: 0.27）。両方の通貨が同じ場合は不要です。設定しないと、別の通貨の料金は使用されず、料金表が適用されます。小数点とカンマのどちらも小数点区切りとして使えます。
料金（ストアの既定通貨での SMSA Express 料金表。リアルタイム料金がオフの場合に使用され、SMSA が料金を返さない場合の代替としても使用されます）
Price table: 配送先の国ごとに 1 行。Add country をクリックすると行が追加され、ゴミ箱アイコンで削除できます。* Default (all other countries) の行は、独自の行がない国に適用されます。各行には基本料金と重量の列があります: XS は 1 kg まで、S は 2 kg まで、M は 3 kg まで、L は 5 kg まで、XL は 5 kg 超。重量の列が空または 0 の場合は基本料金が使われます。基本料金が 0 の場合は送料無料です。料金が 1 つもない行は保存されません。1 つの国に 2 行ある場合は、最初の行が使われます。"9.99" と "9,99" のどちらも受け付けられます。
Price for countries not in the table: 料金表に配送先の国の行がない場合（* の行もない場合）、またはその行にこの重量の料金がない場合に使われます。この場合に配送業者を非表示にするには、空欄のままにします。
Price applies: 料金の計算方法。
商品の重量は、ストアの重量単位からキログラムに換算されます。
条件
Minimum weight: カートの重量がこの値より軽い場合、配送業者を非表示にします（kg）。0 は制限なしを意味します。
Maximum weight: カートの重量がこの値より重い場合、配送業者を非表示にします（kg）。既定値: 30。0 または空欄は制限なしを意味します。
Minimum order amount: カートの小計（割引後、税抜き）がこの金額に達した場合にのみ配送業者を表示します。空欄にすると常に表示されます。
Free shipping from: SMSA Express の配送が無料になるカートの小計（割引後、税抜き）。カートがこの金額に達すると、料金は 0 になり、SMSA へのリクエストは送られません。空欄にすると、送料無料は提供されません。
配送ゾーンを使わない場合の提供
通常は、Shipping > Carriers で割り当てられたゾーンで配送業者が提供されます。
Ignore shipping zones: 一致するゾーンに関係なく、以下の国に SMSA Express を提供します。有効にしている間は、後から作成されたものを含むすべてのゾーンに配送業者が追加されます。無効にすると、この方法で追加されたゾーンは再び削除されます。
Countries: このモードでの配送先の国。空欄にすると、ショップで有効なすべての国が使われます。このフィールドは Ignore shipping zones が有効な場合にのみ使われます。
詳細設定
Debug log: 料金計算を、モジュールフォルダー内の logs/vfd_smsa_debug.log.php に記録します。このファイルは Web から開くことはできません。購入者の住所やキーは記録されません。リアルタイム料金のエラーは、このオプションがオフでも常に記録されます。作業が終わったらログをオフにしてください。
Log: デバッグログのサイズと最新のエントリを表示します。Clear log をクリックすると空になります。
Remove data on uninstall: オンの場合、モジュールをアンインストールすると、SMSA Express の設定、配送業者、ログが削除されます。オフの場合は、再インストールに備えてすべてが保持されます。キャッシュされた料金は常に削除されます。
チェックアウト時の動作
配送ステップで、PrestaShop はモジュールに SMSA Express の料金を問い合わせます。対象になるのは実物の商品のみです。バーチャル商品は重量に加算されず、注文金額にも含まれません。モジュールはまず条件を確認します: Ignore shipping zones の国（オンの場合）、カートの重量、最低注文金額。送料無料が適用される場合は、料金が 0 となり、SMSA へのリクエストは送られません。
リアルタイム料金をオンにすると、モジュールは SMSA に、発送元の都市と国、購入者の都市と国、配送タイプ、kg 単位の荷物の重量、代金引換金額 0 を送信します。SMSA は料金とその通貨を返します。モジュールはそれをストアの既定通貨に換算し、料金は購入者のカートの通貨で表示されます。リアルタイム料金は、購入者が都市を含む配送先住所を入力した後にのみ問い合わせられます。
各料金は 1 時間キャッシュされるため、同じカートでも新たなリクエストは発生しません。失敗したリクエストは 5 分間キャッシュされます。タイムアウトまたはサーバーエラーの後は、2 分間 SMSA に問い合わせません。キーが拒否された後は、5 分間問い合わせません。これにより、チェックアウトが更新のたびに障害中のサービスを待つことはありません。リクエストのタイムアウトは 12 秒です。
SMSA から使用可能な料金が返されない場合（passKey がない、まだ都市が入力されていない、商品の重量がない、キーが無効、タイムアウト、エラー、都市へのサービスがない、通貨が不明など）は、料金表が使われます。料金表と Price for countries not in the table で料金が決まらない場合は、配送業者が非表示になります。購入者にエラーが表示されることはありません。理由はログに記録されます。
配送業者に注文が入った後に Shipping > Carriers で配送業者を編集すると、PrestaShop はそれを配送業者の新しいバージョンとして保存します。モジュールは新しいバージョンに自動的に追従します。
このモジュールが計算するのは配送料のみです。SMSA の発送データ作成、AWB ラベルの印刷、返品処理、荷物追跡は行いません。代金引換とその手数料は、リアルタイム料金には含まれません。SMSA の小売拠点を選択する機能はありません。配送業者は玄関先までの配送です。
ライセンスキー
本モジュールは vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox SMSA Express は、Modules > Module Manager > VibeFox SMSA Express > Configure ページの、設定より上にある最初のブロックです。キーを License key に入力し、Activate をクリックしてください。その後、ブロックにはマスクされたキー、ステータス（ライセンスの有効期限日やお使いのドメインなど）、そして次のボタンが表示されます：ステータスを再確認する Check now、別のキーを入力する Change key、このショップからキーを削除する Remove key。その下には Product: presta-shipping-smsa-express の行と、vibefox.net のアカウントを開くリンク Manage licenses and domains in your account があります。キーを変更できるのは、モジュールの Configure 権限を持つスタッフのみです。ブロックの文言は管理画面の言語に従います（英語とロシア語が含まれます）。
キーが受け付けられない場合、ブロックに理由が表示されます。例: Key not found、This key belongs to another product、Domain limit reached、または日付付きの License expired on。ショップのアドレスを変更した後、またはアカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、モジュールは最後に確認できたステータスで動作を続けます。
1 つのキーは 1 つのドメインで使用できます。メインショップのドメインで、マルチストア構成でも同様です。ショップからキーを削除しても、ドメインの枠は解放されません。枠は vibefox.net のアカウントで解放してください。
有効なキーがない場合、チェックアウトで SMSA Express 配送業者は購入者に表示されず、送料も計算されません。PrestaShop のストアフロントは、管理画面にログインしていることを認識しないため、配送業者はあなたにも表示されません。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブに通知が表示されます。既存の注文には影響しません。
ライセンスの期限が切れても、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。管理画面で作業している間、ステータスは自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスのステータスは常に削除されます。
トラブルシューティング
チェックアウトに SMSA Express が表示されない: ライセンスが有効で、Enable SMSA Express がオンになっていることを確認してください。Shipping > Carriers で、配送業者が購入者の国のゾーンと顧客グループを対象にしていることを確認してください（または Ignore shipping zones がオンで、その国が許可されていること）。重量の制限と Minimum order amount を確認してください。国または * に料金があること、または Price for countries not in the table が設定されていることを確認してください。また、商品ページで商品が特定の配送業者に限定されている場合もあります。
購入者に SMSA の料金ではなく料金表の料金が表示される: SMSA は購入者の都市を必要とするため、入力されるまでは料金表の料金が表示されます。SMSA が応答しない、キーや都市を拒否する、または為替レートのない通貨で料金を返す場合も、料金表が使われます。理由はモジュールのページにある Log フィールドで確認してください。
ログに "Invalid Passkey" と表示される: SMSA の Web サービスがこのキーを受け付けていません。SMSA に Web サービス用の passKey を依頼してください。
購入者の都市が受け付けられない: SMSA は独自の都市表記を使用します。配送先住所の都市と Ship-from city を確認してください。
設定が保存されず、エラーが表示される: 数値のフィールドにテキストや負の値が入っている、為替レートが 0、通貨コードが 3 文字でない、または Minimum weight が Maximum weight より大きいことが原因です。メッセージに示された値を修正して、もう一度 Save をクリックしてください。
配送料に税が二重にかかる: 料金表または SMSA の料金にすでに付加価値税が含まれている可能性があります。Tax を No tax に設定してください。
変更後に料金が古いように見える: モジュールのページで Save をクリックしてください。キャッシュされた SMSA の料金がクリアされます。
ページに SMSA Express 配送業者が見つからないと表示される: 配送業者が Shipping > Carriers で削除されています。Modules > Module Manager でモジュールをリセットすると、再作成されます。
アンインストール
Modules > Module Manager に移動し、VibeFox SMSA Express の横のメニューを開いて Uninstall を選びます。ライセンスキーとライセンスのステータスは常に削除されます。キャッシュされた料金は常に削除されます。Remove data on uninstall がオンの場合、配送業者は削除され（注文は履歴を保持します）、設定とログも削除されます。オフの場合、配送業者は無効化されるだけで、すべての設定が保持されます。モジュールを再インストールするか、Reset を実行すると、配送業者は以前のステータスに戻ります。
SMSA Express は、それぞれの所有者の商標です。このモジュールは SMSA Express とは提携しておらず、SMSA Express による推奨も受けていません。