VibeFox SMSA Express for OpenCart — ヘルプ
動作要件
OpenCart：3.0.x（3.0.5.0 で検証済み）または 4.0.2 以降（4.1.0.3 で検証済み）。
PHP：8.0 以降。
SMSA Express 料金表：料金表の価格は、SMSA アカウントまたは SMSA の営業チームから入手してください。ストアの基準通貨で入力してください。料金表が SAR、AED、またはその他の通貨の場合は、先に換算してください。
SMSA passKey（リアルタイム送料の場合のみ）：リアルタイムの送料は SMSA ウェブサービス（SECOM、操作 getShipCharges）を使用します。SMSA は依頼に応じて passKey を発行します。SMSA のアカウントマネージャーに依頼するか、info@smsaexpress.com までご連絡ください。passKey は SMSA の e コマースポータルの API キーとは異なる場合があります。SMSA はこのサービス用のテスト（サンドボックス）サーバーを提供していません。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。お使いのコンピューターで解凍してください。含まれるのは README.txt、OpenCart 3 用パッケージ vfd_smsa_express-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ vfd_smsa_express.ocmod.zip です。お使いの OpenCart バージョン用のパッケージだけをインストールしてください。ライセンスキーは両方のバージョンで同じです。
OpenCart 3
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_smsa_express-oc3-(version).ocmod.zip を選択します。この拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。Installer を使用する代わりに、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。
2. Extensions > Extensions に移動し、拡張機能の種類として Shipping を選択します。VibeFox SMSA Express を見つけて、Install（緑色の + ボタン）をクリックします。
3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。
4. Edit ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。
5. 料金表に SMSA Express の料金を入力します。
6. 任意：Live rates (API) の下で Live charges をオンにし、SMSA passKey、発送元の都市と国を入力します。ストアの基準通貨が SAR でない場合は、為替レートも入力します。
7. Enable SMSA Express をオンにして、Save をクリックします。
OpenCart 4
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_smsa_express.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変更したパッケージは動作しません。
2. 同じページのインストール済み拡張機能の一覧にパッケージが表示されます。その横の Install（緑色の + ボタン）をクリックします。
3. Extensions > Extensions に移動し、拡張機能の種類として Shipping を選択します。VibeFox SMSA Express を見つけて、Install（緑色の + ボタン）、次に Edit（鉛筆のボタン）をクリックします。
4. ライセンスキーと設定は、OpenCart 3 の手順 4 から 7 と同じように入力します。設定ページとそのフィールドは両方のバージョンで同じです。
インストール後は、Enable SMSA Express をオンにして保存するまで、この方法は無効のままです。アンインストール後に拡張機能を再インストールした場合は、保持されていた SMSA Express の設定が再び使用されます。
設定
すべての設定は拡張機能のページにあります：Extensions > Extensions > Shipping > VibeFox SMSA Express > Edit。セクションは左側に一覧表示されます。Save ボタンを 1 回押すと、ページを再読み込みせずにページ全体が保存されます。保存するたびに、キャッシュされた SMSA の送料も消去されます。無効な方法のタイトル、数値ではない値、負の数、為替レート 0、3 文字ではない通貨コード、料金表の誤った価格、Maximum weight (kg) より大きい Minimum weight (kg)、整数ではない並び順は、エラーとして拒否され、修正するまで何も保存されません。この拡張機能を変更する権限を持つ管理者ユーザーのみが設定を保存できます。
リアルタイムの送料が有効な場合、設定の上の警告は、passKey、発送元の都市、為替レートの未入力、または空の料金表を知らせます。ストアに kg の重量クラスがなく、そのデフォルトの重量単位が拡張機能で認識されない場合にも警告が表示されます（その場合、商品の重量は kg として読み取られます）。System > Localisation > Weight Classes で kg の重量クラスを追加してください。
一般
設定はすべてのジオゾーンに適用されます。Conditions でジオゾーンに限定するか、Ignore shipping zones で国のリストに限定できます。
Enable SMSA Express：チェックアウト時に SMSA Express を表示または非表示にします。デフォルト：オフ。
Method title：カートとチェックアウトでお客様に表示される配送方法の名前。デフォルト：SMSA Express。必須。最大 64 文字で、文字 < > ; = # { } は使用できません。
Sort order：チェックアウト時の配送方法の中での SMSA Express の位置。整数です。
リアルタイム料金（API）（任意。SMSA が料金を返さない場合は料金表を使用します）
Live charges：SMSA Express から配送料金を取得します。オフの場合、チェックアウト中に SMSA へは何も送信されません。デフォルト：オフ。
SMSA passKey：SMSA ウェブサービス（SECOM）のキーです。保存後、このフィールドは空になり、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。Remove the saved passKey にチェックを入れると削除されます。ログに "Invalid Passkey" と表示される場合、このサービスではそのキーは受け付けられません。SMSA にウェブサービス用の passKey を請求してください。
Ship-from city：荷物の発送元となる都市。SMSA の表記に合わせて入力します（例：Riyadh、Jeddah、Dammam）。リアルタイム料金には必須です。OpenCart にはストアの都市がないため、ストアの住所から取得されることはありません。
Ship-from country：荷物の発送元の国。最初の選択肢 Store country は、System > Settings > Store > Local で設定されたストアの国を使用します。これがデフォルトです。
Shipment type：出荷の種類として SMSA に送信されます。DLV（デフォルト）は標準配送です。SMSA から別のコードを指定された場合にのみ変更してください。
Currency of SMSA charges：SMSA が料金を返す通貨の 3 文字のコード。通常は SAR（デフォルト）です。この通貨またはストアの基準通貨以外の通貨による料金は使用されません。
Exchange rate：SMSA 通貨 1 単位のストアの基準通貨での価格（例：0.27）。両方の通貨が同じ場合は不要です。設定しない場合、他の通貨による料金は使用されず、料金表が適用されます。
料金（ストアの基準通貨による SMSA Express の料金表です。リアルタイム料金がオフのときに使用され、SMSA が料金を返さないときの予備としても使用されます）
Price table：目的地の国ごとに 1 行です。Add country をクリックすると行を追加できます。* All other countries の行は、独自の行がない国に適用されます。各行には Base 料金と重量列があります：XS ≤1 kg、S ≤2 kg、M ≤3 kg、L ≤5 kg、XL >5 kg。重量列が空または 0 の場合は基本料金が使用されます。基本料金が 0 の場合は送料無料を意味します。料金が 1 つもない行は保存されません。ある国に 2 行ある場合は、最初の行が使用されます。"9.99" と "9,99" のどちらも受け付けられます。
Price for countries not in the table：表に目的地の国の行がない場合（* の行もない場合）、またはその行にこの重量の料金がない場合に使用されます。その場合に方法を非表示にするには空欄のままにします。
Price applies：料金の計算方法。
商品の重量は、OpenCart の重量クラスからキログラムに換算されます。
条件
Minimum weight (kg)：カートがこの重量より軽い場合、この方法を非表示にします。0 は制限なし（デフォルト）を意味します。
Maximum weight (kg)：カートがこの重量より重い場合、この方法を非表示にします。デフォルト：30。0 または空欄は制限なしを意味します。
Minimum order amount：配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額に達した場合にのみ、この方法を表示します。常に表示するには空欄のままにします。
Free shipping from：配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額に達すると、SMSA Express の送料が無料になります。カートがこの金額に達すると、料金は 0 になり、SMSA へのリクエストは送信されません。送料無料を提供しない場合は空欄のままにします。
Tax class：送料の税クラス、または No tax（デフォルト）。料金（料金表と SMSA の送料）にすでに税金（サウジアラビアの付加価値税など）が含まれている場合は、No tax を選択してください。
Geo zone：この地域の住所に対してのみ SMSA Express を提供します。All zones（デフォルト）は制限なしを意味します。Ignore shipping zones がオンの間は確認されません。ジオゾーンは System > Localisation > Geo Zones で管理します。
配送ゾーンを使用しない場合の提供条件
通常、この方法は Conditions で選択したジオゾーンの住所に対して提供されます。
Ignore shipping zones：ジオゾーンに関係なく、下記の国に対して SMSA Express を提供します。オフの場合は、ジオゾーンによって決まり、国のリストは使用されません。
Countries：このモードの配送先の国。空欄のままにすると、ストアで有効になっているすべての国が使用されます。このフィールドは Ignore shipping zones がオンの場合にのみ使用されます。
詳細設定
Debug log：料金計算を storage/logs/vfd_smsa_debug.log.php に記録します。このファイルはウェブから読み取ることはできません。お客様の住所とキーは記録されません。このオプションがオフでも、リアルタイム料金のエラーは常に記録されます。作業が終わったらログをオフにしてください。ファイルが 5 MB に達すると、vfd_smsa_debug.old.log.php に移動され、新しいログが開始されます。
Log：デバッグログのサイズと最新のエントリを表示します。Clear log をクリックすると空にできます。
Remove data on uninstall：オンにすると、拡張機能をアンインストールした際に SMSA Express の設定とデバッグログが削除されます。オフ（デフォルト）の場合は、再インストール用に設定が保持されます。キャッシュされた送料は常に削除されます。
インポート / エクスポート
Export：Download JSON をクリックすると、設定を JSON ファイルとして保存します。passKey はエクスポートされません。
Import：以前にエクスポートした JSON を貼り付け、Import をクリックすると、設定が復元されます（例：別のストアで）。値は通常の保存と同じように確認されます。保存済みの passKey は保持されます。
チェックアウト時の動作
OpenCart が配送方法を表示するとき、拡張機能に SMSA Express の料金を問い合わせます。Geo zone が設定されていて（かつ Ignore shipping zones がオフの）、住所がその範囲外の場合、SMSA Express は提供されません。Requires Shipping が Yes に設定された商品のみが対象になります。それ以外の商品は重量に加算されず、注文金額にも含まれません。その後、拡張機能は条件を確認します。Ignore shipping zones の国（オンの場合）、カートの重量、最低注文金額です。ギフト券、ポイント、ストアクレジットは考慮されません。送料無料が適用される場合は、料金は 0 になり、SMSA へのリクエストは送信されません。
リアルタイム料金がオンの場合、拡張機能は SMSA に、発送元の都市と国、お客様の都市と国、出荷の種類、kg 単位の荷物の重量、金額 0 の代金引換額を送信します。SMSA は料金とその通貨を返します。拡張機能はそれをストアの基準通貨に換算し、小数点以下の桁数に丸めます。その後、料金は選択された Tax class の税金を加えて、お客様の通貨で表示されます。リアルタイム料金は、お客様が都市を含む配送先住所を入力した後にのみ問い合わせられます。
各料金は 1 時間キャッシュされるため、同じカートで新たなリクエストが発生することはありません。失敗したリクエストは 5 分間キャッシュされます。タイムアウトやサーバーエラーの後、2 分間は SMSA に問い合わせません。キーが拒否された後は 5 分間問い合わせません。これにより、チェックアウトが更新のたびに失敗しているサービスを待つことはありません。リクエストのタイムアウトは 12 秒です。
SMSA が使用可能な料金を返さない場合（passKey がない、都市が未入力、キーが無効、タイムアウト、エラー、その都市へのサービスがない、通貨が不明など）は、いつでも料金表が使用されます。料金表と Price for countries not in the table のどちらでも価格が得られない場合は、この方法は非表示になります。お客様にエラーが表示されることはありません。理由はログに記録されます。
この拡張機能は配送料金の計算のみを行います。SMSA の出荷データの作成、AWB ラベルの印刷、返品の処理、荷物の追跡は行いません。代金引換とその手数料はリアルタイム料金には含まれません。SMSA の取扱店を選択する機能はありません。この方法は戸別配送です。注文に何かを追加することはありません。注文には、他の OpenCart の配送方法と同様に、方法のタイトルと送料が表示されます。
OpenCart 4 では、お客様はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options ウィンドウで SMSA Express を選択します。この方法は OpenCart 3 と同じように動作します。
ライセンスキー
この拡張機能は、vibefox.net で入手した VibeFox ライセンスキーで動作します。License — VibeFox SMSA Express ライセンスブロックは、Extensions > Extensions > Shipping > VibeFox SMSA Express > Edit ページで設定の上にある最初のブロックです。キーを License key に貼り付けて Activate をクリックします。その後、ブロックにはキーがマスクされた形で表示され、ステータス（例：ライセンスの有効期限日とお使いのドメイン）と、次のボタンが表示されます：Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）。その下には Product: opencart-shipping-smsa-express の行と、vibefox.net アカウントを開くリンク Manage licenses and domains in your account があります。キーを変更できるのは、この拡張機能の Modify 権限を持つ管理者ユーザーだけです。ブロックの文言は管理画面の言語に従います（英語とロシア語が含まれます）。
キーが受け付けられない場合、ブロックにはその理由が表示されます。例：Key not found、This key belongs to another product、Domain limit reached、または日付付きの License expired on。ストアの住所を変更した後、またはアカウントでドメイン枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、拡張機能は最後に確認できたステータスで動作を続けます。
1 つのキーは 1 つのドメインで使用できます。OpenCart の設定にあるストアの住所です。ストアからキーを削除しても、ドメイン枠は解放されません。vibefox.net アカウントで枠を解放してください。
有効なキーがない場合、SMSA Express はチェックアウトでお客様に表示されず、料金も計算されません。同じブラウザで管理画面にログインしている管理者ユーザーには、(unlicensed — visible to admins only) と表示された状態で、ストアにこの方法が引き続き表示されます。そのため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 ではこのプレビューは利用できません。ストアは管理画面へのログインを認識できないため、有効なキーがない場合は全員に対してこの方法が非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると、7 日間非表示になります。既存の注文には影響しません。
ライセンスの期限が切れても、拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスは自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日に 1 回、その後は週に 1 回です。cron ジョブは必要ありません。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは必ず削除されます。
トラブルシューティング
チェックアウトに SMSA Express が表示されない：ライセンスが有効であること、Enable SMSA Express がオンであることを確認してください。Geo zone（または Ignore shipping zones がオンの場合は Countries）、重量制限、Minimum order amount を確認してください。その国または * に料金が設定されているか、Price for countries not in the table が設定されているかを確認してください。商品の Requires Shipping が Yes に設定されているか確認してください。
お客様に SMSA の送料ではなく料金表の価格が表示される：SMSA にはお客様の都市が必要なため、入力されるまでは料金表の価格が表示されます。料金表は、SMSA が応答しない、キーや都市を拒否する、または為替レートのない通貨で料金を返す場合にも使用されます。理由は拡張機能ページの Log フィールドで確認してください。
ログに "Invalid Passkey" と表示される：そのキーは SMSA ウェブサービスに受け付けられていません。SMSA にウェブサービス用の passKey を請求してください。
お客様の都市が受け付けられない：SMSA は独自の都市の表記を求めます。配送先住所の都市と Ship-from city を確認してください。
設定が保存されず、エラーが表示される：数値フィールドにテキストまたは負の値が含まれている、為替レートが 0 である、通貨コードが 3 文字ではない、または Minimum weight (kg) が Maximum weight (kg) より大きい。メッセージに示された値を修正し、もう一度 Save をクリックしてください。
送料に税金が二重にかかる：料金表または SMSA の送料にすでに付加価値税が含まれている可能性があります。Tax class を No tax に設定してください。
変更後に料金が古く見える：拡張機能ページで Save をクリックしてください。これにより、キャッシュされた SMSA の送料が消去されます。
ページに "Warning: You do not have permission to modify VibeFox SMSA Express!" と表示される：管理者のユーザーグループが設定を閲覧のみできる可能性があります。System > Users > User Groups で、そのグループに extension/shipping/vfd_smsa_express（OpenCart 3）または extension/vfd_smsa_express/shipping/vfd_smsa_express（OpenCart 4）の変更権限を付与してください。
開発者向け：SMSA ウェブサービスのアドレスは、設定 vfd_smsa_api_url（テスト用）で置き換えられます。設定ページにはこの項目のフィールドはありません。
アンインストール
Extensions > Extensions に移動し、種類 Shipping を選択して、VibeFox SMSA Express の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは必ず削除されます。OpenCart は常に Enable SMSA Express、Sort order、Tax class、Geo zone をリセットします。キャッシュされた送料は常に削除されます。Remove data on uninstall がオンの場合は、SMSA Express の設定とデバッグログも削除されます。オフの場合は、その他の設定が保持され、拡張機能を再インストールしたときに再び使用されます。既存の注文は、配送方法と送料を保持します。
OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧で VibeFox SMSA Express の横にある Uninstall（オレンジ色の − ボタン）をクリックしてから、Delete（赤いごみ箱のボタン）をクリックして、アップロードしたパッケージを削除します。
SMSA Express は、その所有者の商標です。この拡張機能は SMSA Express と提携しておらず、SMSA Express による推奨も受けていません。