VibeFox The Courier Guy for OpenCart — ヘルプ

要件

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

PHP：8.0 以降。

ShipLogic API キー（リアルタイム料金とロッカー用）：The Courier Guy は ShipLogic プラットフォーム上で動作しています。The Courier Guy のクーリエポータルで、ビジネスアカウントの Settings > API Keys から API キーを作成してください。キーがない場合は料金表のみが使われ、ロッカーのオプションは表示されません。

南アフリカへの配送：リアルタイム料金とロッカーは南アフリカの住所のみが対象です。南アフリカをストアの有効な国に設定する必要があり（System > Localisation > Countries）、リアルタイムのクーリエ料金には南アフリカの州（ゾーン）が必要です。これらは OpenCart 3 に既に含まれています。

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

インストール

ダウンロードは、両方の OpenCart バージョン向けのパッケージを含む 1 つの ZIP ファイルです。お使いのコンピューターで展開してください。含まれるのは README.txt、OpenCart 3 用パッケージ vfd_the_courier_guy-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ vfd_the_courier_guy.ocmod.zip です。お使いの OpenCart バージョン用のパッケージだけをインストールしてください。ライセンスキーは両方のバージョンで同じです。

OpenCart 3

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

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

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

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

5. Courier to the door や TCG locker をオンにして、ShipLogic の API key を入力します。リアルタイム料金を使う場合は、発送元住所（番地、市、州、郵便番号）を入力します。ストアの通貨が ZAR でない場合は、ZAR conversion rate も入力します。

6. 料金表やフォールバック料金を入力し、Save をクリックします。

OpenCart 4

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

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

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

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

インストール後は、どちらかのオプションをオンにして保存するまで、両方のオプションがオフのままです。2 つのオプションのうち少なくとも 1 つがオンの間、拡張機能は有効になります。アンインストール後に再インストールした場合は、残しておいた設定が再び使用されます。

設定

すべての設定は拡張機能のページにあります：Extensions > Extensions > Shipping > VibeFox The Courier Guy > Edit。セクションは左側に並んでいます。ページ下部の Save ボタンを押すと、ページを再読み込みせずにページ全体が保存されます。保存するたびに、キャッシュされた料金とロッカー、および最後の ShipLogic エラーが消去されます。この拡張機能の変更権限を持つ管理者ユーザーだけが設定を保存できます。

