VibeFox Ninja Van for PrestaShop — ヘルプ
要件
PrestaShop: 8.0 から 9.x。
PHP: 8.0 以降。古い PHP バージョンではモジュールのインストールを拒否します。
Ninja Van の料金表: Ninja Van の発送元アカウントの料金、または Ninja Van の営業担当から提供された料金を、料金表に入力します。API キーは不要です。インドネシア国内で任意に利用するリアルタイム料金は、公開されており認証を必要としない Ninja Van Tariff API を使用します。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで機能します。
インストール
1. 管理画面で Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックします。後で探す場合は、モジュール一覧から VibeFox Ninja Van を見つけて Configure をクリックします。
3. Configure ページ上部のライセンスブロックで、License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。
4. Ninja Van の料金を料金表に入力します。インドネシアの場合は、必要に応じて Live rates を有効にできます（設定を参照）。Save をクリックします。
インストール時に、モジュールは配送日数のテキスト Courier delivery を持つ Ninja Van 配送業者を作成します。配送業者は有効になり、すべてのゾーンとすべての顧客グループに割り当てられ、税ルールはありません。ゾーン、顧客グループ、配送日数、ロゴ、サイズ制限は Shipping > Carriers で変更できます。そこで料金は設定しないでください。料金は常にモジュールから取得されます。
設定
すべての設定はモジュールのページにあります: Modules > Module Manager > VibeFox Ninja Van > Configure。設定は配送業者のすべてのゾーンに適用されます。各セクションには専用の Save ボタンがあり、ページ全体が保存されます。数値欄にテキストや負の数が入力されている場合、IDR conversion rate が 0 の場合、Minimum weight (kg) が Maximum weight (kg) より大きい場合、または Method title が 64 文字を超える場合は、何も保存されずエラーが表示されます。ショップの重量単位がモジュールで扱えない単位の場合、保存後に、商品の重量はキログラムとみなされるという警告が表示されます。
一般
Enable Ninja Van: 配送業者のオン／オフを切り替えます。Shipping > Carriers の配送業者のステータスと同じスイッチです。
Method title: カートとチェックアウトで顧客に表示される配送業者の名前です。初期値: Ninja Van。必須、最大 64 文字。
Tax: 配送業者の税ルール、または No tax（初期値）。料金表の料金にすでに税（GST、SST、VAT）が含まれている場合は No tax を選択してください。
料金（ショップの基準通貨、税抜き）
Ninja Van の料金表の料金を、ショップの基準通貨で入力してください。料金表が SGD、MYR、IDR などの通貨の場合は、先に換算してください。この表は、インドネシア以外のすべての配送先、およびリアルタイム料金が利用できない場合に使用されます。
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: 表に配送先の国の行（および * 行）がない場合、またはその行にこの重量の料金がない場合に使用されます。この場合に配送業者を非表示にするには空欄のままにします。0 は送料無料を意味します。
Price applies: 料金の計算方法です。リアルタイム料金にも適用されます。
リアルタイム料金（API）— インドネシア
Ninja Van Tariff API は、インドネシア国内で発送される荷物について、追加料金や割引を除いた標準の配送料を返します。Ninja Van はインドネシアでのみ提供しています。Live rates を有効にすると、セクションタイトルの下のステータス行に、発送元のゾーン、換算レートの未設定、最後の Tariff API の応答（環境、時刻、結果）が表示されます。
Live rates: インドネシア国内の配送について、Ninja Van のリアルタイム料金を取得します。初期値: オフ。このオプションがオフの場合、チェックアウト時に Ninja Van へは何も送信されません。
Environment: Production (api.ninjavan.co)（初期値）または Sandbox — testing only (api-sandbox.ninjavan.co)。
Service level: 料金を問い合わせるサービスです: Standard（初期値）、Express、Same day、Next day。Ninja Van にそのルートとサービスの料金がない場合は、料金表を使用します。
Ship-from zone code L1 と Ship-from zone code L2: 発送元の地区の L1 および L2 階層コードです（例: ID_A00007_01 と ID_B00069_01）。Ninja Van のゾーンコード対応表（CSV）から取得するもので、その住所が欄の下に表示されます。両方を入力するか、両方を空欄にして Shop Parameters > Contact > Stores のショップの住所から自動検出させます。検出対象は、インドネシア、州（state）、市、そして市に複数のゾーンがある場合は住所欄の地区（Kecamatan）です。形式の誤ったコードは警告とともに消去されます。片方のコードだけが入力されている場合は、両方の入力を求める警告が表示され、ステータス行にリアルタイム料金を問い合わせないことが示されます。
IDR conversion rate: Tariff API はインドネシアルピア（IDR）で料金を返します。ショップの基準通貨が IDR の場合は空欄のままにします。それ以外の場合は、1 IDR がショップの通貨でいくらになるかを入力します（例: 0.000058）。0 より大きい値である必要があります。未入力の場合、リアルタイム料金は使用されず、料金表が使用されます。
条件
Minimum weight (kg): カートの重量がこれより軽い場合、配送業者を非表示にします。商品の重量は、ショップの重量単位からキログラムに換算されます。0 は制限なしを意味します。
Maximum weight (kg): カートの重量がこれより重い場合、配送業者を非表示にします。初期値: 30。0 は制限なしを意味します。Minimum weight (kg) より小さくすることはできません。
Minimum order amount: カートの小計（配送が必要な商品、割引後、税抜き）がこの金額に達した場合にのみ配送業者を表示します。空欄の場合は常に表示します。
Free shipping from: カートの小計（配送が必要な商品、割引後、税抜き）がこの金額以上の場合、Ninja Van の配送は無料になります。空欄の場合は送料無料になりません。
配送ゾーンなしでの提供
Ignore shipping zones: 配送業者が配送先の国のゾーンに関連付けられていなくても、下記の国向けに Ninja Van を提供します。オンにすると、配送業者はすべての有効なゾーン（後から作成するゾーンを含む）に関連付けられます。オフにすると、配送業者は以前のゾーンに戻ります。
Countries: このモードでの配送先の国です。空欄の場合は、発送先のすべての国を使用します。このフィールドは Ignore shipping zones がオンの場合にのみ使用されます。
詳細
Debug log: 料金計算を、モジュールフォルダ内の logs/vfd_njvn_debug.log.php に記録します。このファイルはウェブから開くことはできません。顧客の住所は記録されません。このオプションがオフでも、失敗した Tariff API のリクエストは記録されます。作業が終わったらオフにしてください。
Log: デバッグログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログが空になります。
Remove data on uninstall: オンの場合、モジュールをアンインストールするとモジュールの設定、配送業者、キャッシュされた料金、ログが削除されます。オフの場合、再インストール用にすべてが保持されます。
チェックアウト時の動作
配送ステップで、PrestaShop はモジュールに Ninja Van の料金を問い合わせます。実物の商品のみが対象です。バーチャル商品は重量に加算されず、注文金額にも含まれません。モジュールはまず条件を確認します: Ignore shipping zones の国リスト（オンの場合）、カートの重量、最低注文金額です。送料無料が適用される場合、料金は 0 となり、Ninja Van へのリクエストは送信されません。
料金は、国の行（または * 行）から取得されます: 重量列、なければ基本料金、それもなければ Price for countries not in the table。料金がない場合、そのカートでは配送業者が非表示になります。料金はショップの基準通貨で計算され、その後、顧客のカート通貨で表示されます。
Live rates がオンの場合、インドネシア国内の配送は Ninja Van が最初に料金を計算します。モジュールは発送元と配送先の住所を Ninja Van のゾーンコードに変換します: 州（state）、市または県（regency）、そして複数のゾーンがある市の場合は住所欄に書かれた地区（Kecamatan）です。コード、重量、サービスレベルを送信し、料金を IDR からショップの通貨に換算します。Per item の場合は、異なる商品重量ごとに 1 回リクエストを送信し、カートあたり最大 5 回です。異なる重量がそれより多い場合は、料金表を使用します。
Tariff API は毎分 20 リクエストまでのため、応答は 6 時間、失敗は 5 分、「このルートの料金なし」は 1 時間キャッシュされます。モジュールは毎分 18 リクエストを超えて送信することはなく、HTTP 429 の応答後は 1 時間停止します。API のタイムアウトは 12 秒です。Ninja Van が応答しない場合、エラーを返す場合、そのルートの料金がない場合、または住所を照合できない場合は、料金表の料金が使用されます。エラーはログに記録され、顧客に表示されることはありません。
注文のある配送業者を Shipping > Carriers で編集すると、PrestaShop はそれを配送業者の新しいバージョンとして保存します。モジュールは新しいバージョンに自動的に追従します。
モジュールが行うのは料金の計算のみです。Ninja Van の注文の作成、航空貨物伝票（AWB）の印刷、集荷の手配、荷物の追跡、代金引換（COD）の処理は行いません。それらには Ninja Van Dashboard を使用してください。受け取り拠点（Ninja Points）の選択機能はありません: 配送業者は玄関先までの配送です。リアルタイム料金はインドネシア以外では利用できません。
ライセンスキー
本モジュールは vibefox.net で入手した VibeFox ライセンスキーで動作します。License — VibeFox Ninja Van ライセンスブロックは、Modules > Module Manager > VibeFox Ninja Van > Configure の一番上、設定の上にあるブロックです。キーを License key に入力し、Activate をクリックしてください。その後、ブロックにはキーがマスクされて表示され、ステータス（例: ライセンスの有効期限の日付とドメイン）と、ステータスを再確認する Check now、別のキーを入力する Change key、このショップからキーを削除する Remove key のボタンが表示されます。その下には Product: presta-shipping-ninja-van の行と、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 のアカウントで枠を解放してください。
有効なキーがない場合、Ninja Van 配送業者はチェックアウト時に顧客に表示されず、料金も計算されません。PrestaShop のフロントエンドは、管理画面にログインしていることを認識しないため、配送業者はあなたにも表示されません。キーを購入する前にモジュールを設定することはできますが、チェックアウトでのテストはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。
ライセンスの期限が切れてもモジュールは動作を続けますが、アップデートとサポートには更新が必要です。管理画面で作業している間にステータスは自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日 1 回、その後は週に 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
チェックアウトに Ninja Van が表示されない: ライセンスが有効であること、Enable Ninja Van がオンであることを確認してください。Shipping > Carriers で、配送業者が顧客の国のゾーンと顧客グループをカバーしていることを確認してください（または Ignore shipping zones をオンにして Countries を確認してください）。重量制限と Minimum order amount を確認し、国、* 行、または Price for countries not in the table に料金が設定されていることを確認してください。商品ページで、商品が特定の配送業者に限定されている場合もあります。
一部の住所でリアルタイム料金が使用されない: 配送先は Ninja Van のゾーンと一致している必要があります: インドネシア、州（state）、市または県（regency）、そして複数のゾーンがある市の場合は住所欄の地区（Kecamatan）です。一致しない場合は、料金表の料金が使用されます。Debug log をオンにし、チェックアウトを再読み込みして、モジュールのページにある Log 欄を確認してください。
リアルタイム料金がまったく問い合わせられない: リアルタイム料金（API）— インドネシア の下のステータス行に理由が表示されます: ショップの住所がインドネシアにない、発送元のゾーンを検出できない（両方のゾーンコードを入力してください）、2 つのコードのうち 1 つだけが入力されている、入力されたコードがゾーンコード対応表でペアになっていない、または IDR conversion rate が未入力です。
リクエストの上限に達した（HTTP 429）: リアルタイムのリクエストは 1 時間停止され、その間は料金表の料金が使用されます。
料金の通貨: 料金表と条件はショップの基準通貨で設定されます。リアルタイム料金はルピア（IDR）で、ショップの通貨が IDR でない場合は IDR conversion rate で換算されます。
ページに Ninja Van 配送業者が見つからないと表示される: 配送業者は Shipping > Carriers で削除されています。Modules > Module Manager でモジュールをリセットすると、再作成されます。
開発者向け: 独自の地区（Kecamatan）フィールドを持つショップは、フック actionVfdNjvnTariffZone でゾーンコードを提供できます。
アンインストール
Modules > Module Manager に移動し、VibeFox Ninja Van の横のメニューを開いて Uninstall を選択します。ライセンスキーとライセンスステータスは常に削除されます。キャッシュされた料金は常に削除されます。Remove data on uninstall がオンの場合、配送業者は削除され（注文は履歴を保持します）、設定、最後の Tariff API のステータス、ログも削除されます。オフの場合、配送業者は無効になるだけで、すべての設定は保持されます。モジュールを再インストールすると、保存されていた配送業者はアンインストール前のステータスに戻ります。
Ninja Van は各所有者の商標です。本モジュールは Ninja Van と提携しておらず、Ninja Van の承認も受けていません。