VibeFox Ninja Van for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 で動作確認）または 4.0.2 以降（4.1.0.3 で動作確認）。

PHP: 8.0 以降。

Ninja Van の料金表: Ninja Van の発送者アカウントの料金、または Ninja Van の営業担当から提供された料金を、料金表に入力します。API キーは不要です。インドネシア国内の任意のリアルタイム料金は、公開されていて認証を必要としない Ninja Van Tariff API を使用します。

VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。

インストール

このダウンロードは、両方の OpenCart バージョン用のパッケージが入った zip ファイル 1 つです。コンピュータで解凍してください。README.txt、OpenCart 3 用パッケージ vfd_ninja_van-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ vfd_ninja_van.ocmod.zip が含まれています。お使いの OpenCart のバージョンのパッケージのみをインストールしてください。ライセンスキーは両方のバージョンで同じです。

OpenCart 3

1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_ninja_van-oc3-(version).ocmod.zip を選択します。この拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。インストーラーの代わりに、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。

2. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選びます。VibeFox Ninja Van を見つけて、Install（緑色の + ボタン）をクリックします。

3. Edit（鉛筆のボタン）をクリックして設定画面を開きます。

4. Edit ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。

5. 料金表に Ninja Van の料金を入力します。インドネシア向けにリアルタイム料金を使う場合は、必要に応じて Live rates をオンにします（設定を参照）。Enable Ninja Van をオンにして、Save をクリックします。

OpenCart 4

1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_ninja_van.ocmod.zip を選択します。ファイル名を変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から読み取るため、名前を変更したパッケージは動作しません。

2. パッケージは同じページのインストール済み拡張機能の一覧に表示されます。その横の Install（緑色の + ボタン）をクリックします。

3. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選択します。VibeFox Ninja Van を見つけ、Install（緑色の + ボタン）をクリックしてから、Edit（鉛筆のボタン）をクリックします。

4. ライセンスキーと設定は、OpenCart 3 の手順 4 と 5 と同じように入力します。設定ページとその項目は両方のバージョンで同じです。

インストール直後は、Enable Ninja Van をオンにして保存するまで、この配送方法はオフのままです。アンインストール後に拡張機能を再インストールした場合は、保存されていた Ninja Van の設定が再び使用されます。

設定

すべての設定は拡張機能のページにあります。Extensions > Extensions > Shipping > VibeFox Ninja Van > Edit です。セクションは左側に一覧表示されます。下部にある 1 つの Save ボタンで、ページを再読み込みせずにページ全体を保存します。Method title が空である場合、64 文字を超える場合、または < > ; = # { } を含む場合、数値フィールドに文字や負の数が入っている場合、IDR conversion rate が 0 の場合、Minimum weight (kg) が Maximum weight (kg) より大きい場合、Sort order が整数でない場合には、何も保存されずエラーが表示されます。ストアに単位が kg の重量クラスがなく、既定の重量クラスの単位を拡張機能が認識できない場合は、商品の重量がキログラムとして扱われるという警告が表示されます。その場合は System > Localisation > Weight Classes で kg の重量クラスを追加してください。この拡張機能の変更権限を持つ管理者ユーザーだけが設定を保存できます。

一般

設定はすべてのジオゾーンに適用されます。Conditions で配送方法をジオゾーンに限定することも、Ignore shipping zones を使うこともできます。

Enable Ninja Van: チェックアウト時に Ninja Van を表示または非表示にします。既定値: オフ。

Method title: カートとチェックアウトでお客様に表示される配送方法の名前です。既定値: Ninja Van。必須、最大 64 文字。

Tax class: 送料の税率クラス、または No tax（既定値）です。料金表の金額にすでに税（GST、SST、VAT）が含まれている場合は No tax を選択します。

Sort order: チェックアウト時の配送方法の中での Ninja Van の表示順です。整数で入力します。

料金（ストアの既定通貨、税抜き）

