VibeFox CTT for PrestaShop — ヘルプ
要件
PrestaShop: 8.0 から 9.x。
PHP: 8.0 以降。古い PHP バージョンではモジュールのインストールを拒否します。
CTT e-commerce アカウント（リアルタイム料金と CTT の受取ポイントにのみ必要）: リアルタイム料金と CTT の受取ポイントへの配送は、CTT e-commerce API を使用します。enviosecommerce.ctt.pt で CTT e-commerce アカウントが必要です（CTT Expresso の契約のお客様、または CTT に提案を依頼してください）。そのアカウントのキー管理ページで、公開キーと秘密キーのペアを作成します。App ID（X-APPID）は、連携用に CTT が発行します。CTT の e-commerce 担当者にお問い合わせください。App ID で利用できる API の機能（料金見積もり、CTT の受取ポイント）も CTT が決定します。最後に、アカウントの CTT Carrier ID が必要です。キーを保存すると、設定ページにアカウントの配送業者が表示されます。価格表と住所への配送だけを使う場合は、API キーは不要です。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
1. 管理画面で Modules > Module Manager を開き、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックします。後でモジュール一覧から VibeFox CTT を探して Configure をクリックすることもできます。
3. Configure ページ上部のライセンスブロックの License key に VibeFox ライセンスキーを入力し、Activate をクリックします（「ライセンスキー」を参照）。
4. 価格表を入力し（少なくとも Portugal または * Default の行を 1 つ）、Save をクリックします。必要に応じて CTT の API キーと Carrier ID を入力し、Live rates と Enable CTT point carrier を有効にします（「設定」を参照）。
インストールすると、モジュールは 2 つの配送業者を作成します。CTT（購入者の住所への配送。配送時間の表示テキストは CTT delivery to your address）は有効になっています。CTT point / parcel locker（配送時間の表示テキストは Pickup at a CTT point or parcel locker）は、有効にするまで無効です。両方ともポルトガルのゾーンと、すべての顧客グループに紐付けられます。ゾーン、顧客グループ、配送時間、ロゴ、サイズ制限は Shipping > Carriers で変更できます。料金はそこで設定しないでください。料金は常にモジュールから取得されます。
設定
すべての設定はモジュールのページにあります: Modules > Module Manager > VibeFox CTT > Configure。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。料金と条件は、両方の CTT 配送業者に適用されます。保存のたびに、API トークンや CTT の受取ポイント一覧を含め、キャッシュされた CTT の応答がクリアされます。
設定の上部には警告が表示されます。価格表が空、ポルトガルの料金がない、API キーが不完全、Carrier ID がない、ショップの通貨が EUR 以外で為替レートがない、CTT API への接続失敗、CTT の配送業者が削除された、といった内容です。無効な値は保存時に通知されます。無効な数値は保存されず、不明な仕向地や価格表の重複行は削除されます。ショップの重量単位またはサイズ単位がモジュールで認識されない場合は、警告が International > Localization（Local units）で単位を設定するよう求めます。
一般
Enable/Disable: 購入者の住所への CTT 配送のオン／オフを切り替えます。Shipping > Carriers の配送業者のステータスと同じスイッチです。
Name: チェックアウトで購入者に表示される配送業者名です（例: "CTT Expresso"）。デフォルトは CTT です。必須、64 文字まで。
Tax status: None は、料金が確定額であることを意味します。税ルールを設定した Taxable は、その配送税（例: IVA）が料金に上乗せされることを意味します。選択内容は両方の CTT 配送業者に保存されます。
CTT の受取ポイントまたはパーセルロッカーへの配送
2 つ目の CTT 配送業者です。購入者は郵便番号または都市名で CTT の受取ポイントを検索し、次に進む前に 1 つ選ぶ必要があります。CTT API キーと Carrier ID が必要です。これらがない場合は、ポイントの選択がない配送業者になります。
Enable CTT point carrier: CTT 受取ポイントの配送業者のオン／オフを切り替えます。Shipping > Carriers でのステータスと同じスイッチです。デフォルトは無効です。
CTT point carrier name: チェックアウトでのこのオプションの名前です。デフォルトは CTT point / parcel locker です。必須、64 文字まで。
CTT e-commerce API（リアルタイム料金、CTT の受取ポイント）（任意。キーがない場合は価格表を使用）
Public key: CTT e-commerce アカウントのキー管理ページにある公開キーです。
Private key: すべてのリクエストに署名するための秘密キーです（HMAC-SHA256）。CTT に送信されることも、ログに書き込まれることもありません。
両方のキーは、保存後には再表示されません。その場合、フィールドの説明には Saved - leave empty to keep it. と表示されます。変更する場合のみ新しい値を入力します。Remove the saved public and private key をオンにして保存すると、両方のキーを削除できます。
App ID (X-APPID): CTT が発行するアプリケーションキーで、X-APPID ヘッダーで送信されます。
Carrier ID: アカウント内の CTT 配送業者の ID です。リアルタイム料金と CTT の受取ポイント検索に使われます。キーと App ID を保存すると、フィールドの下にアカウントの配送業者が一覧表示されます。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 に、重量はグラムに変換されます。
料金（セクションのタイトルには、ショップのデフォルト通貨が表示されます）
CTT との契約料金、または ctt.pt にある CTT の公開価格表の料金を、ショップのデフォルト通貨で、税抜きで入力します。リアルタイム料金が無効のとき、この表が料金を決定します。リアルタイム料金が有効のときは、代替料金になります。
Price table: 仕向地ごとに 1 行です。国を選択します: Portugal - Azores (PT-AC)、Portugal - Madeira (PT-MA)、または * Default (other destinations)。各行には基本料金の Price と、任意のサイズ別料金があります: XS（1 kg まで）、S（2 kg まで）、M（3 kg まで）、L（5 kg まで）、XL（5 kg 超）。サイズ別料金が空（または 0）の場合は基本料金が使われます。両方の欄が空の行では、配送業者が非表示になります。Azores の行はポルトガルの郵便番号 9500-9999 に、Madeira の行（Porto Santo を含む）は 9000-9499 に使われます。これらがない場合は Portugal の行が適用されます。Add destination をクリックすると行を追加でき、ゴミ箱アイコンで行を削除できます。料金は小数点またはカンマで入力できます。インストール直後、表は空です。
Calculation: 価格表から料金を求める方法です。
リアルタイムの CTT 料金は、常に荷物全体に対するものです。
条件
Min weight (kg): 配送業者が表示されるためのカートの最小重量です。0 は制限なしを意味します。
Max weight (kg): このカート重量を超えると、配送業者は非表示になります。デフォルトは 30 です（CTT の荷物は最大 30 kg）。0 は制限なしを意味します。Min weight (kg) は Max weight (kg) より大きくできません。設定は保存されません。
Minimum order amount: カートの小計（配送が必要な商品、割引後、税抜き）がこの金額に達した場合にのみ、配送業者を表示します。空欄のままにすると、常に表示されます。
送料無料
Free shipping: 下記の金額以上で、CTT の配送を無料にします。
Free shipping from: 配送業者の料金が 0 になるカートの小計（割引後、税抜き）です。料金が設定されている仕向地にのみ適用されます。Free shipping がオンの場合にのみ使われます。
配送ゾーンを使わない場合の提供条件
通常、配送業者は Shipping > Carriers で紐付けた配送ゾーンで提供されます。
Ignore shipping zones: 下記の国で、ゾーンに紐付けずに配送業者を提供します。オンにすると、両方の配送業者が有効なすべてのゾーンに紐付けられます（後から作成したゾーンも含みます）。オフにすると、以前のゾーンに戻ります。
Countries: このモードの配送先の国です。デフォルトは Portugal です。空欄にすると、すべての国が許可されます。Ignore shipping zones がオンの場合にのみ使われます。配送業者が以前紐付けられていたゾーンの購入者には、常にサービスが提供されます。
詳細設定
Debug log: 料金の計算と CTT API の呼び出しを、モジュールフォルダー内の logs/vfd_ctt_debug.log.php に記録します。このファイルは Web から開くことはできません。この設定がオフでも、CTT API のエラーは常に記録されます。キー、トークン、購入者の住所がログに記録されることはありません。
Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログを空にできます。
Remove data on uninstall: オンの場合、モジュールをアンインストールするとモジュールの設定と配送業者が削除されます。オフの場合、アンインストールでは配送業者が無効になるだけです。選択した CTT の受取ポイントを含め、注文は変更されません。
チェックアウトでの動作
配送ステップで PrestaShop は、CTT の各配送業者の料金をモジュールに問い合わせます。対象になるのは物理的な商品だけです。仮想商品は重量に加算されず、注文金額にも含まれません。モジュールは最初に Ignore shipping zones とその国、カートの重量、最低注文金額を確認します。Live rates がオンで住所が完全に入力されている場合、配送先住所と、カートの各行について数量、グラム単位の重量、cm 単位の寸法を CTT に送信し、返された料金を使います。それ以外の場合、または CTT が料金を返さない場合（API エラー、タイムアウト、対応地域外、App ID で機能が有効になっていない）は、価格表から料金を取得します。送料無料が適用される場合、料金は 0 です。料金はショップのデフォルト通貨で計算され、その後、購入者のカートの通貨で表示されます。
CTT の料金は 1 時間キャッシュされるため、同じカートで新しいリクエストが発生することはありません。失敗したリクエストは 5 分間記憶されるため、チェックアウトは更新のたびに CTT を待つことはありません。API のタイムアウトは 12 秒です。API のエラーが購入者に表示されることはありません。価格表の料金が使われるか、仕向地に料金がない場合は配送業者が非表示になります。
注文のある配送業者を Shipping > Carriers で編集すると、PrestaShop はそれを新しい配送業者のバージョンとして保存します。モジュールは新しいバージョンに自動的に従います。
API キーが入力されている場合、モジュールは配送先住所、商品の重量と寸法、ショップの URL を CTT に送信し、料金または最寄りの CTT の受取ポイントを取得します。
モジュールは、発送の作成、ラベルの印刷、集荷の依頼、追跡番号の提供、CTT の受取ポイントの地図表示は行いません。両方の配送業者で、料金表と API 設定は 1 つずつです。
受取ポイント
購入者が CTT の受取ポイントの配送業者を選択すると、その下に検索フィールドと一覧が表示されます。配送先住所の郵便番号が自動的に入力され、検索されます。購入者は郵便番号または都市名（Search ボタンまたは Enter キー）で他の CTT の受取ポイントを検索し、一覧から 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 の受取ポイントの一覧は 6 時間キャッシュされます。CTT に接続できない場合、購入者には CTT points cannot be loaded right now. Please try again in a few minutes or choose another shipping method. と表示されます。
ポイントの選択は、Classic テーマと Hummingbird テーマで動作します。公開キー、秘密キー、App ID、Carrier ID がすべて入力されている場合にのみ有効です。
選択したポイントは注文に保存されます。管理画面の注文ページの CTT point ブロック（名前と ID）、注文確認ページ、顧客アカウントの注文詳細、注文確認メールに、配送業者名の横の CTT point: として表示されます。Mail alerts モジュールの新規注文メールにも、ポイントの ID が表示されます。
管理画面の注文ページで、Change CTT point の下に郵便番号または都市名を入力し、Search をクリックして、ポイントを選び、Save をクリックします。ページには CTT point updated. と表示され、新しいポイントを含む非公開の注文メッセージ CTT point changed to: が追加されます。ポイントの変更には、注文を編集する権限が必要です。
ライセンスキー
このモジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox CTT は、Modules > Module Manager > VibeFox CTT > Configure ページで設定の上にある最初のブロックです。キーを License key に入力し、Activate をクリックしてください。その後、ブロックにはキーがマスクされて表示され、ステータス（例えばライセンスの有効期限日とドメイン）と、ステータスを再確認する Check now、別のキーを入力する Change key、このショップからキーを削除する Remove key のボタンが表示されます。その下には Product: presta-shipping-ctt の行と、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 のアカウントで解放してください。
有効なキーがない場合、CTT の配送業者（住所への配送または CTT の受取ポイントへの配送のどちらも）はチェックアウトで購入者に表示されず、料金も計算されません。PrestaShop のストアフロントは、管理画面にログインしていることを認識しないため、配送業者はあなたにも表示されません。購入前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブに通知が表示されます。既存の注文には影響しません。
ライセンスの有効期限が切れてもモジュールは動作を続けますが、アップデートとサポートには更新が必要です。ステータスは、管理画面での作業中に自動的に再確認されます。キー入力後の最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
チェックアウトに CTT が表示されない: ライセンスが有効であることと、Enable/Disable（または Enable CTT point carrier）がオンであることを確認してください。Shipping > Carriers で、配送業者が購入者の国のゾーンと購入者の顧客グループをカバーしていることを確認します。または、Ignore shipping zones がオンで、その国が許可されていることを確認します。仕向地が価格表に行（または * Default の行）を持っていること、カートの重量が Min weight と Max weight の範囲内であること、Minimum order amount に達していることも確認してください。商品ページで、商品を特定の配送業者に制限している場合もあります。
購入者が CTT の受取ポイントを選べない: セレクターは CTT の受取ポイントの配送業者の下にのみ表示され、公開キー、秘密キー、App ID、Carrier ID がすべて入力されている場合にのみ表示されます。設定の上部の警告を確認し、Debug log をオンにして、モジュールのページの Log フィールドを確認してください。
リアルタイム料金が表示されない: 購入者が番地、郵便番号、都市を入力するまでは、価格表が使われます。設定の上部の警告とログを確認してください。応答が "405" の場合は、その機能が App ID で有効になっていないことを意味します。CTT に問い合わせてください。ユーロ以外の通貨のショップでは、Exchange rate を入力してください。
CTT API への接続に失敗した: 設定の上部の警告にエラーが表示されます。キーと App ID を確認してください。モジュールは数分後に自動的に再試行します。
税込みまたは税抜きの料金: Tax status を Taxable ルールに設定すると、PrestaShop は配送税を料金に上乗せします。None の場合、料金は確定額です。
変更後に料金が古いように見える: モジュールのページで Save をクリックしてください。これにより、キャッシュされた CTT の応答がクリアされます。
CTT の配送業者が見つからないと表示される: Shipping > Carriers で配送業者が削除されています。Modules > Module Manager でモジュールをリセットすると、再作成されます。リセットしても、設定と両方の配送業者のオン／オフの状態は保持されます。
開発者向け: CTT API のアドレスは、設定キー vfd_ctt_API_URL で変更できます。
アンインストール
Modules > Module Manager に移動し、VibeFox CTT の横にあるメニューを開いて Uninstall を選択します。ライセンスキー、ライセンスステータス、キャッシュされた CTT の応答と API トークンは、常に削除されます。Remove data on uninstall がオンの場合は、両方の配送業者が削除されます（注文は履歴を保持します）。さらに、モジュールの設定、ログ、そして注文にならなかったカートの CTT の受取ポイントも削除されます。オフの場合は、配送業者が無効になるだけで、すべての設定は保持されます。モジュールを再インストールすると、各配送業者は以前のオン／オフの状態に戻ります。注文に保存された CTT の受取ポイントは、常に保持されます。
CTT は、その所有者の商標です。本モジュールは CTT と提携しておらず、CTT による推奨も受けていません。