VibeFox UPS for PrestaShop — ヘルプ
要件
PrestaShop：8.0～9.x。
PHP：8.0 以降（cURL 拡張機能を含む）。古いバージョンの PHP や cURL のない環境ではモジュールをインストールできません。
UPS Developer Portal のアプリ（リアルタイム料金のみ）：UPS Developer Portal（developer.ups.com）にログインし、「Rating」製品を含むアプリを作成して UPS アカウントを連携させ、Client ID と Client Secret をコピーしてください。モジュールは OAuth 2.0 を使用します。Access Key、ユーザー名、パスワードは不要です。契約料金を利用する場合は、6 文字の UPS アカウント番号も必要です。認証情報がない場合は、固定料金のみが使用されます。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
1. 管理画面で Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックします。後からモジュール一覧で VibeFox UPS を探し、Configure をクリックすることもできます。
3. Configure ページ上部のライセンスブロックにある License key フィールドに VibeFox ライセンスキーを入力し、Activate をクリックします（「ライセンスキー」を参照）。
4. Client ID と Client Secret、UPS アカウント番号（契約料金の場合）、および Ship from の住所（郵便番号、米国とカナダの場合は 2 文字の州コード）を入力します。
5. UPS アカウントの通貨がショップの既定通貨と異なる場合は、UPS account currency と Exchange rate を入力します。
6. 必要に応じて代替料金として固定料金を入力し、Save をクリックします。
インストール時にモジュールは、配送時間のテキストを UPS delivery とした UPS 配送業者を作成します。この配送業者はすべてのゾーンとすべての顧客グループに割り当てられます。ゾーン、顧客グループ、配送時間、ロゴ、サイズ制限は Shipping > Carriers で変更できます。ここで料金を設定しないでください。料金は常にモジュールから取得されます。
設定
すべての設定はモジュールページにあります：Modules > Module Manager > VibeFox UPS > Configure。設定は配送業者のすべてのゾーンに適用されます。各セクションには独自の Save ボタンがあり、ページ全体を保存します。保存のたびに、キャッシュされた UPS トークンと料金がクリアされます。UPS API セクションの Clear cached UPS token and rates をクリックすることもできます。
設定の上部には次のような警告が表示されます：Client ID と Client Secret のどちらか一方しか設定されていない場合、認証情報も固定料金もない場合（この場合、配送業者は表示されません）、発送元の郵便番号または州が未入力の場合、アカウント番号なしで契約料金が選択されている場合、為替レートが未入力の場合、またはショップの重量・寸法の単位をモジュールが認識できない場合です。無効な数値、誤った箱サイズ、Max weight を超える Min weight は保存時に報告され、以前の値が保持されます。
一般
Enable UPS shipping：配送業者を有効または無効にします。これは Shipping > Carriers の配送業者ステータスと同じスイッチです。
Name：チェックアウト時にお客様に表示される配送業者名です。既定値：UPS。必須、最大 64 文字。
Tax status：配送業者の税ルール、または None。UPS の料金は税抜きで見積もられます。税ルールを設定すると、ショップは配送税をその上に加算します。
UPS API（リアルタイム料金）
Test mode：UPS のテスト環境を使用します。テスト料金は実際の料金ではありません。リアルタイム料金にするには無効にしてください。既定値：off。
Client ID：UPS Developer Portal でのアプリの Client ID です。消去すると、保存されている Client Secret も削除されます。
Client Secret：同じアプリの Client Secret です。保存後、このフィールドは空のままになり、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。
UPS account number：6 文字の UPS 荷送人番号（例：A1B2C3）。契約（ネゴシエート）料金に必要で、公開料金には任意です。
Rates：使用する UPS の料金の種類です。
Measurement units：UPS に送信される単位です。ショップの重量とサイズは変換されます。
Residential delivery：お客様の住所を、UPS の住宅地域割増料金を適用した住宅住所として見積もります。主に法人向けに発送する場合は無効にしてください。既定値：on。
Box size：ショップの寸法単位による任意の箱のサイズです（例：30x20x15）。UPS は容積重量を適用します。重量のみで見積もる場合は空欄のままにします。
UPS account currency：UPS は発送元アカウントの国の通貨で見積もります（例：米国は USD、カナダは CAD、ユーロ圏は EUR）。既定値：USD。
Exchange rate：UPS アカウントの通貨がショップの既定通貨と異なる場合にのみ必要です。アカウント通貨 1 単位の価格を既定通貨で入力します（例：0.92）。入力しない場合、そのような料金は使用されず、固定料金が適用されます。為替レートは自動更新されません。
発送元住所（UPS が集荷に来る住所、またはお客様が荷物を持ち込む住所です。リアルタイム料金に使用されます）
Country：発送元の国です。既定ではショップの国になります。
State / province code：2 文字の州・県コードです。米国とカナダでは必須です（例：NY、CA、ON）。
City：発送元の都市です。
ZIP / postal code：発送元の郵便番号です。UPS が料金を見積もるために必要です。
固定料金（API の認証情報が入力されていない場合に使用され、UPS が料金を返さない場合の代替料金としても使用されます。両方を空欄にすると、その場合は配送業者を非表示にします）
Country prices：ショップの既定通貨による税抜きの料金で、配送先の国ごとに設定します。Add country をクリックして行を追加し、削除ボタンで行を削除します。国 * はそれ以外のすべての国に適用されます。重量列（XS は 1 kg まで、S は 1～2 kg、M は 2～3 kg、L は 3～5 kg、XL は 5 kg 超）は、その重量について Price より優先されます。空のセルでは Price が使用されます。0 は送料無料を意味します。どの料金も入力されていない行は保存時に削除され、数値ではない値はメッセージとともに拒否されます。
Fallback cost：どの国の料金も一致しない場合に使用される、ショップの既定通貨による定額料金です。この場合に配送業者を非表示にするには、空欄のままにします。
Fixed price is：Per order は、カート全体の重量に対して一度だけ料金を請求します。Per item (each item priced by its own weight x quantity) は、各商品を個別の重量（重量がない場合は既定の重量）で計算し、数量を掛けます。商品に固定料金がない場合、配送業者は非表示になります。UPS のリアルタイム料金は常にカート全体の重量で見積もられます。
条件
Free shipping from：この配送業者が無料になるカートの小計（配送が必要な商品、割引後・税抜き）です。その場合、UPS へのリクエストは送信されません。無料配送を提供しない場合は空欄のままにします。
Minimum subtotal：カートの小計がこの金額以上の場合にのみ、配送業者を表示します。常に表示する場合は空欄のままにします。
Min weight：この配送業者が表示されるためのカートの最低重量（kg）です。0 は制限なしを意味します。
Max weight：カートの重量がこの値（kg）を超えると、配送業者は非表示になります。既定値：70（UPS の 1 個口あたりの上限、70 kg / 150 lbs）。0 は制限なし、空欄は 70 を意味します。Min weight を Max weight より大きく設定することはできません。
Default product weight：重量が設定されていない商品に使用される重量（kg）です。UPS の料金、重量列、重量制限で使われます。既定値：0.5。
配送ゾーンを使わない場合の提供
通常、配送業者は Shipping > Carriers で割り当てられたゾーンで提供されます。
Ignore shipping zones：一致するゾーンに関係なく、下記の国に対して配送業者を提供します。保存時に、配送業者はすべてのゾーンに追加され、後から作成されたゾーンにも追加されます。無効にすると、それらのゾーンは再び削除されます。
Countries：このモードの配送先の国です。空欄の場合は、ショップで有効なすべての国を使用します。このフィールドは Ignore shipping zones が有効な場合にのみ使用されます。
詳細設定
Debug log：API リクエストと料金計算を、モジュールフォルダー内の logs/vfd_upsx_debug.log.php に記録します。このファイルは Web から開くことはできません。このオプションが無効でも、API エラーは常に記録されます。認証情報、トークン、お客様の住所は決して記録されません。
Log：ログのサイズと最新のエントリを表示します。Clear log をクリックすると空になります。
Remove data on uninstall：有効にすると、モジュールをアンインストールした際に、設定、配送業者、キャッシュされたトークンと料金、ログ、注文と共に保存された UPS サービスが削除されます。注文自体は保持されます。無効にすると、再インストールに備えてすべてが保持されます。
チェックアウト時の動作
配送のステップで PrestaShop はモジュールに UPS の料金を問い合わせます。対象となるのは実物の商品のみです。仮想商品は重量に加算されず、小計にも含まれません。モジュールはまず条件を確認します：Ignore shipping zones の国、カートの重量、最低小計です。送料無料が適用される場合、料金は 0 となり、UPS へのリクエストは送信されません。
モジュールは UPS から OAuth トークンを取得し、有効期限が切れるまで保持します。UPS によって拒否されたトークンは自動的に更新されます。その後、発送元住所からお客様の住所までのすべてのサービスについて、カートを 1 個口として UPS Rating API に問い合わせます。郵便番号のある国の場合、お客様が郵便番号を入力するまでリクエストは待機します。米国からカナダまたはプエルトリコへの発送では、UPS の要件に従い商品の価格が送信されます。
お客様には、最も安い UPS サービスを含む 1 つの選択肢が表示されます。料金はショップの既定通貨で計算された後、お客様のカートの通貨で表示されます。モジュールは Access Point の住所を収集しないため、UPS Access Point Economy は見積もられません。
各見積もりは 1 時間キャッシュされます。失敗したリクエストは 10 分間、失敗したトークンリクエストは 5 分間記憶されるため、障害があってもチェックアウトの更新が毎回遅くなることはありません。HTTP のタイムアウトは 15 秒です。
UPS が料金を返さない場合（API の停止、認証情報の誤り、サービスがない、為替レートのない別の通貨など）、料金は Country prices から、次に Fallback cost から取得されます。どちらも該当しない場合、配送業者は非表示になります。お客様に UPS のエラーメッセージが表示されることはありません。
配送業者に注文が入った後で Shipping > Carriers から編集すると、PrestaShop はそれを新しいバージョンの配送業者として保存します。モジュールは新しいバージョンに自動的に追従します。
本モジュールは送料の計算のみを行います。UPS Access Point の選択、配送ラベルや UPS の発送データの作成、集荷の手配、荷物の追跡は行いません。複数の UPS サービスではなく、1 つの選択肢のみを表示します。ボックスへの梱包は行わず、カートは 1 個口として見積もられます。為替レートは自動更新されません。
注文
リアルタイムの UPS 料金で注文が行われると、UPS サービスが注文と共に保存されます。バックオフィスの注文ページには、UPS service（例：UPS Ground）と Live rate (excl. tax) を表示する UPS ブロックが表示されます。バックオフィスでカートを後から変更しても、これは変わりません。固定料金または送料無料の注文には、このブロックはありません。
ライセンスキー
本モジュールは vibefox.net で入手した VibeFox ライセンスキーを使用します。ライセンスブロック License — VibeFox UPS は Modules > Module Manager > VibeFox UPS > Configure ページの最初のブロックで、設定の上に表示されます。キーを License key に入力し、Activate をクリックしてください。その後、ブロックにはマスクされたキー、ステータス（ライセンスの有効期限日や、お使いのドメインなど）、次のボタンが表示されます：ステータスを再確認する Check now、別のキーを入力する Change key、このショップからキーを削除する Remove key。その下には Product: presta-shipping-ups という行と、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 のアカウントで枠を解放してください。
有効なキーがない場合、UPS 配送業者はチェックアウト時にお客様に表示されず、料金も計算されません。PrestaShop のフロントエンドはバックオフィスにログインしていることを認識しないため、配送業者はご自身にも表示されません。キーを購入する前にモジュールを設定することはできますが、チェックアウトでのテストはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。
ライセンスの期限が切れてもモジュールは動作を続けますが、アップデートとサポートには更新が必要です。バックオフィスで作業している間、ステータスは自動的に再確認されます。キー入力後の最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールのアンインストールまたはリセットを行うと、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
チェックアウトに UPS が表示されない：ライセンスが有効であること、および Enable UPS shipping がオンであることを確認してください。Shipping > Carriers で、配送業者がお客様の国のゾーンと顧客グループに対応しているか確認するか、Ignore shipping zones をオンにして Countries を確認してください。重量制限と Minimum subtotal も確認してください。UPS の認証情報が機能していない場合、配送業者には固定料金（Country prices または Fallback cost）が必要です。また、商品ページで特定の配送業者に商品を限定することもできます。
リアルタイム料金が表示されない：Configure ページ上部の警告を確認してください。Debug log をオンにし、チェックアウトを再読み込みして、モジュールページの Log フィールドを確認してください。OAuth エラー（Client ID、Client Secret、Test mode を確認してください）、UPS のエラーメッセージ、通貨の問題が表示されます。
料金は USD だが、ショップの通貨は違う：UPS は発送元アカウントの通貨で料金を返します。UPS account currency と Exchange rate を設定してください。為替レートがない場合、そのような料金は無視され、固定料金が使用されます。
「This measurement system is not valid for the selected country」：Measurement units を Automatic のままにするか、発送元の国で UPS が要求する単位を選択してください。
ショップの重量または寸法の単位が不明であるという警告が表示される：その場合、重量は kg、箱のサイズは cm として読み取られます。International > Localization の Local units セクションで標準単位（kg、g、lb、oz、cm、mm、m、in のいずれか）を設定してください。
変更後に料金が古いように見える：モジュールページで Save をクリックするか、Clear cached UPS token and rates をクリックしてください。
UPS 配送業者が見つからないと表示される：配送業者は Shipping > Carriers で削除されています。Modules > Module Manager でモジュールをリセットすると、再作成されます。
開発者向け：フック actionVfdUpsxAllowedServices と actionVfdUpsxExcludedServices は、表示できる UPS サービスを制限します。actionVfdUpsxRateRequest は料金リクエストを変更し、actionVfdUpsxApiBaseUrl は API のアドレスを、actionVfdUpsxCurrencyCodes は UPS が返す通貨コードのマッピングを変更します。
アンインストール
Modules > Module Manager に移動し、VibeFox UPS の横にあるメニューを開いて Uninstall を選択してください。ライセンスキーとライセンスステータスは常に削除されます。キャッシュされた UPS トークンと料金は常に削除されます。Remove data on uninstall がオンの場合、配送業者は削除され（注文は履歴を保持します）、設定、ログ、注文と共に保存された UPS サービスも削除されます。オフの場合、配送業者は無効化されるだけで、設定は保持されます。モジュールを再インストールするか、リセットすると、配送業者は以前の状態に戻ります。
UPS は各所有者の商標です。本モジュールは UPS と提携しておらず、UPS による承認もされていません。