VibeFox J&T Express for PrestaShop — ヘルプ
要件
PrestaShop: 8.0 ～ 9.x。
PHP: 8.0 以降。モジュールは古い PHP バージョンではインストールできません。
J&T Express Malaysia API へのアクセス（リアルタイム見積もりのみ）: リアルタイム見積もりは、マレーシアの配送先住所向けの J&T Express Malaysia でのみ利用できます。必要な値は 4 つです。J&T Express Malaysia の Web サイトで J&T VIP アカウントを申し込んでください（モジュールのページにリンクがあります）。J&T から VIP 顧客コードと VIP API キーが提供されます。API アカウントと、リクエストの署名に使う秘密鍵は、API 連携のために J&T が発行します。J&T のアカウントマネージャーにお問い合わせください。J&T フィリピン、インドネシア、その他の国には公開の見積もり API がないため、これらの国では料金表を使用してください。料金表と予備の送料のみを使用する場合、J&T API へのアクセスは不要です。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
1. バックオフィスで Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックするか、後でモジュールの一覧から VibeFox J&T Express を見つけて Configure をクリックします。
3. Configure ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを貼り付け、Activate をクリックします（ライセンスキーを参照）。
4. 料金表や予備の送料を入力します。マレーシアのリアルタイム見積もりを使用する場合は、J&T API の認証情報と発送元の郵便番号も入力します。ショップのデフォルト通貨が MYR でない場合は、通貨換算レートも入力してください（設定を参照）。Save をクリックします。
インストール時に、モジュールは配送時間のテキスト Courier delivery を付けて J&T Express 配送業者を作成します。配送業者はすべてのゾーンとすべての顧客グループに割り当てられます。ゾーン、顧客グループ、配送時間、ロゴ、サイズ制限は Shipping > Carriers で変更できます。ここで料金を設定しないでください。料金は常にモジュールから取得されます。
設定
すべての設定はモジュールのページにあります: Modules > Module Manager > VibeFox J&T Express > Configure。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。保存するたびに、キャッシュされた J&T の見積もりも消去されます。リアルタイム見積もりが一部しか設定されていない場合、ページ上部の警告に不足している設定が表示されるか、通貨換算レートが未設定であることが通知されます。0 以上の数値ではない金額はエラーで拒否されます。Currency conversion rate が 0 の場合や、Min weight が Max weight より大きい場合も同様に拒否されます。ショップの重量単位が認識されない場合、警告が表示され、International > Localization で標準単位を設定するよう求められます。
一般
このページの設定はすべてのゾーンに適用されます。配送業者のゾーン、顧客グループ、サイズ制限は Shipping > Carriers で設定します（または下の Ignore shipping zones を使用します）。
Enable J&T Express: 配送業者のオン・オフを切り替えます。Shipping > Carriers の配送業者のステータスと同じスイッチです。
Method title: カートとチェックアウトに表示される配送業者名です。デフォルト: J&T Express。必須です。
Tax: 配送業者の税ルール、または No tax です。税ルールを選ぶと、ショップの配送税が料金に加算されます。J&T の料金に請求したい内容がすべて含まれている場合は No tax を選択してください。
J&T Express Malaysia API（リアルタイム見積もり）（任意。マレーシアの配送先住所向け。4 つの認証情報はすべて必須です）
VIP customer code: J&T Express の VIP 顧客コードです。消去すると、保存済みの VIP API キーも消去されます。
VIP API key: VIP コードと一緒に J&T Express から発行された API キー（パスワード）です。ログには決して記録されません。保存後、このフィールドは空になり、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。
API account: J&T Express の API アカウント名です。消去すると、保存済みの秘密鍵も消去されます。
API private key: API アカウントの秘密鍵です。リクエストの署名（SHA-256）にのみ使用されます。J&T に送信されることも、ログに記録されることもありません。VIP API キーと同様に、保存後は再表示されません。
Sender postcode: 荷物を発送するマレーシアの郵便番号です。ショップがマレーシアにある場合は、空欄のままにすると Shop Parameters > Contact > Stores のショップの郵便番号が使われます。保存時にスペースは削除されます。
Currency conversion rate: J&T Express Malaysia の見積もりは MYR 建てです。ショップのデフォルト通貨が MYR でない場合は、1 MYR がご自身の通貨で何単位に相当するかを入力します（1 MYR = X）。この値がないと、リアルタイム見積もりは使用されず、代わりに料金表または予備の送料が使われます。デフォルト通貨が MYR の場合、フィールドにその旨が表示され、入力は不要です。見積もりはそのまま使用されます。小数点としてピリオドとカンマの両方が使えます。レートは 0 より大きい値である必要があります。
料金表と予備の送料（マレーシア以外の国、リアルタイム見積もりが未設定の場合、または J&T が見積もりを返さない場合に使用されます。料金はショップのデフォルト通貨で、税抜きです）
Country prices: 国ごとに 1 行の表です。Add country をクリックして行を追加し、ゴミ箱のアイコンをクリックして行を削除します。独自の行がないすべての国には * Any other country を選択します。各行には Base price と 5 つの重量区分があります。XS は 1 kg まで、S は 2 kg まで、M は 3 kg まで、L は 5 kg まで、XL は 5 kg 超です。区分の料金が 0 より大きい場合、その区分のカートについて基本料金の代わりに使用されます。区分が 0 の場合は基本料金が使用されます。基本料金が 0 の場合は送料無料になり、空の基本料金は 0 として保存されます。同じ国が 2 行にある場合は、最後の行が残ります。行のない国（* の行がない場合）には、料金表の料金は適用されません。
Fallback cost: J&T も料金表も料金を提供できない場合に使用される料金です。この場合に配送業者を非表示にするには空欄にします。0 は送料無料を意味します。
Table / fallback price is: Per order は料金を 1 回だけ請求します。Per item (multiplied by the number of items) はカート内の商品数を掛けます。J&T のリアルタイム見積もりは常に注文全体を対象とします。
条件
Free shipping from: この金額以上で送料が無料になる、カートの小計です（配送が必要な商品、割引後、税抜き）。送料無料を設定しない場合は空欄にします。
Minimum subtotal: カートの小計がこの金額に達した場合のみ配送業者を表示します。常に表示する場合は空欄にします。
Min weight: カートがこれより軽い場合、配送業者を非表示にします（kg 単位）。商品の重量はショップの重量単位から換算されます。0 は制限なしを意味します。Max weight より大きくすることはできません。
Max weight: カートがこれより重い場合、配送業者を非表示にします（kg 単位）。デフォルト: 50。0 は制限なしを意味します。
配送ゾーンを使わない場合の提供範囲
Ignore shipping zones: 下記の国について、その国のゾーンに配送業者が紐付けられていなくても、配送業者を提供します。オンにすると、配送業者はすべての有効なゾーンに紐付けられ、後から作成するゾーンにも紐付けられます。オフの場合、配送業者は Shipping > Carriers で設定した自身のゾーンでのみ提供されます。オフにすると、配送業者は以前のゾーンに戻ります。
Countries: このモードの配送先の国です。空欄にすると、配送先としているすべての国が使用されます。このフィールドは Ignore shipping zones がオンの場合にのみ使用されます。
詳細設定
Debug log: 料金計算の内容を、モジュールフォルダー内の logs/vfd_jtex_debug.log.php に書き込みます。このファイルはウェブから開くことはできません。このオプションがオフでも、J&T API のエラーは常に記録されます。キー、パスワード、購入者の郵便番号は記録されません。作業が終わったらログをオフにしてください。
Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると内容が消去されます。
Remove data on uninstall: オンの場合、モジュールをアンインストールすると、モジュールの設定、配送業者、キャッシュされた見積もり、ログが削除されます。オフの場合は、再インストールに備えてすべて保持されます。
チェックアウト時の動作
配送ステップで、PrestaShop はモジュールに J&T Express の料金を問い合わせます。対象になるのは実物の商品だけです。バーチャル商品は重量に加算されず、小計にも含まれません。モジュールはまず条件を確認します。配送先の国（Ignore shipping zones を考慮）、カートの重量、最低小計です。カートの小計が Free shipping from に達している場合、料金は 0 となり、J&T へのリクエストは送信されません。
それ以外の場合、料金は最初に料金を提供できるソースから取得されます。
1. J&T のリアルタイム見積もり: 4 つの API 認証情報と発送元の郵便番号がすべて設定されており、配送先の国がマレーシアで、購入者が 5 桁の郵便番号を入力しており、デフォルト通貨が MYR 以外のショップでは換算レートが設定されている場合にのみ使用されます。モジュールは、発送元と配送先の郵便番号、およびカートの重量（最低 0.1 kg）を J&T に送信し、標準サービス EZ（荷物 1 個）の見積もりを求めます。返された MYR の料金は、ショップのデフォルト通貨に換算されます。
2. 国別の料金: 配送先の国の行、または * の行から、カートの重量区分の料金を取得します。
3. 予備の送料。
いずれのソースも料金を提供できない場合、そのカートでは配送業者が非表示になります。Per item は料金表と予備の料金にのみ適用されます。料金はショップのデフォルト通貨で計算され、その後、購入者のカートの通貨で表示されます。
J&T の各応答は 1 時間キャッシュされるため、同じカートで新たなリクエストが発生することはありません。失敗したリクエストは 10 分間キャッシュされるため、チェックアウトは再読み込みのたびに J&T の応答を待つことはありません。リクエストのタイムアウトは 10 秒です。J&T がエラー、ゼロ円の料金、または応答なしを返した場合、購入者にエラーは表示されません。料金表または予備の送料が使用され、その理由がログに記録されます。
注文のある配送業者を Shipping > Carriers で編集した場合、PrestaShop はそれを新しいバージョンの配送業者として保存します。モジュールは新しいバージョンに自動的に従います。
モジュールが計算するのは送料のみです。送り状、伝票、ラベルの作成、集荷の予約、荷物のキャンセルや追跡は行わず、購入者が受け取り場所を選ぶこともできません。荷物は通常どおり J&T のアカウントで作成・追跡してください。本モジュールは、J&T Express Malaysia の公式プラグインのリクエスト形式に基づいて開発されています。本番稼働の前に、J&T のアカウントで料金を確認してください。
ライセンスキー
本モジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox J&T Express は、Modules > Module Manager > VibeFox J&T Express > Configure ページの設定の上にある最初のブロックです。キーを License key に貼り付け、Activate をクリックします。その後、ブロックにはキーが一部隠された形で表示され、ステータス（ライセンスの有効期限日やお使いのドメインなど）、および Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このショップからキーを削除）のボタンが表示されます。その下には Product: presta-shipping-jt-express の行と、Manage licenses and domains in your account のリンクがあり、vibefox.net のアカウントが開きます。キーを変更できるのは、本モジュールに対する Configure 権限を持つ従業員のみです。ブロックのテキストはバックオフィスの言語に従います（英語とロシア語が含まれます）。
キーが受け入れられない場合、ブロックに理由が表示されます（例: Key not found、This key belongs to another product、Domain limit reached、または日付と共に License expired on）。ショップの住所を変更した後、またはアカウントでドメインの枠を解放した後に、Check now をクリックしてください。ライセンスサーバーに接続できない場合、モジュールは最後に確認された状態で動作を続けます。
1 つのキーは 1 つのドメインで使用できます。これはメインショップのドメインを指し、マルチストア構成の場合も同様です。ショップからキーを削除しても、そのドメインの枠は解放されません。枠は vibefox.net のアカウントで解放してください。
有効なキーがない場合、J&T Express 配送業者はチェックアウトで購入者に表示されず、料金も計算されません。PrestaShop のストアフロントは、バックオフィスにログインしていることを認識しないため、配送業者はご自身にも表示されません。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。
ライセンスの期限が切れても、モジュールは動作し続けますが、アップデートとサポートには更新が必要です。バックオフィスで作業している間、ステータスは自動的に再確認されます。キー入力後の最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
チェックアウトに J&T Express が表示されない: ライセンスが有効で、Enable J&T Express がオンになっていることを確認してください。Shipping > Carriers で、配送業者が購入者の国のゾーンと購入者のグループをカバーしていることを確認してください（または Ignore shipping zones がオンで、その国が許可されていることを確認してください）。重量制限と Minimum subtotal も確認してください。Country prices に、その国の行または * の行があるか、Fallback cost が設定されているかを確認してください。商品ページで、特定の配送業者に制限されている場合もあります。Debug log をオンにして、モジュールのページの Log フィールドを確認してください。
料金は J&T からではなく料金表から来ている: リアルタイム見積もりには、4 つの API 認証情報、発送元の郵便番号、5 桁の郵便番号が入ったマレーシアの配送先住所、そして MYR 以外のショップの場合は Currency conversion rate が必要です。モジュールのページ上部の警告を確認してください。J&T がリクエストを拒否するか応答しない場合、エラーはログに記録され、料金表または予備の送料が使用されます。失敗したリクエストは 10 分後に再試行されます。
フィリピンやインドネシアではリアルタイム見積もりが使えない: J&T は、これらの国向けに公開の見積もり API を提供していません。これらの国では料金表と予備の送料を使用してください。
ある国で誤って送料が無料になる: その国の行の基本料金が 0 になっています（空の基本料金は 0 として保存されます）。基本料金を入力するか、行を削除してください。Free shipping from も確認してください。
変更後にレートが古いように見える: モジュールのページで Save をクリックしてください。キャッシュされた J&T の見積もりが消去されます。
ページに J&T Express 配送業者が見つからないと表示される: 配送業者が Shipping > Carriers で削除されています。Modules > Module Manager でモジュールをリセットして、再作成してください。
開発者向けフック: フック actionVfdJtexQuoteRequest は見積もりリクエストの本文（例: サービスの種類）を変更し、actionVfdJtexApiUrl は見積もりのエンドポイントを変更します。
アンインストール
Modules > Module Manager に移動し、VibeFox J&T Express の横にあるメニューを開いて、Uninstall を選択します。ライセンスキーとライセンスステータスは常に削除されます。キャッシュされた見積もりは常に削除されます。Remove data on uninstall がオンの場合、配送業者は削除され（注文は履歴を保持します）、設定とログも削除されます。オフの場合、配送業者はオフになるだけで、すべての設定は保持されます。モジュールを再インストールすると、保存されていた配送業者は以前のステータスに戻ります。
J&T Express は、各所有者の商標です。本モジュールは J&T Express と提携しておらず、J&T Express の承認も受けていません。