VibeFox Cargoson for PrestaShop — ヘルプ
要件
PrestaShop: 8.0 から 9.x。
PHP: 8.0 以降。モジュールは古い PHP バージョンではインストールできません。
Cargoson アカウント（リアルタイム料金のみ）: リアルタイム料金には Cargoson の運賃料金 API を使用します。運賃料金の照会には、API アクセスを含む Cargoson のサブスクリプション（執筆時点では Advanced プラン以上）が必要です。API キーは Cargoson アカウントで発行されます。プランに API 設定が表示されない場合は、Cargoson サポートにお問い合わせください。料金は、そのアカウントに接続された配送業者と料金表から提供されます。固定料金のみを使用する場合は、Cargoson アカウントは不要です。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインでのみ使用できます。
インストール
1. バックオフィスで Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択してください。
2. アップロードが完了したら Configure をクリックします。後でモジュール一覧から VibeFox Cargoson を見つけて、Configure をクリックすることもできます。
3. Configure ページ上部のライセンスブロックの License key に VibeFox ライセンスキーを入力し、Activate をクリックします（「ライセンスキー」を参照）。
4. 配送料の計算方法を選択し、該当するセクションに入力します。固定料金、およびリアルタイム料金の場合は API キーと集荷郵便番号です（設定を参照）。Save をクリックします。
インストール時に、モジュールは配送日数のテキスト Delivery by the cheapest Cargoson carrier を持つ Cargoson 配送業者を作成します。配送業者はすべてのゾーンとすべての顧客グループに割り当てられます。ゾーン、顧客グループ、配送日数、ロゴ、サイズ制限は Shipping > Carriers で変更できます。ここでは料金を設定しないでください。料金は常にモジュールから取得されます。
設定
すべての設定はモジュールページにあります: Modules > Module Manager > VibeFox Cargoson > Configure。これらは配送業者のすべてのゾーンに適用されます。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。保存後は Settings saved. Cached Cargoson prices were cleared. と表示されます。小数はピリオドまたはカンマで入力できます。数値欄にテキストや負の数が含まれている場合、Currency conversion rate が 0 の場合、Minimum weight が Maximum weight より大きい場合、Method title が 64 文字を超える場合、Price currency が 3 文字の通貨コードでない場合、または料金表の行に無効な国コードまたは料金がある場合は、何も保存されず、ページにエラーが表示されます。モジュールがショップの重量単位を認識できない場合、保存後に、商品の重量はキログラムとして扱われるという警告が表示されます。その場合は International > Localization（Local units）で単位を設定してください。
General
Enable Cargoson: 配送業者を有効または無効にします。Shipping > Carriers の配送業者のステータスと同じスイッチです。
Method title: カートとチェックアウトに表示される配送業者名。デフォルト: Cargoson。必須項目です。Shipping > Carriers の配送業者名にもなります。
Shipping cost: 料金の計算方法。
リアルタイム料金が表示されない理由は、モジュールのログに記録されます。購入者に表示されることはありません。
Cargoson API（リアルタイム料金にのみ必要）
API key: Cargoson アカウントの API キー。Cargoson にのみ送信され、購入者に表示されたりログに記録されたりすることはありません。保存後、この欄は空になり、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。
Remove the saved API key: キーが保存されているときに表示されます。オンにして保存すると、キーが削除されます。
Carrier: 使用する料金。購入者に表示される料金は 1 つです。
Package type code: 料金照会とともに送信される Cargoson の梱包タイプコード。デフォルト: CLL。Cargoson API の例では EUR（EUR パレット）と FIN（FIN パレット）が使われています。小包には、Cargoson アカウントの梱包コードを使用してください。注文は、カートの合計重量を持つ 1 つの荷物として送信されます。
Price currency: Cargoson アカウントにある料金の通貨。3 文字のコードで指定します。デフォルト: EUR。API は通貨コードなしで金額を返します。
Currency conversion rate: 料金の通貨がショップのデフォルト通貨と異なる場合にのみ必要です: Cargoson 通貨 1 単位 = デフォルト通貨 X 単位。このような料金を拒否するには空欄のままにします。そうすれば、購入者が誤った通貨で支払うことはありません。
発送元（集荷先住所）（リアルタイム料金に使用）
Collection country: 発送元の国。デフォルトはショップの国です。
Collection postcode: 発送元の郵便番号。Cargoson で必須です。空欄で、集荷国がショップの国の場合は、Shop Parameters > Contact > Stores にあるショップの郵便番号が使用されます。
Cargoson に送信される集荷日は、ショップのタイムゾーンでの当日です。週末の場合は翌週の月曜日になります。
固定料金（Shipping cost が Fixed prices の場合に使用され、リアルタイム料金のフォールバックとしても使用されます）
Price per country and size: Country 列（2 文字の国コード）、Price 列、そしてショップのデフォルト通貨（税抜き）でカート重量ごとの料金を示す表です: XS は 1 kg まで、S は 2 kg まで、M は 3 kg まで、L は 5 kg まで、XL は 5 kg 超です。サイズの料金が空欄または 0 の場合は Price 列の値が使用されます。Price が空欄の場合は、そのサイズの固定料金がないことを意味します。行を追加するには Add country をクリックし、削除するにはごみ箱アイコンをクリックします。独自の行を持たないすべての国には、国コードとして * を使用します。行のない国（* の行がない場合）には固定料金がないため、その国では配送業者が表示されません。料金は 0 以上の数値でなければなりません。空の行は無視されます。
Fixed price applies: Per order は料金を 1 回だけ請求します。Per item (price × quantity) は、カート内の商品数を掛けて請求します。Cargoson のリアルタイム料金は、常に 1 出荷ごとです。
条件
Minimum weight: このカート重量未満の場合は配送業者を非表示にします（単位: kg）。0 は制限なしを意味します。
Maximum weight: このカート重量を超える場合は配送業者を非表示にします（単位: kg）。デフォルト: 25。0 は制限なしを意味します。
Minimum order amount: カートの小計（割引後、税抜き）がこの金額以上の場合にのみ配送業者を表示します。空欄にすると、常に表示されます。
Free shipping: 下記の注文金額に達したときに、送料無料を有効にします。
Free shipping from: 送料が無料になるカート小計（割引後、税抜き）。Free shipping が有効な場合にのみ使用されます。
Tax: 配送業者の税ルール、または No tax。Cargoson の配送料は通常、税抜き（付加価値税なし）です。料金にすでに税が含まれている場合は、No tax を選択してください。
配送ゾーンを使わない場合の提供
通常、配送業者は Shipping > Carriers で割り当てられたゾーンで提供されます。
Ignore shipping zones: 配送業者に割り当てられているゾーンに関係なく、下記の国向けに Cargoson を提供します。オンにして保存すると、配送業者はすべてのゾーンに割り当てられます。後から作成したゾーンにも割り当てられます。オフにして保存すると、配送業者は以前のゾーンを取り戻します。
Countries: このモードの配送先国。空欄にすると、配送している国（有効な国）がすべて使用されます。このフィールドは Ignore shipping zones がオンの場合にのみ使用されます。
詳細設定
Debug log: すべての料金計算を、モジュールフォルダ内の logs/vfd_cgs_debug.log.php に記録します。このファイルは Web から開くことはできません。このオプションがオフでも、API エラーと拒否された料金は常に記録されます。API キーと購入者の郵便番号は、決して記録されません。
Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログが空になります。
Remove data on uninstall: オンの場合、モジュールをアンインストールすると、Cargoson の設定、配送業者、キャッシュされた料金、注文の見積もり、ログが削除されます。オフの場合は、再インストールに備えてすべて保持されます。
チェックアウト時の動作
配送ステップで、PrestaShop はモジュールに Cargoson の料金を問い合わせます。対象となるのは実物の商品のみです。バーチャル商品は重量に加算されず、注文金額にも含まれません。商品の重量は、ショップの単位からキログラムに変換されます。モジュールはまず条件を確認します。配送先の国、カートの重量、最低注文金額です。送料無料が適用される場合、料金は 0 となり、Cargoson へのリクエストは送信されません。
固定料金モードでは、料金は表から取得されます。リアルタイムモードでは、モジュールは Cargoson に、集荷日、集荷国と郵便番号、配送先の国と郵便番号、そして梱包タイプコードとカートの合計重量（最低 0.1 kg）を持つ 1 つの荷物を送信します。リアルタイム料金は、配送先住所に郵便番号がある場合にのみ問い合わせられます。Cargoson は、登録済みの配送業者の料金を返します。モジュールは最も安い料金を選択し（配送業者が選択されている場合は、その中から）、必要に応じてショップのデフォルト通貨に換算します。料金はショップのデフォルト通貨で計算され、その後、購入者のカートの通貨で表示されます。
各応答は 1 時間キャッシュされるため、同じカートで新たなリクエストが発生することはありません。失敗したリクエストは 10 分間キャッシュされるため、チェックアウトは画面を更新するたびに Cargoson の応答を待つ必要がありません。API のタイムアウトは 10 秒です。Cargoson がエラーを返した場合、そのルートの料金がない場合、または換算レートがないまま別の通貨の料金が返された場合でも、購入者にはエラーが表示されません。配送業者は非表示になるか、フォールバックモードでは固定料金が使用されます。
注文がある配送業者を Shipping > Carriers で編集した場合、PrestaShop はそれを配送業者の新しいバージョンとして保存します。モジュールは新しいバージョンに自動的に追従します。
モジュールは料金の計算のみを行います。Cargoson での出荷や予約の作成、ラベルの印刷、荷物の追跡は行わず、購入者はパーセルマシンや受け取り場所を選択することもできません。カートは合計重量の 1 つの荷物として見積もられ、荷物のサイズは送信されません。表示されるのは最も安い料金 1 つだけで、配送業者の一覧は表示されません。
注文
Cargoson の注文ページには、チェックアウト時に計算された料金を示す Cargoson shipping ブロックが表示されます:
Carrier、Service、Cargoson service ID: 見積もりを出した Cargoson の配送業者とサービス。リアルタイム料金が使用された場合に表示されます。
Price source: Cargoson live price、Fixed price、または Free shipping threshold。
Calculated price (excl. tax): ショップのデフォルト通貨での料金。
見積もりは注文時に保存され、後から変更されることはありません。Cargoson、またはその独自の連携機能で出荷を予約してください。
ライセンスキー
本モジュールは、vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Cargoson は、Modules > Module Manager > VibeFox Cargoson > Configure ページの最初のブロックで、設定の上にあります。キーを License key に入力し、Activate をクリックします。その後、ブロックにはキーがマスクされた状態で表示され、ステータス（ライセンスの有効期限日やドメインなど）と、以下のボタンが表示されます。ステータスを再確認する Check now、別のキーを入力する Change key、このショップからキーを削除する Remove key です。その下には Product: presta-shipping-cargoson の行と、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 つのドメインでのみ使用できます。メインショップのドメインで、マルチストア構成でも同様です。ショップからキーを削除しても、ドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。
有効なキーがない場合、Cargoson の配送業者はチェックアウト時に購入者に表示されず、料金も計算されません。PrestaShop のストアフロントは、バックオフィスにログインしていることを認識しないため、配送業者はあなたにも非表示になります。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。
ライセンスの期限が切れた場合、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。バックオフィスで作業している間、ステータスは自動的に再確認されます。キー入力後の最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは必要ありません。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
Cargoson がチェックアウトに表示されない: ライセンスが有効であること、Enable Cargoson がオンであることを確認してください。Shipping > Carriers で、配送業者が購入者の国のゾーンと購入者のグループを対象にしているか確認してください（または Ignore shipping zones がオンで、その国が Countries に含まれているか確認してください）。重量制限と Minimum order amount を確認してください。固定料金モードでは、その国または * に、カートのサイズに対する料金があるか確認してください。商品ページで、特定の配送業者に制限されている場合もあります。
リアルタイム料金が表示されない: モジュールページの Log 欄を確認してください。API エラーは常に記録されます。すべての計算を確認するには Debug log をオンにしてください。よくある原因は、配送先の郵便番号が未入力、集荷郵便番号がない、API キーが拒否された（キーが誤っているか期限切れ、または Cargoson プランに API アクセスがない）、そのルートや重量に配送業者がない、または別の通貨の料金である、といったものです。Cargoson live prices, fixed prices if the API fails を使用すると、問題を修正するまでの間も、購入者は固定料金を受け取ることができます。
Cargoson が梱包タイプを拒否する: Cargoson アカウントが Package type code で使用している梱包コードを使用してください。理由はログに表示されます。
別の通貨の料金が拒否される: Price currency を Cargoson の料金の通貨に設定し、Currency conversion rate を入力してください。
配送料に税が二重に課される: Cargoson の料金にはすでに付加価値税が含まれています。Tax を No tax に設定してください。
変更後に料金が古く見える: モジュールページで Save をクリックしてください。キャッシュされた Cargoson の料金が消去されます。
ページに Cargoson 配送業者が見つからないと表示される: 配送業者が Shipping > Carriers で削除されています。Modules > Module Manager でモジュールをリセットすると、再作成されます。
アンインストール
Modules > Module Manager に移動し、VibeFox Cargoson の横のメニューを開いて Uninstall を選択します。ライセンスキーとライセンスステータスは常に削除されます。キャッシュされた料金は常に削除されます。Remove data on uninstall がオンの場合、配送業者は削除され（注文は履歴を保持します）、設定、注文の見積もり、ログも削除されます。オフの場合、配送業者は無効になるだけで、設定と確定済みの注文の見積もりは保持され、注文のないカートの見積もりのみが削除されます。モジュールを再インストールすると、保存されていた配送業者は以前のステータスに戻ります。そのため、Reset を実行しても、無効にした配送業者が有効になることはありません。
Cargoson は、それぞれの所有者の商標です。本モジュールは Cargoson と提携しておらず、Cargoson による推奨も受けていません。