Ninja Van の料金表の金額を、ストアの既定通貨で入力します。料金表が SGD、MYR、IDR などの別の通貨の場合は、先に換算してください。この表は、インドネシア以外のすべての配送先と、リアルタイム料金が利用できない場合に使われます。

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 の場合、その国への送料は無料です。「9.99」と「9,99」のどちらも入力できます。料金が入っていない行は保存時に削除され、同じ国の行は最初の 1 行だけが残ります。

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）から取得し、対応表の住所はフィールドの下に表示されます。両方を入力してください。OpenCart のストア住所には市区町村と番地が別々に入っていないため、そこから発送元ゾーンを判定することはできません。コードは大文字に変換されます。形式が誤ったコードは警告と共に消去されます。1 つだけ入力した場合は、両方の入力を求める警告が表示され、リアルタイム料金は問い合わせされないことがステータス行に表示されます。2 つのコードがゾーンコード対応表で組になっていない場合も、ステータス行で警告されます。

IDR conversion rate: Tariff API は、料金をインドネシアルピア（IDR）で返します。ストアの既定通貨が IDR の場合は空欄のままにします。それ以外の場合は、1 IDR がストアの通貨でいくらに当たるかを入力します（例: 0.000058）。0 より大きい値である必要があります。この値がないと、リアルタイム料金は使われず、料金表が使われます。

条件

Minimum weight (kg): カートがこの重量より軽い場合は配送方法を非表示にします。商品の重量は OpenCart の重量クラスからキログラムに換算されます。0 は上限なし（既定値）を意味します。

Maximum weight (kg): カートがこの重量より重い場合は配送方法を非表示にします。既定値: 30。0 または空欄は上限なしを意味します。Minimum weight (kg) より小さくすることはできません。

Minimum order amount: 配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額に達した場合にのみ、配送方法を表示します。常に表示する場合は空欄のままにします。

Free shipping from: 配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額以上の場合、Ninja Van の配送料が無料になります。送料無料を設けない場合は空欄のままにします。

Geo zone: この地理的ゾーン内の住所にのみ Ninja Van を提供します。All zones（既定値）は制限なしを意味します。Ignore shipping zones がオンのときは確認されません。ジオゾーンは System > Localisation > Geo Zones で管理します。

配送ゾーンを使わない場合の提供範囲

Ignore shipping zones: Geo zone に関係なく、下に記載された国に対して Ninja Van を提供します。オフ（既定値）の場合は、ジオゾーンで判定され、国のリストは使われません。

Countries: このモードで対象とする配送先の国です。すべての国を許可する場合は空欄のままにします。このフィールドは、Ignore shipping zones がオンのときにのみ使われます。

詳細設定

Debug log: 料金の計算内容を storage/logs/vfd_njvn_debug.log.php（OpenCart 4 では system/storage/logs/vfd_njvn_debug.log.php）に書き込みます。このファイルはウェブから読み取ることはできません。お客様の住所やゾーンコードは記録されません。失敗した Tariff API のリクエストは、このオプションがオフでも記録されます。確認が終わったらオフにしてください。ファイルが 5 MB に達すると、vfd_njvn_debug.old.log.php に移動され、新しいログが始まります。

Log: デバッグログのサイズと最新のエントリを表示します。Clear log をクリックすると内容を消去します。

Remove data on uninstall: オンの場合、拡張機能をアンインストールすると、Ninja Van の設定とログが削除されます。オフ（既定値）の場合は、再インストール用に保持されます。キャッシュされた料金は常に削除されます。

インポート / エクスポート

Export: Download JSON をクリックすると、設定を JSON ファイルとして保存できます。この拡張機能には秘密のキーがないため、すべての内容がエクスポートされます。

Import: 以前にエクスポートした JSON を貼り付けて Import をクリックすると、設定を復元します（別のストアでの利用など）。値は通常の保存と同じように検証されます。

チェックアウト時の動作

