VibeFox iMile for OpenCart — ヘルプ
要件
OpenCart：3.0.x（3.0.5.0 で検証済み）または 4.0.2 以降（4.1.0.3 で検証済み）。
PHP：8.0 以降。
iMile の料金：iMile の営業チームと合意した料金。料金表に、ストアの初期通貨で入力します。
iMile API アカウント（リアルタイム見積もりの場合のみ）：リアルタイム見積もりでは、iMile OpenAPI の「Estimated order delivery costs」を使用します。Customer ID と Secret key（Customer ID とともに iMile が発行する API キー）が必要です。テスト用のクライアントは、iMile 開発者ポータル（developer.imile.com）で登録してください。本番用のキーは、iMile のアカウントマネージャーから入手します。料金表のみを使用する場合は、API キーは不要です。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。コンピューターで解凍してください。README.txt、OpenCart 3 用のパッケージ vfd_imile-oc3-(version).ocmod.zip、OpenCart 4 用のパッケージ vfd_imile.ocmod.zip が含まれています。お使いの OpenCart のバージョンに対応するパッケージのみをインストールしてください。ライセンスキーは両方のバージョンで同じです。
OpenCart 3
1. 管理画面で Extensions > Installer に進み、Upload をクリックして、ファイル vfd_imile-oc3-(version).ocmod.zip を選択します。本拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。インストーラーを使う代わりに、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。
2. Extensions > Extensions に進み、拡張機能の種類で Shipping を選択します。VibeFox iMile を見つけて、Install（緑色の + ボタン）をクリックします。
3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。
4. Edit ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーの項を参照）。
5. Price table に iMile の料金を入力します。必要に応じて Live rates (API) のセクションに入力し、Live estimate をオンにします（設定の項を参照）。Enable iMile をオンにして、Save をクリックします。
OpenCart 4
1. 管理画面で Extensions > Installer に進み、Upload をクリックして、ファイル vfd_imile.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から読み取るため、名前を変更したパッケージは動作しません。
2. インストール済みの拡張機能の一覧に、このパッケージが同じページに表示されます。その横の Install（緑色の + ボタン）をクリックします。
3. Extensions > Extensions に進み、拡張機能の種類で Shipping を選択します。VibeFox iMile を見つけて、Install（緑色の + ボタン）をクリックしてから、Edit（鉛筆のボタン）をクリックします。
4. ライセンスキーと設定は、OpenCart 3 の手順 4 と 5 と同じように入力します。設定ページとそのフィールドは、両方のバージョンで同じです。
インストール後は、Enable iMile をオンにして保存するまで、この配送方法はオフのままです。拡張機能をアンインストールした後に再インストールすると、保持されていた iMile の設定が再び使用されます。
設定
すべての設定は拡張機能のページにあります：Extensions > Extensions > Shipping > VibeFox iMile > Edit。セクションは左側に一覧表示されます。Save ボタン 1 つで、ページを再読み込みせずにページ全体を保存できます。保存するたびに、キャッシュされた iMile の見積もりとアクセストークンも消去されます。この拡張機能の変更権限を持つ管理者ユーザーのみが設定を保存できます。
保存時、拡張機能は次の内容を確認します：Method title が有効であること（最大 64 文字、< > ; = # { } の文字は使用不可）、料金、金額、重量のフィールドが 0 以上の数値であること、Minimum weight (kg) が Maximum weight (kg) を超えないこと、Sort order が整数であること、税クラスとジオゾーンが存在すること。これらを満たさない場合、エラーが表示され、何も保存されません。
Live estimate がオンで、かつ正しく動作できない場合、設定の上部に警告が表示されます（保存後にも再表示されます）。Customer ID または Secret key が空の場合、出荷元の都市または国が未入力の場合（またはその国が iMile の市場ではない場合）、為替レートがない場合、料金表が空で他の国の料金がない場合などです。ストアに kg 単位の重量クラスがなく、デフォルトの重量クラスの単位を拡張機能が認識できない場合にも警告が表示されます。この場合、商品の重量はキログラムとして扱われるため、System > Localisation > Weight Classes で kg の重量クラスを追加してください。
一般
設定はすべてのジオゾーンに適用されます。Conditions でジオゾーンに限定することも、Countries で Ignore shipping zones をオンにして国のリストに限定することもできます。
Enable iMile：チェックアウトで iMile を表示するかどうかを切り替えます。初期値：オフ。
Method title：カートとチェックアウトで購入者に表示される配送方法名。初期値：iMile。必須です。
Sort order：チェックアウトで配送方法の中に表示される iMile の順序。整数です。
リアルタイム料金 (API)（任意）
iMile から見積もりが返されない場合（キーがない、都市がまだ入力されていない、エラー、タイムアウト、為替レートがない）、料金表が使用されます。
Live estimate：オンにすると、iMile から配送料金を取得します。初期値：オフ。リアルタイム見積もりがオフの場合、チェックアウト中に iMile へは何も送信されません。
Environment：Production (openapi.imile.com)（初期値）または Test (test-openapi.52imile.cn)。テストキーはテストサーバーでのみ動作し、テスト用の料金を返します。
Customer ID：iMile が発行するクライアントコード（customerId）。例：C2102192601。消去すると、保存された Secret key も消去されます。
Secret key：Customer ID とともに iMile が発行するシークレットキー（API キー）。リクエストに署名します。保存後、このフィールドは空欄のまま Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。
Signature：リクエストの署名方法。
Ship-from country：出荷元の国。最初の選択肢 Store country は、ストアの国を使用します。一覧には、拡張機能が iMile の国コードを持つ国のみが含まれます。
Ship-from city：荷物を発送する都市。iMile の都市リストと同じ綴りで入力します（例：Dubai、Riyadh）。リアルタイム見積もりには必須です。OpenCart にはストアの都市がないため、この欄がないと料金表のみが使われます。
Ship-from province：任意。例：Dubai、Riyadh Province。
iMile service：iMile に送信される注文の種類：Delivery order (100)（初期値）または Express order (1100)。Express は、お使いのアカウントと国で有効になっている必要があります。
Goods category：iMile に送信される商品の種類：Normal goods（初期値）、Sensitive (cosmetics, liquids...)、With battery、Batteries / power banks、Documents、または Parcel。
Exchange rates：iMile は配送先の国の通貨で見積もります。通貨ごとに 1 行を入力し、1 単位のストア初期通貨での価格を書いてください。例："AED = 0.25" や "SAR = 0.24"。ストア自身の通貨にはレートは不要です。レートがない場合、その通貨の見積もりは使われず、代わりに料金表が使用されます。同じレートは、iMile に申告するカートの金額の換算にも使われます。
料金（リアルタイム見積もりがオフの場合に使用され、iMile から見積もりが返されない場合のフォールバックとしても使われます）
iMile の料金は、税抜きでストアの初期通貨で入力します。AED、SAR、またはほかの通貨の場合は、先に換算してください。
Price table：配送先の国ごとに 1 行あります。Add country をクリックすると行を追加し、× ボタンで削除できます。独自の行がないすべての国に適用する行には、* All other countries を選択します。各行には Base price と、任意の重量列があります：XS ≤1 kg、S ≤2 kg、M ≤3 kg、L ≤5 kg、XL >5 kg。空欄（または 0）の重量列は基本料金を使用します。基本料金が 0 の場合、その国への配送は無料です。"9.99" と "9,99" のどちらの形式も受け付けられます。
Price for countries not in the table：ストアの初期通貨での料金。表に配送先の国の行がない場合（かつ * の行もない場合）、または行にその重量の料金がない場合に使用されます。その場合に配送方法を非表示にするには、空欄のままにします。
Price applies：料金の請求方法。
同じ選択肢はリアルタイム見積もりにも適用されます。注文ごとの場合は、カート全体を 1 つの荷物として送信します。商品ごとの場合は、異なる荷物ごとに見積もりを求め、個数を掛けます。カートに 5 種類を超える異なる荷物がある場合は、料金表が使われます。
商品の重量は、OpenCart の重量クラスからキログラムに、サイズは長さの単位からセンチメートルに変換されます。
条件
Minimum weight (kg)：カートの重量がこの値未満の場合、その方法を非表示にします。0 は制限なし（初期値）を意味します。
Maximum weight (kg)：カートの重量がこの値を超える場合、その方法を非表示にします。初期値：30。0 は制限なしを意味します。空欄の場合、30 kg が使用されます。
Minimum order amount：配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額に達した場合にのみ、その方法を表示します。常に表示する場合は空欄のままにします。
Free shipping from：配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額に達した場合、iMile の配送は無料です。送料無料を提供しない場合は、空欄のままにします。
Tax class：配送料の税クラス、または No tax（初期値）。料金表の料金と iMile の見積もりに付加価値税がすでに含まれている場合は、No tax を選択してください。
Geo zone：この地域の住所に対してのみ iMile を提供します。All zones（初期値）は制限なしを意味します。Ignore shipping zones がオンの場合、ジオゾーンは確認されません。ジオゾーンは System > Localisation > Geo Zones で管理されます。
国
Ignore shipping zones：オンの場合、Geo zone は確認されず、下に記載された国に対して iMile が提供されます。オフ（初期値）の場合は、Geo zone のみが適用されます。
Countries：配送を許可する配送先の国。空欄にすると、ストアで有効なすべての国が許可されます。このフィールドは Ignore shipping zones がオンの場合にのみ使用されます。
詳細設定
Debug log：料金の計算を storage/logs/vfd_imile_debug.log.php（OpenCart 4 では system/storage/logs/vfd_imile_debug.log.php）に書き込みます。このファイルはウェブから読み取ることはできません。キーや購入者の住所は記録されません。失敗した iMile のリクエストは、デバッグログがオフでも常に記録されます。作業が終わったらログをオフにしてください。ファイルが 5 MB に達すると、vfd_imile_debug.old.log.php に移動され、新しいログが開始されます。
Log：デバッグログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログを空にできます。
Remove data on uninstall：オンの場合、拡張機能をアンインストールすると、iMile の設定とログが削除されます。オフ（初期値）の場合、設定は再インストール用に保持されます。キャッシュされた見積もりとアクセストークンは常に削除されます。
インポート / エクスポート
Export：Download JSON をクリックすると、設定を JSON ファイルとして保存します。Secret key はエクスポートされません。
Import：以前にエクスポートした JSON を貼り付けて Import をクリックすると、別のストアなどで設定を復元します。値は通常の保存と同じ方法で確認されます。保存済みの Secret key は保持されます。
チェックアウトでの動作
OpenCart が配送方法を表示するとき、拡張機能に iMile の料金を問い合わせます。Geo zone が設定されていて、Ignore shipping zones がオフであり、住所がジオゾーンの外にある場合、iMile は提供されません。Requires Shipping が Yes に設定された商品のみがカウントされます。それ以外の商品は重量に加算されず、注文金額にも含まれません。その後、拡張機能は条件を確認します：許可された国（Ignore shipping zones がオンの場合）、カートの重量、最低注文金額。注文金額は、配送が必要な商品のクーポン割引後、税抜きの価格です。ギフト券、ポイント、ストアのクレジットは考慮されません。送料無料が適用される場合、料金は 0 となり、iMile へのリクエストは送信されません。
リアルタイム見積もりがオンの場合、拡張機能は iMile に、出荷元の国・州・都市、配送先の国・地域・都市・郵便番号、キログラム単位のカートの重量、立方センチメートル単位のサイズ（商品の寸法から算出）、カートの金額、iMile のサービス、商品カテゴリーを送信します。見積もりは常に前払いとして請求され、代金引換の手数料は含まれません。リアルタイム見積もりは、購入者が都市を含む配送先住所を入力した後、かつカート内のすべての商品に重量がある場合にのみ請求されます。
各応答は 1 時間キャッシュされます。失敗したリクエストは 5 分間キャッシュされます。タイムアウトまたはサーバーエラーの後は 2 分間、キーが拒否された後は 5 分間、iMile に問い合わせません。これにより、チェックアウトが再読み込みのたびに iMile を待つことを防ぎます。API のタイムアウトは 12 秒です。期限切れのアクセストークンは自動的に更新されます。
見積もりは、設定した為替レートでストアの初期通貨に換算されます。iMile から使用可能な見積もりが返されない場合（キー未設定、都市がまだ入力されていない、不明な都市、エラー、タイムアウト、為替レートなし）、購入者にエラーは表示されず、料金表の料金が使用されます。料金表にも料金がない場合、配送方法は非表示になります。理由はログに記録されます。料金は、ストアの初期通貨で計算され、その小数点以下の桁数に丸められ、選択した Tax class の税額とともに購入者の通貨で表示されます。
OpenCart 4 では、購入者はチェックアウトページの配送方法ブロックで Choose をクリックし、ウィンドウ Shipping method options で iMile を選びます。この方法は OpenCart 3 と同じように動作します。
本拡張機能は料金の計算のみを行います。iMile の発送データの作成、AWB ラベルの印刷、集荷の依頼、荷物の追跡、代金引換の照合、受け取り拠点やロッカーの提供は行いません。注文には何も追加しません。注文には、ほかの OpenCart の配送方法と同じく、配送方法名と配送料金が表示されます。発送には iMile のポータルを使用してください。
ライセンスキー
本拡張機能は、vibefox.net の VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox iMile は、Extensions > Extensions > Shipping > VibeFox iMile > Edit ページで設定の上にある最初のブロックです。License key にキーを入力し、Activate をクリックしてください。その後、このブロックにはキーがマスクされた状態、ステータス（ライセンスの有効期限日やお使いのドメインなど）、および次のボタンが表示されます：Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）。その下には Product: opencart-shipping-imile の行と Manage licenses and domains in your account のリンクがあり、リンクから vibefox.net のアカウントを開けます。キーを変更できるのは、この拡張機能の変更権限を持つ管理者ユーザーのみです。ブロックの文言は管理画面の言語に従います（英語とロシア語が含まれます）。
キーが受け付けられない場合、ブロックに理由が表示されます。例：Key not found、This key belongs to another product、Domain limit reached、または License expired on と日付。ストアの住所を変更した後、またはアカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、拡張機能は最後に確認できた状態で動作を続けます。
1 つのキーは 1 つのドメインで使用できます。OpenCart の設定にあるストアの住所が対象です。ストアからキーを削除しても、ドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。
有効なキーがない場合、iMile の配送方法はチェックアウトで購入者に表示されず、料金も計算されません。同じブラウザで管理画面にログインしている管理者ユーザーには、ストアで (unlicensed — visible to admins only) と表示された配送方法が引き続き見えるため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 では、このプレビューは利用できません。ストアは管理画面のログインを認識しないため、有効なキーがない場合は、配送方法がすべての人に対して非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると、7 日間非表示になります。既存の注文には影響しません。
ライセンスの期限が切れても拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスは自動的に再確認されます。キー入力後の最初の 14 日間は 1 日 1 回、その後は週に 1 回です。cron ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスの状態は常に削除されます。
トラブルシューティング
チェックアウトに iMile が表示されない：ライセンスが有効で、Enable iMile がオンになっていることを確認してください。Geo zone、Ignore shipping zones、Countries、重量の制限、Minimum order amount を確認してください。国または * All other countries に Price table の行があるか、Price for countries not in the table が設定されているかを確認してください。商品の Requires Shipping が Yes に設定されていることを確認してください。
iMile の見積もりではなく料金表の料金が表示される：Debug log をオンにし、チェックアウトを再読み込みして、拡張機能のページの Log フィールドを確認してください。よくある理由：Live estimate がオフになっている、キーがない、Ship-from city が空欄、購入者がまだ都市を入力していない、iMile が都市の綴りを認識しない、商品に重量がない、配送先の通貨の為替レートがない、または API のエラー。設定の上部の警告も確認してください。
ログに "sign is invalid" と表示される：Secret key を確認してから、Signature を SimpleKey に変えて試してください。
キーが拒否される：Customer ID、Secret key、Environment を確認してください。テストキーはテストサーバーでのみ動作します。
都市名が一致しない：都市名は iMile の都市リストと一致している必要があります。開発者は OpenCart のイベント vfd_imile/live_request でリクエストを変更でき、国コードはイベント vfd_imile/live_country_code で変更できます。
料金の通貨が間違っている：料金表はストアの初期通貨で設定します。AED、SAR、MXN の料金は入力時に換算してください。リアルタイム見積もりは Exchange rates で換算されます。
配送料に税金が二重にかかる：料金にすでに付加価値税が含まれている場合は、Tax class を No tax に設定してください。
変更後も見積もりが古いままに見える：拡張機能のページで Save をクリックしてください。これにより、キャッシュされた iMile の見積もりが消去されます。
ページに "Warning: You do not have permission to modify VibeFox iMile!" と表示される：管理者のユーザーグループは、設定の閲覧のみが可能な可能性があります。System > Users > User Groups で、そのグループに extension/shipping/vfd_imile（OpenCart 3）または extension/vfd_imile/shipping/vfd_imile（OpenCart 4）の変更権限を付与してください。
アンインストール
Extensions > Extensions に進み、種類 Shipping を選択して、VibeFox iMile の横にある Uninstall（赤い − ボタン）をクリックします。本拡張機能のライセンスキーとライセンスの状態は常に削除されます。OpenCart は Enable iMile、Sort order、Tax class、Geo zone を常にリセットします。キャッシュされた見積もりとアクセストークンは常に削除されます。Remove data on uninstall がオンの場合は、iMile の設定とデバッグログも削除されます。オフの場合は、その他の設定が保持され、拡張機能を再インストールすると再び使用されます。既存の注文は、配送方法と料金を維持します。
OpenCart 4 では、拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に進み、インストール済みの拡張機能の一覧で VibeFox iMile の横にある Uninstall（オレンジ色の − ボタン）をクリックし、次に Delete（赤いゴミ箱のボタン）をクリックして、アップロードしたパッケージを削除してください。
iMile は、各所有者の商標です。本拡張機能は iMile と提携しておらず、iMile の承認も受けていません。