VibeFox Cargoson for OpenCart — ヘルプ
要件
OpenCart：3.0.x（3.0.5.0 で動作確認済み）、または 4.0.2 以降（4.1.0.3 で動作確認済み）。
PHP：8.0 以降。
Cargoson アカウント（リアルタイム料金のみ必要）：リアルタイム料金は Cargoson の貨物運賃価格 API を使用します。運賃の見積もりには、API アクセスを含む Cargoson のサブスクリプション（執筆時点では Advanced プラン以上）が必要です。API キーは Cargoson アカウントで発行されます。プランに API 設定が表示されない場合は、Cargoson のサポートにお問い合わせください。料金は、このアカウントに接続された運送業者と料金表から取得されます。固定料金のみを使用する場合、Cargoson アカウントは不要です。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。コンピューターで解凍してください。README.txt、OpenCart 3 用パッケージ vfd_cargoson-oc3-（バージョン）.ocmod.zip、OpenCart 4 用パッケージ vfd_cargoson.ocmod.zip が含まれています。使用している OpenCart のバージョンに対応するパッケージのみをインストールしてください。ライセンスキーは両方のバージョンで同じです。
OpenCart 3
1. 管理画面で Extensions > Installer に進み、Upload をクリックして、ファイル vfd_cargoson-oc3-（バージョン）.ocmod.zip を選択します。この拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。Installer を使う代わりに、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。
2. Extensions > Extensions に進み、拡張機能の種類として Shipping を選択します。VibeFox Cargoson を見つけて、Install（緑色の + ボタン）をクリックします。
3. Edit（鉛筆のボタン）をクリックして、設定ページを開きます。
4. Edit ページの上部にある License key 欄に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーの項を参照）。
5. 送料の計算方法を選び、該当するセクションに入力します。固定料金を使うか、リアルタイム料金を使う場合は API キーと集荷先の郵便番号を入力します（設定の項を参照）。Enable Cargoson をオンにして、Save をクリックします。
OpenCart 4
1. 管理画面で Extensions > Installer に進み、Upload をクリックして、ファイル vfd_cargoson.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変更したパッケージは動作しません。
2. パッケージは、同じページのインストール済み拡張機能の一覧に表示されます。その横の Install（緑色の + ボタン）をクリックします。
3. Extensions > Extensions に進み、拡張機能の種類として Shipping を選択します。VibeFox Cargoson を見つけて、Install（緑色の + ボタン）をクリックし、次に Edit（鉛筆のボタン）をクリックします。
4. ライセンスキーと設定は、OpenCart 3 の手順 4 と 5 と同じように入力します。設定ページとそのフィールドは、両方のバージョンで同じです。
インストール後は、Enable Cargoson をオンにして保存するまで、この配送方法はオフのままです。アンインストール後に拡張機能を再インストールすると、保持した Cargoson の設定が再び使用されます。
設定
すべての設定は拡張機能のページにあります：Extensions > Extensions > Shipping > VibeFox Cargoson > Edit。セクションは左側に表示されます。ページ下部の Save ボタンを 1 回押すと、ページを再読み込みせずにページ全体が保存されます。保存後には Settings saved. Cached Cargoson prices were cleared. と表示されます。小数はピリオドまたはカンマで入力できます。Method title が空または 64 文字を超える場合、数値欄にテキストや負の数が含まれる場合、Currency conversion rate が 0 の場合、Minimum weight (kg) が Maximum weight (kg) より大きい場合、Price currency が 3 文字のコードでない場合、料金表の行に無効な国や料金がある場合、または Sort order が整数でない場合は、何も保存されず、ページにエラーが表示されます。拡張機能がストアの重量単位を認識できない場合は、保存後の警告で、商品の重量はキログラムとして扱われることが示されます。その場合は System > Localisation > Weight Classes で単位が kg の重量クラスを追加してください。この拡張機能の変更権限を持つ管理者ユーザーだけが設定を保存できます。
一般
顧客に表示されるのは Cargoson の料金 1 つです。Availability で、この方法をジオゾーンまたは国に限定できます。
Enable Cargoson：チェックアウトで Cargoson を表示するか非表示にするかを切り替えます。既定値：オフ。
Method title：カートとチェックアウトで顧客に表示される配送方法の名前です。最大 64 文字。既定値：Cargoson。必須項目です。
Shipping cost：料金の計算方法です。
リアルタイム料金が見つからない理由は、デバッグログに記録されます。顧客に表示されることはありません。
Sort order：チェックアウトの配送方法の中で Cargoson が表示される順序です。整数で指定します。
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：発送元の国です。最初の選択肢 Store country は、ストアの国を使用します。
Collection postcode：発送元の郵便番号です。リアルタイム料金に必要です。OpenCart のストア住所は自由入力のため、そこから郵便番号が取得されることはありません。ここに入力してください。
Cargoson に送信される集荷日は、ストアのタイムゾーンでの当日です。週末の場合は、次の月曜日になります。
固定料金（Shipping cost が Fixed prices の場合に使用され、リアルタイム料金の代替としても使われます）
Price per country and size：行のリストです。各行には Country、Price、そしてカート重量ごとの料金（ストアの既定通貨、税抜き）があります：XS は 1 kg まで、S は 2 kg まで、M は 3 kg まで、L は 5 kg まで、XL は 5 kg 超。サイズの料金が空または 0 の場合は Price 列が使われます。Price が空の場合は、そのサイズの固定料金がないことを意味します。Add country をクリックすると行を追加できます。自分の行がないすべての国に適用される料金には、* All other countries を選択します。行がない国（* の行もない場合）には固定料金がないため、その国ではこの方法が非表示になります。料金は 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 class：送料の税クラス、または No tax（既定値）です。Cargoson の運送業者料金は通常、税抜きです。料金にすでに税金が含まれている場合は、No tax を選択してください。
提供状況
Geo zone：この地域内の住所にのみ Cargoson を提供します。All zones（既定値）は制限なしを意味します。ジオゾーンは System > Localisation > Geo Zones で管理されます。
Ignore shipping zones：ジオゾーンは確認しません。下記の国のリストが判断基準になります。
Countries：このモードの配送先の国です。空のままにすると、すべての国が許可されます。このフィールドは Ignore shipping zones がオンの場合にのみ使用されます。
詳細
Debug log：すべての料金計算を storage/logs/vfd_cgs_debug.log.php に記録します。このファイルはウェブから読み取れません。API のエラーと拒否された料金は、このオプションがオフでも常に記録されます。API キーと顧客の郵便番号は記録されません。ファイルが 5 MB に達すると、vfd_cgs_debug.old.log.php に移動され、新しいログが開始されます。
Log：デバッグログのサイズと最新のエントリを表示します。Clear log をクリックすると消去されます。
Remove data on uninstall：オンにすると、拡張機能のアンインストール時に Cargoson の設定、キャッシュされた料金、ログが削除されます。オフ（既定値）の場合、再インストールに備えてこれらは保持されます。配送済みの注文の Cargoson 見積もりは、常に保持されます。
インポート / エクスポート
Export：Download JSON をクリックすると、設定を JSON ファイルとして保存できます。API キーはエクスポートされません。
Import：以前にエクスポートした JSON を貼り付け、Import をクリックすると、設定を復元できます（例：別のストアで）。値は通常の保存と同じように検証されます。保存済みの API キーは保持されます。
チェックアウトでの動作
OpenCart が配送方法を表示する際、拡張機能に Cargoson の料金を問い合わせます。Geo zone が設定されていて（かつ Ignore shipping zones がオフ）、住所がそのゾーン外にある場合、Cargoson は提供されません。Requires Shipping を Yes に設定した商品のみが計算に含まれます。その他の商品は重量に加算されず、注文金額にも含まれません。商品の重量は、重量クラスからキログラムに変換されます。次に拡張機能は条件を確認します。許可された国、カート重量、最低注文金額です。注文金額は、配送が必要な商品の価格で、クーポン割引後、税金の前です。ギフト券、ポイント、ストアクレジットは考慮されません。送料無料が適用される場合、料金は 0 となり、Cargoson へのリクエストは送信されません。
固定モードでは、料金は表から取得されます。リアルタイムモードでは、拡張機能は Cargoson に、集荷日、集荷国と集荷郵便番号、配送先の国と郵便番号、そして荷物タイプコードとカートの合計重量（最低 0.1 kg）を含む 1 つの荷物を送信します。リアルタイム料金は、配送先住所に郵便番号がある場合にのみリクエストされます。Cargoson は運送業者の料金を返し、拡張機能は（選択された運送業者がいればその中から）最安のものを選び、必要に応じてストアの既定通貨に換算します。料金は既定通貨で計算され、その小数桁に丸められ、選択した Tax class の税金を加えて、購入者の通貨で表示されます。
各レスポンスは 1 時間キャッシュされるため、同じカートでは新しいリクエストは発生しません。失敗したリクエストは 10 分間キャッシュされるため、チェックアウトの更新のたびに Cargoson を待つことはありません。API のタイムアウトは 10 秒です。Cargoson がエラーを返した場合、そのルートの料金がない場合、または換算レートなしで別の通貨の料金が返された場合、購入者にエラーは表示されません。この方法は非表示になるか、フォールバックモードでは固定料金が使われます。
拡張機能は料金の計算のみを行います。Cargoson での出荷や予約の作成、ラベルの印刷、荷物の追跡は行わず、購入者は宅配ロッカーや受け取り場所を選択できません。カートは合計重量の 1 つの荷物として見積もられ、荷物のサイズは送信されません。運送業者の一覧ではなく、最安の料金 1 つだけが表示されます。
OpenCart 4 では、顧客はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options ウィンドウで Cargoson を選択します。この方法は OpenCart 3 と同じように動作します。
注文
顧客が Cargoson で注文すると、チェックアウトで計算された料金が注文とともに保存されます。Sales > Orders の注文ページには、Cargoson shipping パネルが表示されます：
Carrier、Service、Cargoson service ID：見積もりの Cargoson 運送業者とサービスです。リアルタイム料金が使用された場合に表示されます。
Price source：Cargoson live price、Fixed price、または Free shipping threshold。
Calculated price (excl. tax)：ストアの既定通貨での料金です。
このパネルは、この方法がオフの場合も表示されます。OpenCart 4 では、注文は確認の手順で一度作成され、顧客がその手順に戻るたびに更新されます。そのため、保存された見積もりはチェックアウトで最後に計算されたものです。顧客が別の配送方法に切り替えた場合、その注文の Cargoson 見積もりは削除されます。管理画面で注文を変更しても見積もりは変わらず、後から変わることもありません。出荷は Cargoson で、または Cargoson の独自の連携機能を使って予約してください。
ライセンスキー
この拡張機能は、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Cargoson は、Extensions > Extensions > Shipping > VibeFox Cargoson > Edit ページの設定より上にある最初のブロックです。キーを License key に貼り付け、Activate をクリックします。その後、ブロックにはマスクされたキー、ステータス（例：ライセンスの有効期限日と、お使いのドメイン）、そしてボタンが表示されます。ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key です。その下には、Product: opencart-shipping-cargoson の行と、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 のアカウントで枠を解放してください。
有効なキーがない場合、チェックアウトで顧客に Cargoson は表示されず、料金も計算されません。管理画面に同じブラウザでログインしている管理者ユーザーには、ストアで (unlicensed — visible to admins only) と表示された状態で、この方法が引き続き表示されます。そのため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 では、このプレビューは利用できません。ストアは管理者のログインを認識しないため、有効なキーがない場合、この方法はすべてのユーザーに対して非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると 7 日間非表示になります。既存の注文には影響しません。
ライセンスの有効期限が切れた後も拡張機能は動作し続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスが自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日に 1 回、その後は週に 1 回です。cron ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスのステータスは常に削除されます。
トラブルシューティング
Cargoson がチェックアウトに表示されない：ライセンスが有効で、Enable Cargoson がオンになっているか確認してください。Geo zone（または Ignore shipping zones と Countries）、重量制限、Minimum order amount を確認してください。固定モードでは、国または * All other countries にカートサイズの料金があるか確認してください。商品の Requires Shipping が Yes になっているか確認してください。
リアルタイム料金が表示されない：拡張機能のページにある Log 欄を確認してください。API のエラーは常に記録されます。すべての計算を確認するには Debug log をオンにしてください。よくある原因：配送先の郵便番号がまだ入力されていない、Collection postcode がない、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 class を No tax に設定してください。
変更後に料金が古く見える：拡張機能のページで Save をクリックしてください。これにより、キャッシュされた Cargoson の料金が消去されます。
ページに "Warning: You do not have permission to modify VibeFox Cargoson!" と表示される：管理者のユーザーグループに設定の閲覧権限しかない可能性があります。System > Users > User Groups で、そのグループに extension/shipping/vfd_cargoson（OpenCart 3）または extension/vfd_cargoson/shipping/vfd_cargoson（OpenCart 4）の変更権限を付与してください。
開発者向け：Cargoson の API アドレスは、設定 vfd_cgs_api_url（テスト用）で置き換えられます。設定ページには、この項目の入力欄はありません。
アンインストール
Extensions > Extensions に進み、種類 Shipping を選択して、VibeFox Cargoson の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスのステータスは常に削除されます。OpenCart は常に Enable Cargoson、Sort order、Tax class、Geo zone をリセットします。キャッシュされた料金は常に削除されます。Remove data on uninstall がオンの場合、Cargoson の設定とデバッグログも削除されます。オフの場合、他の設定は保持され、拡張機能を再インストールすると再び使用されます。配送済みの注文の Cargoson 見積もりは削除されることはなく、既存の注文は、配送方法と送料をそのまま保持します。
OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に進み、インストール済み拡張機能の一覧で VibeFox Cargoson の横にある Uninstall（オレンジ色の − ボタン）をクリックし、次にアップロードしたパッケージを削除するために Delete（赤いゴミ箱のボタン）をクリックします。
Cargoson は、各所有者の商標です。この拡張機能は Cargoson と提携しておらず、同社の承認も受けていません。