OpenCart が配送方法を表示するとき、拡張機能に Ninja Van の料金を問い合わせます。Geo zone が設定されていて（かつ Ignore shipping zones がオフ）、住所がその範囲外の場合、Ninja Van は提供されません。Requires Shipping が Yes に設定されている商品のみが計算に含まれます。それ以外の商品は重量に加算されず、注文金額にも含まれません。その後、拡張機能は条件を確認します。Ignore shipping zones の国のリスト（オンの場合）、カートの重量、最低注文金額です。注文金額は、配送が必要な商品の料金（クーポン割引後、税抜き）です。ギフト券、リワードポイント、ストアクレジットは考慮されません。送料無料が適用される場合は料金が 0 となり、Ninja Van へのリクエストは送信されません。

料金は、その国の行（または * の行）から取得されます。まず重量の列、次に基本料金、最後に Price for countries not in the table の順です。料金がない場合は、そのカートに対して配送方法が非表示になります。料金はストアの既定通貨で計算され、その小数桁に丸められ、選択した Tax class の税額を加えて、お客様の通貨で表示されます。

Live rates がオンのとき、インドネシア国内の配送は、まず Ninja Van によって料金が計算されます。拡張機能は配送先の住所を Ninja Van のゾーンコードに変換します。住所の地域（州）、City フィールド（市または県）、そして複数のゾーンを持つ市については Address 1 または Address 2 に記載された地区（Kecamatan）です。発送元のコード、配送先のコード、重量、サービスレベルを送信し、料金を IDR からストアの通貨に換算します。Per item の場合は、異なる商品重量ごとに 1 回のリクエストを送信し、カートあたり最大 5 回です。異なる重量がそれより多い場合は、料金表が使われます。

Tariff API は 1 分あたり 20 回のリクエストを許可しているため、応答は拡張機能のテーブルにキャッシュされます。料金は 6 時間、「このルートの料金なし」は 1 時間、失敗は 5 分です。設定を保存してもこのキャッシュは消去されません。拡張機能が 1 分あたりに送信するリクエストは最大 18 回までで、HTTP 429 の応答を受け取ると 1 時間停止します。API のタイムアウトは 12 秒です。Ninja Van が応答しない、エラーを返す、そのルートの料金がない、または住所を照合できない場合は、料金表の金額が使われます。エラーはログに記録され、お客様に表示されることはありません。

OpenCart 4 では、お客様はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options のウィンドウで Ninja Van を選択します。この方法の動作は OpenCart 3 と同じです。

この拡張機能は料金の計算のみを行います。Ninja Van の注文の作成、航空貨物伝票（AWB）の印刷、集荷の予約、荷物の追跡、代金引換（COD）の処理は行いません。それらには Ninja Van Dashboard を使用してください。受け取りポイント（Ninja Points）の選択機能はありません。この配送方法は玄関先までの配送です。注文に追加される情報はありません。注文には、他の OpenCart の配送方法と同様に、配送方法の名前と送料が表示されます。リアルタイム料金はインドネシア以外では利用できません。

ライセンスキー

この拡張機能は、vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Ninja Van は、Extensions > Extensions > Shipping > VibeFox Ninja Van > Edit ページで設定の上にある最初のブロックです。キーを License key に入力し、Activate をクリックしてください。その後、ブロックにはキーが伏せ字で表示され、ステータス（ライセンスの有効期限日やドメインなど）と、ボタンが表示されます。ボタンは、Check now でステータスを再確認、Change key で別のキーを入力、Remove key でこのストアからキーを削除するためのものです。その下には Product: opencart-shipping-ninja-van の行と、vibefox.net のアカウントを開くリンク Manage licenses and domains in your account があります。キーを変更できるのは、この拡張機能の変更権限を持つ管理者ユーザーだけです。ブロックの文言は管理画面の言語に従います（英語とロシア語を含みます）。

キーが受け付けられない場合、ブロックに理由が表示されます。例: Key not found、This key belongs to another product、Domain limit reached、または日付付きの License expired on。ストアのアドレスを変更した後、またはアカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、拡張機能は最後に確認された状態で動作を続けます。

1 つのキーは 1 つのドメインで使用できます。ドメインは OpenCart の設定にあるストアのアドレスです。ストアからキーを削除しても、ドメインの枠は解放されません。枠は vibefox.net のアカウントで解放してください。

