VibeFox CTT for OpenCart — ヘルプ

要件

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

PHP: 8.0 以降。

CTT の e コマースアカウント（リアルタイム料金と CTT 受取拠点の場合のみ）: リアルタイム料金と CTT 受取拠点への配送には、CTT の e コマース API を使用します。enviosecommerce.ctt.pt で CTT の e コマースアカウントが必要です（CTT Expresso の契約をお持ちのお客様、または CTT に見積もりを依頼してください）。そのアカウントのキー管理ページで、公開キーと秘密キーのペアを作成します。App ID（X-APPID）は、連携のために CTT から発行されます。CTT の e コマース担当者にお問い合わせください。また、CTT は App ID で使用できる API 機能（料金見積もり、CTT 受取拠点）も決定します。最後に、アカウントの CTT Carrier ID が必要です。キーを保存すると、設定ページにアカウントの運送業者が表示されます。料金表と住所への配送のみを使用する場合、API キーは不要です。

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

インストール

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

OpenCart 3

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

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

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

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

5. 料金表を入力します（少なくとも 1 行の Portugal または * Default 行）。Enable/Disable および/または Enable CTT point option をオンにして、Save をクリックします。必要に応じて、CTT の API キー、App ID、Carrier ID を入力し、Live rates をオンにしてください（設定を参照）。

OpenCart 4

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

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

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

4. OpenCart 3 の手順 4 と 5 と同様に、ライセンスキーと設定を入力します。設定ページとそのフィールドは両方のバージョンで同じです。

初回インストール後は、どちらかの配送オプションをオンにして保存するまで、両方の配送オプションはオフのままです。データを削除せずにアンインストールしてから拡張機能を再インストールすると、保存された設定が再び使用され、いずれかのオプションがオンだった場合は拡張機能も再度有効になります。

設定

すべての設定は拡張機能のページにあります: Extensions > Extensions > Shipping > VibeFox CTT > Edit。セクションは左側に表示されます。ページ下部の Save ボタン 1 つで、ページを再読み込みせずにページ全体を保存します。料金と条件は、両方の CTT オプションに適用されます。保存するたびに、キャッシュされた CTT の応答（API トークン、運送業者、料金、CTT 拠点リスト）がクリアされます。この拡張機能の変更権限を持つ管理者ユーザーのみが設定を保存できます。

ページ上部の警告は、料金表が空であること、ポルトガルの料金がないこと、リアルタイム料金または CTT 拠点オプションがオンの間に API キーが不完全であること、Carrier ID がないこと、為替レートが未設定のままストアの通貨が EUR 以外であること、CTT API への接続に失敗したこと、単位が kg の重量クラスまたは単位が cm の長さクラスがストアにないことを通知します（その場合、商品の単位は単位名に基づいて変換されます。System > Localisation > Weight Classes と Length Classes を確認してください）。名前が空、無効、または 64 文字を超える場合、Min weight (kg) が Max weight (kg) より大きい場合、Sort Order、税クラス、またはジオゾーンが無効な場合は、ページにエラーが表示され、何も保存されません。その他の無効な値は警告として表示され、残りは保存されます。無効な数値は保存されず、0 以下の為替レートは消去され、無効な商品サイズはデフォルトに戻り、不明な送付先や料金表の重複行は削除され、無効な表の料金は空欄になります。

一般

この拡張機能は、チェックアウト時に最大 2 つのオプションを提供します。顧客の住所への CTT 配送と、CTT 受取拠点またはパーセルロッカーへの配送です。料金と条件は両方に適用されます。

Enable/Disable: 顧客の住所への CTT 配送をオンまたはオフにします。

Name: チェックアウト時に顧客に表示される配送方法の名前（例: "CTT Expresso"）。デフォルト: CTT。最大 64 文字。

Tax class: 配送料の税クラス。OpenCart は、この税（例: IVA）を料金に加算します。--- None --- は、料金が確定していることを意味します。両方のオプションで使用されます。

Sort Order: チェックアウト時の配送方法の中での CTT の表示順。整数。

CTT 受取拠点またはパーセルロッカーへの配送

2 つ目の CTT オプションです。顧客は郵便番号または都市名で CTT 拠点を検索し（配送先住所が自動的に検索されます）、続行する前に 1 つ選択する必要があります。CTT の API キーと Carrier ID が必要です。これらがない場合、拠点選択のないオプションになります。

