VibeFox The Courier Guy for PrestaShop — ヘルプ
要件
PrestaShop：8.0 ～ 9.x。
PHP：8.0 以降。古いバージョンの PHP ではモジュールをインストールできません。
ShipLogic API キー（リアルタイム料金とロッカー用）：The Courier Guy は ShipLogic プラットフォーム上で稼働しています。The Courier Guy の宅配ポータルで、Settings > API Keys から API キーを作成してください（ビジネスアカウント）。キーがない場合は料金表のみが使用され、ロッカーの配送業者は提供されません。
南アフリカへの配送：リアルタイム料金とロッカーは南アフリカの住所に限られます。南アフリカがストアの有効な国である必要があります（International > Locations > Countries）。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインでのみ有効です。
インストール
1. 管理画面で Modules > Module Manager を開き、Upload a module をクリックします。モジュールの ZIP ファイルを選択してください。
2. アップロードが完了したら Configure をクリックします。後でモジュール一覧から VibeFox The Courier Guy を探し、Configure をクリックすることもできます。
3. Configure ページ上部のライセンスブロックにある License key 欄に VibeFox ライセンスキーを貼り付け、Activate をクリックします（ライセンスキーのセクションを参照）。
4. ShipLogic の API key を入力します。リアルタイム料金を使う場合は発送元住所（番地、市区町村、州、郵便番号）を入力し、ストアの通貨が ZAR でない場合は ZAR conversion rate も入力します。
5. 料金表や代替料金を入力し、Save をクリックします。
6. リアルタイムの宅配料金を使う場合、ページに南アフリカの住所に州がないと表示されたら、Advanced セクションの Add South African provinces をクリックします。
インストール時、モジュールは 2 つの配送業者を作成します。The Courier Guy（配送日数の表示テキスト The Courier Guy courier delivery to your door）と The Courier Guy locker（Delivery to a TCG locker of your choice）です。どちらも有効で、南アフリカのゾーンとすべての顧客グループに紐づけられます。ゾーン、顧客グループ、配送日数、ロゴ、サイズの上限は Shipping > Carriers で変更できます。料金はそこで設定しないでください。料金は常にモジュールから取得されます。
設定
すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox The Courier Guy > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。保存するたびに、キャッシュされた料金とロッカー、および最後の ShipLogic エラーが消去されます。ページ上部の警告は、南アフリカがストアの有効な国でない場合、API キー、ZAR 換算レート、または発送元住所が未入力の場合、料金表も代替料金もない場合、南アフリカの住所に州がない場合、ストアの重量または寸法の単位をモジュールが認識できない場合、または直近の ShipLogic リクエストが失敗した場合（日時とエラーを含む）に表示されます。負の数など無効な数値は保存されません。ページがそのフィールドを示し、以前の値を保持します。
一般
Courier to the door：宅配の配送業者を有効または無効にします。Shipping > Carriers の配送業者のステータスと同じスイッチです。
Courier carrier name：チェックアウトに表示される宅配業者の名前。既定値：The Courier Guy。必須。
TCG locker：ロッカーの配送業者を有効または無効にします。購入者はチェックアウトでロッカーを選択します。南アフリカの住所にのみ提供され、ShipLogic の API キーがある場合に限られます。
Locker carrier name：チェックアウトに表示されるロッカーの配送業者の名前。既定値：The Courier Guy locker。必須。
Tax status：両方の配送業者の税ルール。Taxable: <tax rule>：リアルタイム料金は税抜きで取得され、PrestaShop が選択したルールの配送税を追加します。None：リアルタイム料金は税込みで取得されます。
ShipLogic API（リアルタイム料金とロッカー）
API key：The Courier Guy のポータルで取得した ShipLogic API キー。購入者に表示されることはなく、ログにも書き込まれません。保存後、フィールドは空になり、Saved - leave empty to keep it. と表示されます。変更する場合のみ新しい値を入力してください。Remove the saved API key にチェックを入れて保存すると、保存済みのキーを削除できます。
Account ID：任意。複数のアカウントにアクセスできるキーの場合のみ、ShipLogic の数値のアカウント ID を入力します。数値でない値は保存されません。
リアルタイム料金（南アフリカの住所向け。リアルタイム料金が利用できない場合は料金表を使用）
Price source：料金の取得元。
ZAR conversion rate：ShipLogic は南アフリカ・ランド（ZAR）で見積もります。ストアの既定通貨が ZAR でない場合は、1 ZAR がストアの通貨でいくらかを入力してください（例：0.05）。この値がないとリアルタイム料金は使われず、料金表が適用されます。ストアの通貨が ZAR の場合は空欄のままにしてください。レートは自動更新されません。
発送元住所（リアルタイム料金用）（南アフリカで The Courier Guy が荷物を集荷する場所。リアルタイム料金には番地、市区町村、州、郵便番号が必要です）
Sender company：会社名。
Sender street address：例：12 My Road。
Sender suburb：発送元住所の地区。
Sender city：発送元住所の市区町村。
Sender province：一覧から南アフリカの州を選択します。
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 の行は、専用の行がない国と、料金が一つも入力されていない国の行に適用されます。数値でない料金は消去され、ページに一覧表示されます。
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 へ料金の問い合わせは送信されません。
配送ゾーンなしでの利用可否
通常、配送業者は Shipping > Carriers で紐づけた配送ゾーンで提供されます。
Ignore shipping zones：配送業者のゾーンに下記の国が含まれていなくても、下記の国に対して下で選んだ配送タイプの配送業者を提供します。配送業者は後から作成されたゾーンを含め、有効なすべてのゾーンに紐づけられます。このオプションを再度オフにすると、配送業者は以前のゾーンを取り戻します。
Delivery type without zones：Courier to the door または TCG locker (customer chooses a locker)。Ignore shipping zones と併用する場合にのみ使用されます。
Countries：このモードの配送先国。空欄にするとすべての国を許可します。ロッカーは南アフリカでのみ提供されます。
詳細設定
South African provinces：PrestaShop には南アフリカの州がありませんが、リアルタイムの宅配料金には住所の州が必要です。Add South African provinces は 9 つの州（EC、FS、GP、KZN、LP、MP、NC、NW、WC）を南アフリカの州として追加し、南アフリカの住所に州のフィールドを表示します。既に存在する州は再度追加されません。それまでは、宅配業者は料金表の料金を受け取ります。
Debug log：モジュールフォルダー内の logs/vfd_tcgr_debug.log.php にデバッグメッセージを書き込みます。このファイルは Web からは開けません。このオプションがオフでも、API のエラーは常に記録されます。API キーと顧客データは決して記録されません。
Log：ログのサイズと最新の記録を表示します。Clear log をクリックするとログを空にできます。
Remove data on uninstall：オンの場合、モジュールをアンインストールすると、その設定と配送業者が削除されます。オフの場合、アンインストールでは配送業者が無効になるだけです。注文に保存されたロッカーは常に保持されます。
チェックアウトでの動作
配送ステップで PrestaShop は、各配送業者の料金をモジュールに問い合わせます。対象は実物商品のみです。仮想商品は重量に加算されず、注文金額にも含まれません。モジュールはまず条件を確認します：カートの重量と最低注文金額です。無料配送が適用される場合、料金は 0 になります。
Courier to the door：モジュールは、発送元住所から購入者の住所までの最も安い ShipLogic サービスを問い合わせます。住所には番地、市区町村、州、郵便番号が必要です。それまでは料金表を使用します。
TCG locker：リアルタイム料金は、購入者の市区町村に最も近いロッカーまでの、戸口からロッカーまでの最も安いサービスです。購入者が選んだロッカーに対して再計算されることはありません。ロッカーの配送業者は、南アフリカの住所に対してのみ、かつ API キーがある場合にのみ表示されます。
注文全体は 1 つの荷物として計算されます：合計重量、最長の縦と横、積み重ねた高さです。寸法のない商品は 10 cm の立方体として扱われます。重量と寸法は、ストアの単位から変換されます。ランドの金額は既定の通貨に変換され、その後、購入者のカートの通貨で表示されます。
ShipLogic へのリクエストは 12 秒でタイムアウトします。遅い API によってチェックアウトの更新が毎回遅くならないよう、料金は 1 時間、ロッカーは 6 時間、失敗は 10 分間キャッシュされます。リアルタイム料金がない場合は料金表から、それもない場合は Fallback cost から料金を取得します。どれも適用されない場合は、配送業者を非表示にします。API のエラーが購入者に表示されることはありません。
配送業者は Classic テーマと Hummingbird テーマで動作します。配送業者に注文がある状態で Shipping > Carriers から編集すると、PrestaShop はそれを新しいバージョンの配送業者として保存します。モジュールは新しいバージョンに自動的に従います。
モジュールは配送の手配、送り状やラベルの作成、追跡情報の自動更新を行いません。ロッカーの地図はなく、ロッカーはリストから選択します。リアルタイム料金とロッカーは南アフリカ向けのみです。それ以外の国は料金表を使用します。配送業者ごとに表示される料金は 1 つだけ（最も安いサービスレベル）で、チェックアウトでサービスレベル、保険、オプションを選ぶことはできません。
受け取りポイント
購入者がロッカーの配送業者を選ぶと、その下にロッカーのセレクターが表示されます。配送先住所の市区町村について ShipLogic が返すロッカーを、近い順に一覧表示します。購入者は別の市区町村、地区、郵便番号を入力して Search をクリックできます。購入者は続行する前にロッカーを選択する必要があります。選択しない場合、配送ステップに Please choose a The Courier Guy locker. と表示されます。
ロッカーは注文の確定時にも、サーバーで ShipLogic の一覧と照合されます。名前と提供業者は ShipLogic から取得され、ブラウザーの値は使用されません。選択内容はカートに保持され、配送先住所が変更されるとリセットされます。
ShipLogic に接続できない場合、セレクターにはロッカーを読み込めないこと、ストアがロッカーについて購入者に連絡することが表示されます。その場合、ロッカーを指定せずに注文できます。その注文には、管理画面の注文ページで Not chosen - ShipLogic was unavailable at checkout. Agree the locker with the customer. と表示されます。
注文
選択されたロッカー（名前、ID、提供業者）は注文とともに保存されます。管理画面の注文ページの The Courier Guy ブロック、注文確認ページ、購入者の注文詳細、注文確認メールに表示されます。ストアの「新規注文」メール（Mail alerts モジュール）にもロッカーの ID が表示されます。ShipLogic が利用できなかったためロッカーが選択されなかった場合は、その旨が表示されます。
The Courier Guy の追跡番号：The Courier Guy のポータルで荷物を手配し、その参照番号を注文の Shipping ブロック（Edit）で配送の追跡番号として入力してください。The Courier Guy ブロックに表示されます。購入者は注文詳細でこれを確認でき、PrestaShop から「配送中」のメールを受け取ります。
ライセンスキー
本モジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox The Courier Guy は、Modules > Module Manager > VibeFox The Courier Guy > Configure ページの一番上のブロックで、設定より上にあります。キーを License key 欄に貼り付け、Activate をクリックします。その後、ブロックにはマスクされたキー、ステータス（ライセンスの有効期限日とドメインなど）、および Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）のボタンが表示されます。その下には Product: presta-shipping-the-courier-guy の行と、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 のアカウントで枠を解放してください。
有効なキーがない場合、The Courier Guy の配送業者（courier to the door または TCG locker）はチェックアウトで購入者に表示されず、料金も計算されません。PrestaShop のフロントエンドは管理画面にログインしていることを認識しないため、配送業者はあなたにも表示されません。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。
ライセンスの有効期限が切れてもモジュールは動作を続けますが、アップデートとサポートには更新が必要です。ステータスは管理画面での作業中に自動的に再確認されます。キー入力後の最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールをアンインストールすると、ライセンスキーとライセンスステータスは常に削除されます。このモジュールの Reset ではデータは削除されないため、キーとステータスは保持されます。
トラブルシューティング
チェックアウトに The Courier Guy が表示されない：ライセンスが有効で、配送業者（Courier to the door または TCG locker）がオンになっているか確認してください。Shipping > Carriers で、配送業者が購入者の国のゾーンと顧客グループを対象としているか確認します（または Ignore shipping zones がオンで、その国が許可されているか確認します）。重量の上限と Minimum order amount を確認してください。料金表または Fallback cost に料金が設定されているか確認します。ロッカーの配送業者は、南アフリカの住所で、かつ API キーがある場合にのみ表示されます。また、商品ページで商品が特定の配送業者に限定されている場合もあります。
購入者にロッカーの一覧が表示されない：ロッカーには API キー、TCG locker 配送業者のオン、南アフリカの配送先住所が必要です。設定ページには、最後の ShipLogic エラーがあれば表示されます（例：キーが拒否された場合）。
料金が常に料金表の額になる：設定ページの警告を確認してください。リアルタイム料金には、API キー、完全な発送元住所、そして rand 以外の通貨のストアでは ZAR 換算レートが必要です。宅配の場合、購入者の住所には番地、市区町村、州、郵便番号が必要です。Advanced セクションで南アフリカの州を追加してください。ロッカーの場合、ShipLogic は購入者の市区町村の近くにロッカーを見つける必要があります。Debug log をオンにし、チェックアウトを再読み込みして、モジュールページの Log フィールドを確認してください。
ShipLogic が利用できない：料金表または代替料金が表示されます。ロッカーを指定した注文は、ロッカーなしで注文でき、注文上でフラグが付けられます。
変更後に料金が古いようだ：モジュールページで Save をクリックしてください。キャッシュされた料金とロッカーが消去されます。
The Courier Guy の配送業者が見つからないと表示される：配送業者は Shipping > Carriers で削除されています。Modules > Module Manager でモジュールをリセットすると、再作成されます。リセットしても、設定と既存の配送業者のオン／オフの状態は保持されます。
アンインストール
Modules > Module Manager に移動し、VibeFox The Courier Guy の横のメニューを開いて Uninstall を選択します。ライセンスキーとライセンスステータスは常に削除されます。キャッシュされた料金とロッカー、および最後の ShipLogic エラーは常に削除されます。Remove data on uninstall がオンの場合、配送業者は削除されます（注文は履歴を保持します）。また、設定、ログ、注文のないカートのロッカーも削除されます。オフの場合、配送業者はオフになるだけで、すべての設定は保持されます。モジュールを再インストールすると、配送業者は以前の状態を取り戻します。注文に保存されたロッカーは決して削除されません。
The Courier Guy と ShipLogic は、それぞれの所有者の商標です。本モジュールは The Courier Guy または ShipLogic と提携しておらず、両社の承認も受けていません。