有効なキーがない場合、Ninja Van はチェックアウト時にお客様に表示されず、料金も計算されません。同じブラウザで管理画面にログインしている管理者ユーザーには、ストアでこの配送方法が (unlicensed — visible to admins only) と表示された状態で引き続き見えるため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 ではこのプレビューは利用できません。ストアは管理画面のログインを認識しないため、有効なキーがない場合は全員にこの方法が非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると 7 日間非表示になります。既存の注文は影響を受けません。

ライセンスの期限が切れても、拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスが自動的に再確認されます。キーの入力後最初の 14 日間は 1 日に 1 回、その後は 1 週間に 1 回です。cron ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスのステータスは常に削除されます。

トラブルシューティング

チェックアウトに Ninja Van が表示されない: ライセンスが有効であること、Enable Ninja Van がオンであることを確認してください。Geo zone（または Ignore shipping zones と Countries）、重量の制限、Minimum order amount を確認し、配送先の国、* の行、または Price for countries not in the table に料金があることを確認してください。商品の Requires Shipping が Yes に設定されていることも確認してください。

一部の住所でリアルタイム料金が使われない: 配送先は Ninja Van のゾーンに照合される必要があります。インドネシア、地域（州）、City の市または県、そして複数のゾーンを持つ市の場合は住所の行にある地区（Kecamatan）が必要です。そうでない場合は料金表が使われます。Debug log をオンにし、チェックアウトを再読み込みして、拡張機能のページにある Log の欄を確認してください。

リアルタイム料金がまったく問い合わせされない: Live rates (API) — Indonesia の下のステータス行に理由が表示されます。発送元のゾーンコードがない、2 つのコードのうち 1 つだけが入力されている、入力したコードがゾーンコード対応表で組になっていない、または IDR conversion rate がない、のいずれかです。

リクエストの上限に達した（HTTP 429）: リアルタイムのリクエストは 1 時間停止され、その間は料金表が使われます。設定を保存しても停止は解除されません。

料金の通貨: 料金表と条件は、ストアの既定通貨で設定されています。リアルタイム料金はルピア（IDR）で、ストアの通貨が IDR でない限り、IDR conversion rate で換算されます。

ページに「Warning: You do not have permission to modify VibeFox Ninja Van!」と表示される: 管理者ユーザーのグループには設定の閲覧権限しかない可能性があります。System > Users > User Groups で、そのグループに extension/shipping/vfd_ninja_van（OpenCart 3）または extension/vfd_ninja_van/shipping/vfd_ninja_van（OpenCart 4）の変更権限を付与してください。

開発者向け: 独自の地区（Kecamatan）フィールドを持つストアは、OpenCart のイベント vfd_ninja_van/tariff_zone（トリガー catalog/vfd_ninja_van/tariff_zone）を使ってゾーンコードを渡すことができます。発送元のゾーンについても同様です。Tariff API のアドレスは設定 vfd_njvn_api_url（テスト用）で置き換えられます。この設定は設定画面にはフィールドがありません。

アンインストール

Extensions > Extensions に移動し、種類 Shipping を選んで、VibeFox Ninja Van の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスのステータスは常に削除されます。OpenCart は常に Enable Ninja Van、Sort order、Tax class、Geo zone をリセットします。キャッシュされた料金は常に削除されます。Remove data on uninstall がオンの場合は、Ninja Van の設定、直近の Tariff API のステータス、デバッグログも削除されます。オフの場合は、その他の設定は保持され、拡張機能を再インストールしたときに再び使用されます。既存の注文は、配送方法と送料をそのまま保持します。

OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧で VibeFox Ninja Van の横にある Uninstall（オレンジ色の − ボタン）をクリックしてから、アップロードしたパッケージを削除するために Delete（赤いゴミ箱ボタン）をクリックしてください。

Ninja Van は、それぞれの所有者の商標です。この拡張機能は Ninja Van と提携しておらず、Ninja Van による推奨も受けていません。