Enable CTT point option: CTT 受取拠点またはパーセルロッカーへの配送を提供します。デフォルト: オフ。

CTT point option name: チェックアウト時のこのオプションの名前。デフォルト: CTT point / parcel locker。最大 64 文字。

CTT e コマース API（リアルタイム料金、CTT 拠点）（任意。キーがない場合は料金表が使用されます）

Public key: CTT の e コマースアカウントのキー管理ページにある公開キー。

Private key: すべてのリクエストの署名に使用される秘密キー（HMAC-SHA256）。CTT に送信されることも、ログに書き込まれることもありません。

両方のキーは、保存後は再表示されません。その場合、フィールドの説明に Saved - leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。両方を削除するには、Remove the saved public and private key にチェックを入れて保存します。何も保存されていない場合、このセクションには No keys saved. と表示されます。

App ID (X-APPID): CTT が発行するアプリケーションキー。X-APPID ヘッダーで送信されます。

Carrier ID: アカウント内の CTT 運送業者の ID。リアルタイム料金と CTT 拠点検索に使用されます。キーと App ID を保存すると、アカウントの運送業者がフィールドの下に表示されます（Carriers of your CTT account:）。CTT 拠点に対応している運送業者には CTT points と表示されます。数字のみ。

Live rates: 顧客が番地、郵便番号、都市を入力すると、CTT に料金（料金見積もり）を問い合わせます。住所が不完全な間、および CTT が料金を返さない場合は、料金表が使用されます。CTT はこの料金を見積もりと呼びます。デフォルト: オフ。

Service ID: 任意。CTT が複数のサービスを返す場合は、この ServiceId のサービスが使用されます。空欄のままにすると、最も安いサービスが使用されます。

Exchange rate: CTT の料金はユーロ建てです。ストアのデフォルト通貨が異なる場合は、CTT 通貨 1 単位がストア通貨で何単位に相当するかを入力してください。これがないと、別の通貨でのリアルタイム料金は使用されず、料金表が適用されます。

Default product size (cm): 寸法のない商品について CTT に送信される長さ x 幅 x 高さ。デフォルト: 30x20x15。寸法のある商品は、それぞれの寸法を使用します。寸法は商品の長さクラスと重量クラスに基づいて cm と g に変換されます。

料金（セクションのタイトルにストアのデフォルト通貨が表示されます）

CTT との契約の料金、または ctt.pt にある CTT の公開料金表の料金を、ストアのデフォルト通貨で税抜きで入力してください。リアルタイム料金がオフの場合、この表が料金を決定します。オンの場合は、フォールバックとして使用されます。

Price table: 送付先ごとに 1 行。国を選択します: Portugal - Azores、Portugal - Madeira、または * Default (other destinations)。各行には基本の Price と、任意のサイズ別料金（XS（1 kg まで）、S（2 kg まで）、M（3 kg まで）、L（5 kg まで）、XL（5 kg 超））があります。サイズ別料金が空欄（または 0）の場合は基本料金が使用されます。両方が空欄の行では、配送方法が非表示になります。Azores の行はポルトガルの郵便番号 9500-9999 に、Madeira の行は 9000-9499 に使用されます。これらがない場合は Portugal の行が適用されます。Add destination をクリックすると行が追加され、× ボタンで削除できます。料金は小数点またはカンマを受け付けます。インストール後、この表は空です。

Calculation: 表の料金の求め方。

CTT のリアルタイム料金は、常に発送全体に対するものです。

条件

Min weight (kg): CTT オプションが表示されるためのカートの最小重量。0 は制限なしを意味します。

Max weight (kg): このカート重量を超えると、CTT オプションは非表示になります。デフォルト: 30（CTT の荷物は最大 30 kg）。0 は制限なしを意味します。Min weight (kg) は Max weight (kg) より大きくできません。

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

送料無料

Free shipping: 下記の金額以上の場合に、CTT の配送を無料にします。

Free shipping from: 配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額以上の場合、CTT オプションの料金は 0 になります。料金が設定されている送付先にのみ適用されます。Free shipping がオンの場合にのみ使用されます。

提供地域

通常、CTT オプションは下で選択したジオゾーン内で提供されます。All Zones は、すべての地域を意味します。Ignore shipping zones を使用すると、ジオゾーンは確認されず、Countries が対象を決定します。

Geo Zone: 配送先住所のジオゾーン。ジオゾーンは System > Localisation > Geo Zones で管理されます。