オプション名、税クラス、並び順、ジオゾーンが有効でない場合は何も保存されず、ページに理由が表示されます（例：Enter a valid option name (1-64 characters, without < > ; = # { }).）。無効な数値（負の数など）は保存されません。ページはその項目を示し、以前の値を保持します。残りの項目は保存されます。少なくとも 1 つのオプションがオンの間、設定ページ上部の警告が、南アフリカが有効な国になっていないこと、API キーがないこと、ZAR 換算レートや発送元住所がないこと、料金表もフォールバック料金もないこと、南アフリカに州（ゾーン）がないこと、または直近の ShipLogic リクエストが失敗したこと（日付とエラー付き）を知らせます。ストアに kg の重量クラスや cm の長さクラスがない場合にも警告が表示されます。

一般

配送の種類ごとに、チェックアウトで独立したオプションになります。

Courier to the door：購入者の住所への The Courier Guy クーリエ配送を提供します。既定値：オフ。

Courier option name：チェックアウトに表示されるクーリエオプションの名前。既定値：The Courier Guy。必須、64 文字以内、< > ; = # { } を含まないこと。

TCG locker：購入者はチェックアウトでロッカーを選びます。南アフリカの住所に対してのみ提供され、ShipLogic の API キーがある場合にのみ提供されます。既定値：オフ。

Locker option name：チェックアウトに表示されるロッカーオプションの名前。既定値：The Courier Guy locker。クーリエ名と同じルールが適用されます。

Tax status：両方のオプションの税クラス。税クラスを設定すると、リアルタイム料金は税抜きで取得され、OpenCart がそのクラスの税を加算します。None (live rates including VAT)（既定値）：リアルタイム料金は税込みで取得されます。

Sort order：チェックアウトで配送方法の中に表示される位置。整数。

ShipLogic API

API key：The Courier Guy ポータルで取得した ShipLogic API キーです。購入者に表示されることも、ログに書き込まれることもありません。保存後、このフィールドは空になり、Saved - leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。Remove the saved API key にチェックを入れて保存すると削除されます。

Account ID：任意。ShipLogic のアカウント ID（数値）です。キーが複数のアカウントにアクセスできる場合にのみ必要です。数値でない値は保存されません。

リアルタイム料金（南アフリカの住所向け。リアルタイム料金がない場合は料金表が使われます）

リアルタイム料金は、発送元住所から購入者の住所（クーリエ）または購入者の都市に最も近いロッカー（ロッカー）までの、ShipLogic で最も安いサービスの料金です。API キー、発送元住所、そしてストアの通貨がランドでない場合は換算レートが必要です。

Price source：料金の取得元。

ZAR conversion rate：ShipLogic は南アフリカランド（ZAR）で料金を提示します。ストアの既定の通貨が ZAR でない場合は、1 ZAR がストアの通貨でいくらになるかを入力してください（例：0.05）。0 より大きい値である必要があります。これがないと、リアルタイム料金は使われず、料金表が適用されます。ストアの通貨が ZAR の場合は、空欄のままにしてください。レートは自動では更新されません。

発送元住所（The Courier Guy が南アフリカで荷物を集荷する住所）

OpenCart のストア住所は自由入力のテキストのため、発送元住所はここで入力します。リアルタイム料金には、番地、市、州、郵便番号が必要です。

Sender company：会社名。

Sender street address：例：12 My Road。

Sender suburb：発送元住所の地区。

Sender city：発送元住所の市。

Sender province：リストから南アフリカの 9 つの州のうち 1 つを選択します。

Sender postal code：発送元住所の郵便番号。

料金表（ストアの既定の通貨で、税抜きの独自料金。Price table only と併用、南アフリカ以外、およびリアルタイム料金がない場合に使用されます。小数点はカンマでもピリオドでも入力できます）

Calculation type：料金表にのみ適用されます。リアルタイム料金は常に注文全体に対して算出されます。

Prices by weight：国の表で、Price 列と重量帯 XS（1 kg まで）、S（2 kg まで）、M（3 kg まで）、L（5 kg まで）、XL（5 kg 超）があります。Add row をクリックして行を追加し（新しい行は南アフリカから始まります）、削除ボタンで行を削除します。空欄または 0 の重量帯は Price 列を使用します。料金が 0 の場合は送料無料を意味します。* Any country の行は、独自の行がない国と、料金が 1 つもない国の行に適用されます。数値ではない料金は消去され、ページに一覧表示されます。

Fallback cost：リアルタイム料金も料金表の料金もない場合に使われる料金。この場合にオプションを非表示にするには、空欄のままにします。

条件（両方のオプション）

Min weight (kg)：カートの重量がこの値より低い場合、オプションを非表示にします。0 は制限なし（既定値）です。

Max weight (kg)：カートの重量がこの値より高い場合、オプションを非表示にします。既定値：30。0 は制限なし、空欄は 30 kg を意味します。Min weight (kg) が Max weight (kg) より大きい場合、ページに警告が表示され、両方の制限値は以前の値のままになります。

Minimum order amount：カートの小計がこの金額以上の場合にのみオプションを表示します（配送が必要な商品、税抜き、割引適用後）。空欄の場合は常に表示します。

Free shipping from：この金額以上のカート小計で送料が無料になります。空欄の場合は送料無料を提供しません。小計がこの金額に達すると、オプションは料金 0 で表示され、料金の照会は ShipLogic に送信されません。

提供状況

Geo zone：このジオゾーン内の住所に対してのみオプションを提供します。All zones（既定値）はすべての住所を意味します。ジオゾーンは System > Localisation > Geo Zones で管理します。

Ignore shipping zones：下記の配送の種類では、ジオゾーンを確認しません。代わりに、下記の国でオプションを提供します。

Delivery type without zones：Courier to the door（既定値）または TCG locker (customer chooses a locker)。Ignore shipping zones を使用する場合にのみ利用されます。もう一方の種類は引き続き Geo zone に従います。

Countries：そのモードの配送先の国。Ignore shipping zones を使用する場合にのみ利用されます。空欄の場合はすべての国を許可します。ロッカーは南アフリカでのみ提供されます。

詳細

Debug log：デバッグメッセージを storage/logs/vfd_tcgr_debug.log.php に書き込みます。このファイルはウェブから読み取ることができません。このオプションがオフでも、API エラーは常に記録されます。API キーと購入者のデータは決して記録されません。ファイルが 5 MB に達すると、新しいログが開始されます。

Log：ログのサイズと最新のエントリを表示します。Clear log をクリックすると空になります。

Remove data on uninstall：オンにすると、拡張機能をアンインストールした際に、設定、ログ、注文のないチェックアウトのロッカー選択が削除されます。キャッシュされた料金とロッカーは常に削除されます。注文に保存されたロッカーと追跡参照番号は常に保持されます。

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

Export：Download JSON をクリックすると、設定が JSON ファイルとして保存されます。API キーはエクスポートされません。

Import：以前にエクスポートした JSON を貼り付け、Import をクリックすると、設定を復元できます（例：別のストアで）。値は通常の保存と同じように検証されます。保存済みの API キーは維持されます。

チェックアウトでの動作

OpenCart が配送方法を表示する際、拡張機能に各オプションの料金を問い合わせます。オプションは Geo zone の条件（または Ignore shipping zones を使う場合は国のリスト）を満たす必要があります。Requires Shipping が Yes に設定された商品のみが対象です。それ以外の商品は重量に加算されず、注文金額にも含まれません。その後、拡張機能は条件を確認します。カートの重量と最低注文金額です。注文金額は、配送が必要な商品の税抜き・クーポン割引後の価格です。送料無料が適用される場合、料金は 0 になります。

Courier to the door：拡張機能は、発送元住所から購入者の住所までの ShipLogic で最も安いサービスを問い合わせます。住所には、番地、市、州、郵便番号が必要です。それまでは料金表が使われます。

TCG locker：リアルタイム料金は、ドアからロッカーまでの最も安いサービスで、購入者の都市に最も近いロッカーまでの料金です。購入者が選んだロッカーに対して再計算されることはありません。ロッカーのオプションは、南アフリカの住所で、かつ API キーがある場合にのみ表示されます。

注文全体は 1 つの荷物として見積もられます：合計重量、最長の長さと幅、積み重ねた高さです。寸法のない商品は 10 cm の立方体として扱われます。重量と寸法は、商品の重量クラスと長さクラスから換算されます。ランドの金額はストアの既定の通貨に換算され、その通貨の小数点桁数で丸められ、選択された税クラスの税を含めて購入者の通貨で表示されます。

ShipLogic へのリクエストは 12 秒でタイムアウトします。料金は 1 時間、ロッカーは 6 時間、失敗は 10 分間キャッシュされるため、応答の遅い API によってチェックアウトの更新が毎回遅くなることはありません。リアルタイム料金がない場合は、料金表の料金が使われ、次に Fallback cost が使われます。どちらも適用されない場合は、そのオプションは非表示になります。API のエラーは購入者に表示されることはありません。

拡張機能は、荷物の予約、送り状やラベルの作成、追跡情報の自動更新を行いません。ロッカーの地図はなく、ロッカーはリストから選びます。リアルタイム料金とロッカーは南アフリカのみが対象です。その他の国では料金表が使われます。オプションごとに表示される料金は 1 つだけ（最も安いサービスレベル）で、チェックアウトでサービスレベル、保険、追加オプションを選ぶことはできません。

OpenCart 4 では、購入者はチェックアウトの配送方法ブロックにある Choose をクリックし、Shipping method options ウィンドウでクーリエまたはロッカーのオプションを選びます。この方法は OpenCart 3 と同じように動作します。

受け取りポイント

購入者が配送方法の手順でロッカーのオプションを選ぶと、その下にロッカーセレクターが表示されます。検索欄（既定では配送先住所の都市）と、名前、住所、営業時間を含むロッカーの一覧です。購入者は別の都市、地区、郵便番号を入力して Search をクリックできます。次に進むにはロッカーを 1 つ選ぶ必要があります。選ばないと、この手順では Please choose a The Courier Guy locker. と表示されます。

ロッカーは、購入者が次に進んだときと、注文を確定したときの 2 回、ShipLogic の一覧に照らしてサーバー側で確認されます。名前と提供業者は ShipLogic から取得され、ブラウザからは取得されません。選択内容は配送先住所の国と都市または郵便番号に紐づいています。配送先住所を変更した場合、購入者は選び直す必要があります。

ShipLogic に接続できない場合、セレクターには Lockers cannot be loaded right now. You can place the order without choosing one - the store will contact you about the locker. と表示されます。その場合は、ロッカーを選ばずに注文を確定できます。注文は管理画面の注文ページで「ロッカー未選択」として表示されます：Not chosen - ShipLogic was unavailable at checkout. Agree the locker with the customer.

OpenCart 4 では、ロッカー選択機能は Shipping method options ウィンドウのロッカーオプションの下に表示され、ウィンドウを開くたびに再読み込みされます。ワンページチェックアウトでは住所が変わることがあるためです。ウィンドウの Continue ボタンは、一覧からロッカーを選ぶまで先に進まず、同じメッセージが表示されます。ShipLogic が利用できない場合でも注文はブロックされません。OpenCart 4 は、チェックアウト用に 1 つの注文を保持し、購入者が再度確認するたびに更新します。注文のロッカーも一緒に更新されます。

注文

選択されたロッカーは、注文の配送方法に追加されます（例：「The Courier Guy locker: 名前 — 住所」）。このテキストは Sales > Orders、購入者の注文ページ、請求書、注文メールに表示されます。

Sales > Orders の注文ページには、The Courier Guy で発送された注文ごとに、履歴の上に The Courier Guy パネルが表示されます。ロッカー注文の場合は、ロッカーの名前、ID、提供業者が表示されます。ロッカーを確認できなかった場合は not verified (ShipLogic was unavailable at checkout)、チェックアウト時に ShipLogic が利用できなかった場合は Not chosen のメッセージが表示されます。このパネルは拡張機能が無効になっていても表示されます。

The Courier Guy tracking reference：The Courier Guy ポータルで荷物を予約し、その参照番号をパネルのこの欄に入力して Save をクリックします。欄を空にして保存すると削除されます。注文を変更する権限のない管理者ユーザーは、参照番号を読み取り専用で確認できます。購入者は、アカウントの注文ページ（登録済みの購入者）と、購入者に通知した際の注文ステータスのメールで参照番号を確認できます。参照番号は後から入力されるため、新規注文のメールには含まれません。

ライセンスキー

この拡張機能は、vibefox.net で取得した VibeFox ライセンスキーを使用します。ライセンスブロック License — VibeFox The Courier Guy は、Extensions > Extensions > Shipping > VibeFox The Courier Guy > Edit ページの設定の上にある最初のブロックです。キーを License key に貼り付け、Activate をクリックします。その後、ブロックにはキーがマスクされた状態で表示され、ステータス（例：ライセンスの有効期限日とお使いのドメイン）と、ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key のボタンが表示されます。その下には Product: opencart-shipping-the-courier-guy の行と、vibefox.net のアカウントを開くリンク Manage licenses and domains in your account があります。拡張機能に対する Modify 権限を持つ管理者ユーザーだけがキーを変更できます。ブロックの表示テキストは管理画面の言語に従います（英語とロシア語が含まれます）。

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

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

有効なキーがない場合、The Courier Guy の 2 つのオプション（クーリエ配送またはTCG locker）のどちらもチェックアウトで購入者に表示されず、料金も計算されません。同じブラウザで管理画面にログインしている管理者ユーザーには、ストアでオプションが表示され、(unlicensed — visible to admins only) と表示されます。そのため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 ではこのプレビューは利用できません。ストアは管理画面のログインを認識しないため、有効なキーがない場合はすべてのユーザーに対してオプションが非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると 7 日間非表示になります。既存の注文には影響しません。

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

トラブルシューティング

The Courier Guy does not appear at checkout：ライセンスが有効であり、オプションがオンになっていることを確認してください（Courier to the door または TCG locker）。Geo zone（または Ignore shipping zones と Countries）、重量制限、Minimum order amount を確認してください。料金表または Fallback cost に料金が設定されているか確認してください。商品の Requires Shipping が Yes に設定されているか確認してください。ロッカーのオプションは、南アフリカの住所で、かつ API キーがある場合にのみ表示されます。

Customers see no locker list：ロッカーには API キー、TCG locker のオン、南アフリカの配送先住所が必要です。設定ページには、直近の ShipLogic エラーがあればそれが表示されます（例：キーが拒否された場合）。

The price is always the table price：設定ページの警告を確認してください。リアルタイム料金には、API キー、発送元住所の完全な入力、そして（ストアの通貨がランドでない場合）ZAR 換算レートが必要です。クーリエ配送では、購入者の住所に番地、市、州（ゾーン）、郵便番号が必要です。ロッカーの場合は、ShipLogic が購入者の都市の近くにロッカーを見つける必要があります。Debug log をオンにし、チェックアウトを再読み込みして、拡張機能のページにある Log の欄を確認してください。

ShipLogic is down：料金表またはフォールバック料金が表示されます。ロッカー注文はロッカーなしで行うことができ、注文上でフラグが付きます。

Rates look outdated after a change：拡張機能のページで Save をクリックしてください。キャッシュされた料金とロッカーが消去されます。

The page says "Warning: You do not have permission to modify VibeFox The Courier Guy!"：管理者ユーザーグループが設定を閲覧するだけの権限しか持っていない可能性があります。System > Users > User Groups で、そのグループに extension/shipping/vfd_the_courier_guy（OpenCart 3）または extension/vfd_the_courier_guy/shipping/vfd_the_courier_guy（OpenCart 4）の変更権限を付与してください。

For developers：ShipLogic API のアドレスは、設定 vfd_tcgr_api_url（テスト用）で置き換えられます。設定ページにはこの項目の欄はありません。

アンインストール

Extensions > Extensions に移動し、種類 Shipping を選んで、VibeFox The Courier Guy の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは常に削除されます。OpenCart は、拡張機能のステータス、Sort order、Tax status、Geo zone を常にリセットします。キャッシュされた料金とロッカー、および直近の ShipLogic エラーは常に削除されます。Remove data on uninstall がオンの場合は、設定、ログ、注文のないチェックアウトのロッカー選択も削除されます。オフの場合、その他の設定は保持され、拡張機能を再インストールしたときに再び使われます。注文に保存されたロッカーと追跡参照番号は決して削除されず、既存の注文は配送方法と料金をそのまま保持します。

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

The Courier Guy と ShipLogic は、それぞれの所有者の商標です。本拡張機能は、The Courier Guy や ShipLogic とは提携しておらず、これらの企業による支持も受けていません。