VibeFox iMile for PrestaShop — ヘルプ
要件
PrestaShop: 8.0 から 9.x まで。
PHP: 8.0 以降。古い PHP バージョンではモジュールをインストールできません。
iMile 料金体系: iMile の営業チームと合意した料金です。ショップのデフォルト通貨で料金表に入力します。
iMile API アカウント（リアルタイム見積もりのみ）: リアルタイム見積もりでは、iMile OpenAPI の「Estimated order delivery costs」を使用します。Customer ID と Secret key（iMile が Customer ID と一緒に発行する API キー）が必要です。テスト用クライアントの場合は、iMile の開発者ポータル（developer.imile.com）で登録してください。本番用キーは iMile のアカウントマネージャーから提供されます。料金表のみを使用する場合、API キーは不要です。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
1. バックオフィスで Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックします。後でモジュール一覧から VibeFox iMile を探して Configure をクリックすることもできます。
3. Configure ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを貼り付け、Activate をクリックします（「ライセンスキー」を参照）。
4. Price table に iMile の料金を入力します。必要に応じて Live rates (API) セクションに入力し、Live estimate を有効にします（設定を参照）。Save をクリックします。
インストール時、モジュールは配送日数のテキストを Courier delivery とする iMile 配送業者を作成します。配送業者はすべてのゾーンとすべての顧客グループに割り当てられます。ゾーン、顧客グループ、配送日数、ロゴ、サイズ制限は Shipping > Carriers で変更できます。そこで料金を設定しないでください。料金は常にモジュールから取得されます。
設定
すべての設定はモジュールページにあります: Modules > Module Manager > VibeFox iMile > Configure。設定は配送業者のすべてのゾーンに適用されます。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。保存するたびに、キャッシュされた iMile の見積もりとアクセストークンも消去されます。
Live estimate がオンでも動作できない場合、設定の上に警告が表示されます。Customer ID または Secret key が空、出荷元の都市または国が未入力（または国が iMile の市場ではない）、為替レートがない、または料金表が空で他の国の料金がない、といった場合です。ショップの重量単位をモジュールが認識できない場合も警告が表示されます。その場合、商品の重量はキログラムとして扱われるため、International > Localization（Local units）で単位を設定してください。保存時には、モジュールが Method title の有効性（最大 64 文字）、金額と重量の欄が 0 以上の数値であること、Minimum weight が Maximum weight 以下であること、税ルールが存在することを確認します。確認に失敗するとエラーが表示され、何も保存されません。
一般
Enable iMile: 配送業者を有効または無効にします。これは Shipping > Carriers の配送業者ステータスと同じスイッチです。
Method title: カートとチェックアウトに表示される配送業者名です。デフォルト: iMile。必須。
リアルタイムレート（API）（任意）
iMile が見積もりを返さない場合（キー未設定、都市が未入力、エラー、タイムアウト、為替レートなし）は、料金表が使用されます。
Live estimate: オンにすると、iMile から配送料金を取得します。デフォルト: オフ。Live estimate がオフの場合、チェックアウト中に iMile へ何も送信されません。
Environment: Production (openapi.imile.com)（デフォルト）または Test (test-openapi.52imile.cn)。テストキーはテストサーバーでのみ動作し、テスト料金を返します。
Customer ID: iMile が発行するクライアントコード（customerId）。例: C2102192601。クリアすると、保存されている Secret key も消去されます。
Secret key: iMile が Customer ID と一緒に発行する秘密鍵（API キー）。リクエストに署名します。保存後、このフィールドは空のままになり、Saved — leave empty to keep it. と表示されます。変更する場合のみ新しい値を入力してください。
Signature: リクエストへの署名方法。
Ship-from country: 出荷元の国です。デフォルトではショップの国（Shop country）になります。一覧には、モジュールが iMile の国コードを持つ国のみが含まれます。
Ship-from city: 荷物を出荷する都市です。iMile の都市一覧と同じ表記で入力してください（例: Dubai、Riyadh）。空欄にすると、Shop Parameters > Contact > Stores のショップの都市が使われます。
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 に申告するカートの金額も換算されます。無効な行は保存時に削除されます。
料金（Live estimate がオフの場合、および 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" のどちらも使用できます。料金が 1 つもない行と負の料金は、保存時に削除されます。国ごとに残る行は 1 つだけです。
Price for countries not in the table: ショップのデフォルト通貨での料金です。料金表に仕向け国の行がない場合（* の行もない場合）、またはその行にこの重量の料金がない場合に使われます。この場合に配送業者を非表示にしたいときは空欄にします。
Price applies: 料金表の料金の計算方法です。
リアルタイム見積もりにも同じ選択が適用されます。注文単位の場合は、カート全体を 1 個口として送信します。商品単位の場合は、異なる荷物ごとに問い合わせを行い、個数を掛けます。カートに異なる荷物が 5 個を超える場合は、料金表が使用されます。
商品の重量とサイズは、ショップの単位からキログラムとセンチメートルに換算されます。
条件
Minimum weight: カートの重量がこれより軽い場合、配送業者を非表示にします（kg 単位）。0 は制限なしを意味します。
Maximum weight: カートの重量がこれより重い場合、配送業者を非表示にします（kg 単位）。デフォルト: 30。0 は制限なしを意味します。
Minimum order amount: カートの小計（割引後、税抜き）がこの金額に達した場合にのみ配送業者を表示します。空欄にすると常に表示されます。
Free shipping from: iMile の配送が無料になる、カートの小計（割引後、税抜き）です。空欄にすると、送料無料は提供されません。
Tax: 配送業者の税ルール、または No tax です。料金表の料金と iMile の見積もりに、すでに付加価値税（VAT）が含まれている場合は、No tax を選択してください。
配送ゾーンを使わない場合の提供条件
Ignore shipping zones: 一致するゾーンに関係なく、以下の国に iMile を提供します。保存時、配送業者はすべてのゾーンに追加されます。後から作成されたゾーンにも配送業者が追加されます。このオプションをオフにすると、追加されたゾーンは削除され、配送業者は以前のゾーンに戻ります。
Countries: このモードの仕向け国です。空欄にすると、有効なすべての国が使われます。このフィールドは、Ignore shipping zones がオンの場合にのみ使われます。
詳細設定
Debug log: 料金計算の結果を、モジュールフォルダ内の logs/vfd_imle_debug.log.php に書き込みます。このファイルは Web から開くことはできません。キーや購入者の住所は記録されません。失敗した iMile のリクエストは、デバッグログがオフでも常に記録されます。作業が終わったらログをオフにしてください。
Log: デバッグログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログを空にできます。
Remove data on uninstall: オンの場合、モジュールをアンインストールすると、iMile の設定、配送業者、キャッシュされた見積もり、ログが削除されます。オフの場合は、再インストールのためにすべてが保持されます。
チェックアウト時の動作
配送ステップで、PrestaShop はモジュールに iMile の料金を問い合わせます。物理的な商品のみが対象です。仮想商品は重量に加算されず、注文金額にも含まれません。モジュールはまず条件を確認します。許可された国（Ignore shipping zones がオンの場合）、カートの重量、最低注文金額です。送料無料が適用される場合は、料金は 0 となり、iMile へのリクエストは送信されません。
Live estimate がオンの場合、モジュールは iMile に次の情報を送信します。出荷元の国、州/県、都市、配送先の国、州、都市、郵便番号、キログラム単位のカート重量、立方センチメートル単位のサイズ（商品のサイズから算出）、カートの金額、iMile のサービス、商品カテゴリです。見積もりは常に前払いとして請求されるため、代金引換の手数料は含まれません。リアルタイム見積もりは、購入者が都市を含む配送先住所を入力した後、かつカート内のすべての商品に重量がある場合にのみ要求されます。各応答は 1 時間キャッシュされます。失敗したリクエストは 5 分間キャッシュされます。タイムアウトやサーバーエラーの後は 2 分間、拒否されたキーの後は 5 分間、iMile へ問い合わせません。これにより、チェックアウトが更新のたびに iMile の応答を待つことがなくなります。API のタイムアウトは 12 秒です。期限切れのアクセストークンは自動的に更新されます。
見積もりは、為替レートを使ってショップのデフォルト通貨に換算されます。iMile が使用可能な見積もりを返さない場合（キー未設定、都市未入力、不明な都市、エラー、タイムアウト、為替レートなし）、購入者にエラーは表示されず、料金表の料金が使用されます。料金表にも料金がない場合、配送業者は非表示になります。理由はログに記録されます。料金はデフォルト通貨で計算され、その後、購入者のカートの通貨で表示されます。
Shipping > Carriers で、注文が入った後に配送業者を編集すると、PrestaShop はそれを新しい配送業者のバージョンとして保存します。モジュールは新しいバージョンに自動的に従います。
モジュールが計算するのは料金のみです。iMile の出荷データの作成、AWB ラベルの印刷、集荷の依頼、荷物の追跡、代金引換の照合、受け取りポイントやロッカーの提供は行いません。出荷には iMile のポータルを使用してください。
ライセンスキー
本モジュールは、vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox iMile は、Modules > Module Manager > VibeFox iMile > Configure ページで設定の上にある最初のブロックです。キーを License key に貼り付けて Activate をクリックします。その後、このブロックにはキーがマスクされた状態で表示され、ステータス（例: ライセンスの有効期限日とお使いのドメイン）、そして Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このショップからキーを削除）のボタンが表示されます。その下には Product: presta-shipping-imile の行と、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 のアカウントで枠を解放してください。
有効なキーがない場合、iMile の配送業者は注文手続き時に購入者には表示されず、料金も計算されません。PrestaShop のフロントエンドは、バックオフィスにログインしていることを認識しないため、管理者にも配送業者は非表示になります。キーを購入する前にモジュールを設定することはできますが、注文手続きでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。
ライセンスの期限が切れた場合も、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。バックオフィスで作業している間、ステータスは自動的に再確認されます。キー入力後の最初の 14 日間は 1 日 1 回、その後は週に 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
チェックアウトに iMile が表示されない: ライセンスが有効であること、Enable iMile がオンであることを確認してください。Shipping > Carriers で、配送業者が購入者の国のゾーンと顧客グループをカバーしているか確認するか、Ignore shipping zones をオンにして Countries を確認してください。重量の上限と Minimum order amount を確認してください。国または * に Price table の行があるか、または Price for countries not in the table が設定されているか確認してください。商品ページで、特定の配送業者に制限されている場合もあります。
iMile の見積もりの代わりに料金表の料金が表示される: Debug log をオンにして、チェックアウトを再読み込みし、モジュールページの Log フィールドを確認してください。よくある原因は次のとおりです。Live estimate がオフ、キーが未設定、購入者がまだ都市を入力していない、iMile が都市名の表記を認識しない、商品に重量がない、配送先通貨の為替レートがない、または API エラーです。設定の上の警告も確認してください。
ログに "sign is invalid" と表示される: Secret key を確認し、次に Signature = SimpleKey を試してください。
キーが拒否される: Customer ID、Secret key、Environment を確認してください。テストキーはテストサーバーでのみ動作します。
都市名が一致しない: 都市名は iMile の都市一覧と一致している必要があります。開発者は actionVfdImileLiveRequest フックで都市名を、actionVfdImileLiveCountryCode フックで国コードを対応付けできます。
料金の通貨が誤っている: 料金表はショップのデフォルト通貨で設定されています。AED、SAR、MXN の料金は、入力時に換算してください。リアルタイム見積もりは Exchange rates で換算されます。
送料に税金が二重にかかる: 料金にすでに VAT が含まれている場合は、Tax を No tax に設定してください。
変更後も見積もりが古いまま: モジュールページで Save をクリックしてください。これでキャッシュされた iMile の見積もりが消去されます。
ページに iMile 配送業者が見つからないと表示される: 配送業者は Shipping > Carriers で削除されています。Modules > Module Manager でモジュールをリセットすると、再作成されます。
アンインストール
Modules > Module Manager に移動し、VibeFox iMile の横にあるメニューを開いて Uninstall を選択します。ライセンスキーとライセンスステータスは常に削除されます。キャッシュされた見積もりとアクセストークンは常に削除されます。Remove data on uninstall がオンの場合、配送業者は削除され（注文は履歴を保持します）、設定とログも削除されます。オフの場合、配送業者は無効になるだけで、すべての設定は保持されます。モジュールを再インストールすると、配送業者の以前のステータスが復元されます。
iMile は、それぞれの所有者の商標です。本モジュールは iMile とは提携しておらず、iMile による推奨も受けていません。