Ignore shipping zones: ジオゾーンを確認せず、下記の国で CTT を提供します。

Countries: そのモードでの送付先の国。デフォルト: Portugal。空欄にすると、すべての国を許可します。Ignore shipping zones を使用する場合にのみ使用されます。

詳細設定

Debug log: 料金計算と CTT API の呼び出しを storage/logs/vfd_ctt_debug.log.php（OpenCart 4 では system/storage/logs/vfd_ctt_debug.log.php）に記録します。このファイルは Web から読み取ることはできません。このオプションがオフの場合でも、CTT API のエラーは常に記録されます。キー、トークン、顧客の住所は記録されません。ファイルが 5 MB に達すると、vfd_ctt_debug.old.log.php に移動され、新しいログが開始されます。

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

Remove data on uninstall: オンの場合、拡張機能をアンインストールすると、設定、ログ、完了していないチェックアウトの CTT 拠点が削除されます。オフ（デフォルト）の場合、再インストール用に設定が保持されます。注文（選択された CTT 拠点を含む）は決して変更されません。

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

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

Import: 以前にエクスポートした JSON を貼り付けて Import をクリックすると、設定を復元します（例: 別のストアに移行する場合）。値は通常の保存と同様にチェックされます。保存済みのキーは保持されます。

チェックアウト時の動作

OpenCart が配送方法を表示するとき、拡張機能に CTT の料金を問い合わせます。Ignore shipping zones の場合、CTT は Countries に含まれる国に対してのみ提供されます（空欄 = すべての国）。それ以外の場合、Geo Zone が設定されていれば、そのゾーン内の住所に対してのみ提供されます。Requires Shipping が Yes に設定された商品のみが対象となります。それ以外の商品は重量に加算されず、注文金額にも含まれません。拡張機能はカートの重量と最低注文金額を確認します。Live rates がオンで住所が完全な場合、配送先住所と、カートの各行の数量、グラム単位の重量、cm 単位の寸法を CTT に送信し、返された料金を使用します。それ以外の場合、または CTT が料金を返さない場合（API エラー、タイムアウト、対象外地域、App ID で有効になっていない機能）は、料金表から料金が取得されます。送料無料が適用される場合、料金は 0 になります。両方のオプションは同じ料金になります。料金はストアのデフォルト通貨で計算され、その小数桁数に丸められ、選択された Tax class の税とともに、顧客の通貨で表示されます。

CTT の料金は 1 時間キャッシュされるため、同じカートでも新しいリクエストは発生しません。失敗したリクエストは 5 分間記憶されるため、チェックアウトは更新のたびに CTT を待つことはありません。API トークン、運送業者リスト、CTT 拠点リストもキャッシュされますが、その期間は OpenCart のキャッシュの有効期間（デフォルトは 1 時間）が上限です。API のエラーが顧客に表示されることはありません。料金表の料金が使用されるか、送付先に料金がない場合は配送方法が非表示になります。

API キーが入力されている場合、拡張機能は配送先住所、商品の重量と寸法、ストアの URL を CTT に送信し、料金または最寄りの CTT 拠点を取得します。

この拡張機能は、発送の作成、ラベルの印刷、集荷の依頼、追跡番号の提供、CTT 拠点の地図表示は行いません。料金表と API 設定は、両方のオプションで共通です。

OpenCart 4 では、顧客はチェックアウトページの配送方法ブロックで Choose をクリックし、ウィンドウ Shipping method options で CTT のオプションを選択します。料金は OpenCart 3 と同じです。

受取拠点

顧客が配送方法の手順で CTT 拠点オプションを選択すると、その下に検索フィールドとリストが表示されます。配送先住所の郵便番号が自動的に入力され、検索されます。顧客は郵便番号または都市名で他の CTT 拠点を検索（Search ボタン）し、リストから 1 つを選択できます。選択内容は直ちに保存されます。その検索の CTT リストにある拠点のみが受け付けられます。

顧客は続行する前に拠点を選択する必要があります。顧客が Continue をクリックすると、拡張機能はサーバー上で拠点を確認します。拠点が選択されていない場合、顧客には Please select a CTT point. と表示されます。CTT リストにない拠点の場合は The selected CTT point is not in the CTT list for this search. Please choose the CTT point again. と表示されます。CTT に接続できない場合、顧客には CTT points cannot be loaded right now. Please try again in a few minutes or choose another shipping method. と表示されます。

拠点の選択は、公開キー、秘密キー、App ID、Carrier ID がすべて入力されている場合にのみ有効になります。OpenCart のデフォルトテーマとそのチェックアウト用に作られています。他のテーマでは変更が必要になる場合があります。

OpenCart 4 では、検索フィールドとリストは、CTT 拠点オプションの下にあるウィンドウ Shipping method options に表示されます。ウィンドウの Continue ボタンは、有効な拠点が選択されていない限り先に進みません。メッセージは同じです。OpenCart 4 は、チェックアウトごとに 1 つの注文を保持し、顧客が再度確定するたびにその注文を更新します。その際、注文の CTT 拠点も一緒に更新されます。

選択された拠点は、注文の配送方法に追加されます（例: CTT point / parcel locker: ...）。そのため、顧客はアカウントの注文履歴と注文メールでこれを確認でき、請求書にも印刷され、Sales > Orders に表示されます。OpenCart の注文完了ページには配送方法は表示されません。

管理画面の注文ページでは、履歴の上にある CTT point パネルに拠点名と ID が表示されます。変更するには、Change CTT point の下に郵便番号または都市名を入力し、Search をクリックして拠点を選択し、Save をクリックします。ページには CTT point updated. と表示され、注文の配送方法のテキストが更新され、顧客に通知せずに注文履歴に CTT point changed to: ... のエントリが追加されます。拠点の変更には注文の変更権限（sale/order）と API 設定が必要です。このパネルは、拡張機能が無効の間も、CTT の注文に対して表示されます。

ライセンスキー

この拡張機能は、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox CTT は、Extensions > Extensions > Shipping > VibeFox CTT > Edit ページの最上部、設定の上にあります。キーを License key に入力し、Activate をクリックします。その後、ブロックにはマスク表示されたキー、ステータス（例: ライセンスの有効期限の日付とドメイン）、および Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）のボタンが表示されます。その下には Product: opencart-shipping-ctt の行と、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 のアカウントで枠を解放してください。

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

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

トラブルシューティング

CTT がチェックアウトに表示されない:ライセンスが有効であること、および Enable/Disable（または Enable CTT point option）がオンであることを確認してください。Geo Zone、または Ignore shipping zones と Countries を確認してください。送付先に料金表の行（または * Default の行）があること、カートの重量が Min weight と Max weight の範囲内であること、Minimum order amount に達していること、商品の Requires Shipping が Yes に設定されていることを確認してください。

顧客が CTT 拠点を選択できない:セレクターは、CTT 拠点オプションの下にのみ表示され、公開キー、秘密キー、App ID、Carrier ID がすべて入力されている場合にのみ表示されます。設定ページ上部の警告を確認し、Debug log をオンにして、拡張機能のページの Log フィールドを確認してください。

リアルタイム料金が表示されない:顧客が番地、郵便番号、都市を入力するまで、料金表が使用されます。警告とログを確認してください。"405" という応答は、その機能が App ID で有効になっていないことを意味します。CTT に問い合わせてください。ユーロ以外の通貨を使用しているストアでは、Exchange rate を入力してください。

CTT API への接続に失敗した:設定ページ上部の警告にエラーが表示されます。キーと App ID を確認してください。拡張機能は数分後に自動的に再試行します。

税込み価格か税抜き価格か:Tax class を選択すると、OpenCart はその税を料金に加算します。--- None --- の場合、料金は確定しています。

変更後に料金が古いままに見える:拡張機能のページで Save をクリックしてください。これにより、キャッシュされた CTT の応答がクリアされます。

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

開発者向け:CTT API のアドレスは、設定 vfd_ctt_api_url（テスト用）で置き換えることができます。設定ページにはこの項目はありません。

アンインストール

Extensions > Extensions に移動し、種類 Shipping を選択して、VibeFox CTT の横にある Uninstall（赤色の − ボタン）をクリックします。OpenCart は常に、拡張機能のステータス、Sort Order、Tax class、Geo Zone をリセットします。キャッシュされた CTT の応答と API トークンは常に削除されます。Remove data on uninstall がオンの場合、設定、ログ、注文にならなかったチェックアウトの CTT 拠点も削除されます。オフの場合、その他の設定は保持され、拡張機能を再インストールしたときに再び使用されます。注文に保存された CTT 拠点は常に保持され、既存の注文は配送方法と料金をそのまま維持します。

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

CTT は、その所有者の商標です。本拡張機能は CTT と提携しておらず、CTT による承認もされていません。