VibeFox UPS for OpenCart — ヘルプ
要件
OpenCart：3.0.x（3.0.5.0 で動作確認済み）、または 4.0.2 以降（4.1.0.3 で動作確認済み）。
PHP：8.0 以降（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 つのドメインでのみ使用できます。
インストール
ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。お使いのコンピューターで解凍してください。内容は README.txt、OpenCart 3 用パッケージ vfd_ups-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ vfd_ups.ocmod.zip です。お使いの OpenCart バージョン用のパッケージだけをインストールしてください。ライセンスキーは両方のバージョンで同じです。
OpenCart 3
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_ups-oc3-(version).ocmod.zip を選択します。本拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。Installer を使う代わりに、このパッケージの upload フォルダ内の内容をストアのルートフォルダにコピーすることもできます。
2. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選択します。VibeFox UPS を見つけて、Install（緑色の + ボタン）をクリックします。
3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。
4. Edit ページ上部のライセンスブロックにある License key 欄に VibeFox ライセンスキーを入力し、Activate をクリックします（License key を参照）。
5. Client ID と Client Secret、UPS アカウント番号（協定料金用）、Ship from の発送元住所（郵便番号、および米国とカナダの場合は 2 文字の州コード）を入力します。
6. UPS アカウントの通貨がストアの既定の通貨と異なる場合は、UPS account currency と Exchange rate を入力します。
7. 必要に応じて、フォールバックとして固定料金を入力し、Enable UPS shipping をオンにして、Save をクリックします。
OpenCart 4
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_ups.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変更したパッケージは動作しません。
2. 同じページのインストール済み拡張機能の一覧にパッケージが表示されます。その横の Install（緑色の + ボタン）をクリックします。
3. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選択します。VibeFox UPS を見つけて Install（緑色の + ボタン）をクリックし、続けて Edit（鉛筆のボタン）をクリックします。
4. ライセンスキーと設定は、OpenCart 3 の手順 4 〜 7 と同じように入力します。設定ページとその項目は両方のバージョンで同じです。
インストール後は、Enable UPS shipping をオンにして保存するまで、この方法はオフのままです。Ship from の国は、初期状態ではストアの国になっています。アンインストール後に拡張機能を再インストールした場合は、保持されていた UPS の設定が再び使われます。
設定
すべての設定は拡張機能のページにあります：Extensions > Extensions > Shipping > VibeFox UPS > Edit。セクションは左側に並んでいます。ページ下部の Save ボタンを押すと、ページを再読み込みせずにページ全体が保存されます。保存するたびに、キャッシュされた UPS トークンと料金が消去されます。この拡張機能の変更権限を持つ管理者ユーザーだけが、設定の保存、キャッシュの消去、ログの消去を行えます。
名前、税クラス、並び順、ジオゾーンが有効でない場合は何も保存されず、ページに理由が表示されます（例：Enter a valid name (64 characters max, without < > ; = # { }). Nothing was saved.）。無効な数値（負の数など）、箱のサイズの誤り、Min weight (kg) が Max weight (kg) を超える場合、数値ではない料金のセルは、保存時に報告されます。その項目は以前の値を保持し、残りの項目は保存されます。設定の上の警告は、Client ID と Client Secret のどちらか一方だけが設定されている場合、認証情報も固定料金もない場合（この方法は表示されません）、発送元の郵便番号や州が欠けている場合、アカウント番号なしで協定料金が選ばれている場合、為替レートがない場合、またはストアの重量単位や長さ単位を拡張機能が認識できない場合に表示されます。
一般
この設定はすべてのジオゾーンに適用されます。UPS は、チェックアウトで 1 つの配送オプションとして表示されます。
Enable UPS shipping：チェックアウトで UPS を表示するか非表示にするかを設定します。既定値：オフ。
Name：チェックアウトで顧客に表示される配送方法の名前。既定値：UPS。必須、64 文字以内、< > ; = # { } を含まないこと。
Tax class：配送料の税クラス、または None（既定値）。UPS の料金は税抜きで提示されます。税クラスを設定すると、OpenCart がその上に配送税を加算します。
Sort order：チェックアウトで配送方法の中に表示される UPS の位置。整数。
UPS API（リアルタイム料金）
Test mode：UPS のテスト環境を使用します。テスト用の料金は実際の価格ではありません。リアルタイム料金を使う場合はオフにしてください。既定値：オフ。
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 の住宅地割増料金を伴う住宅として計算します。主に法人宛てに発送する場合はオフにしてください。既定値：オン。
Box size (L x W x H)：ストアの長さ単位（フィールド名に表示）による、任意の箱のサイズ（例：30x20x15）。UPS はこれに基づいて容積重量を適用します。重量のみで計算する場合は空欄のままにしてください。
UPS account currency：UPS は発送者アカウントの国の通貨で料金を提示します（例：米国は USD、カナダは CAD、ユーロ圏は EUR）。既定値：USD。
Exchange rate：UPS アカウントの通貨がストアの既定の通貨と異なる場合にのみ必要です。アカウント通貨 1 単位がストアの既定の通貨でいくらになるかを入力してください（例：0.92）。これがない場合、そのような料金は使われず、固定料金が適用されます。為替レートは自動では更新されません。
Cache：UPS トークンは期限切れまで（最長で OpenCart のキャッシュ期間まで）キャッシュされ、料金は 1 時間、失敗したリクエストは 5 〜 10 分キャッシュされます。Clear cached UPS token and rates をクリックすると、キャッシュをすぐに消去できます。
Ship from（UPS が荷物を集荷する住所、または荷物を持ち込む住所。リアルタイム料金に使用されます）
Country：発送元の国。既定ではストアの国です。
State / province code：2 文字の州コード。米国とカナダでは必須です（例：NY、CA、ON）。この 2 か国の場合にのみ UPS に送信されます。
City：発送元の都市。
ZIP / postal code：発送元の郵便番号。UPS が料金を提示するために必要です。OpenCart にはストアの郵便番号がないため、ここに入力してください。
固定料金（API の認証情報が入力されていない場合に使われ、UPS が料金を返さない場合のフォールバックとしても使われます。両方とも空欄にすると、その場合にこの方法を非表示にします）
Country prices：配送先の国ごとに、ストアの既定の通貨による税抜きの料金。Add country をクリックして行を追加し、削除ボタンで行を削除します。* Default (all other countries) は、その他すべての国に適用されます。重量列（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（既定値）は、カート全体の重量に基づいて、料金を 1 回だけ請求します。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 を意味します。
Default product weight (kg)：重量のない商品に使われる重量。UPS の料金、重量列、重量制限で使用されます。既定値：0.5。空欄も 0.5 を意味します。
Geo zone：このジオゾーン内の住所に対してのみ UPS を提供します。All zones（既定値）は制限なしを意味します。ジオゾーンは System > Localisation > Geo Zones で管理します。Ignore shipping zones を使用する場合は適用されません。
配送ゾーンを無視する場合の提供状況
Ignore shipping zones：ジオゾーンを確認しません。この方法は下記の国に対して提供されます。
Countries：そのモードの配送先の国。空欄の場合は、ストアで有効になっているすべての国を使用します。このフィールドは、Ignore shipping zones がオンの場合にのみ使用されます。
詳細
Debug log：API リクエストと料金計算を storage/logs/vfd_upsx_debug.log.php（OpenCart 4 では system/storage/logs/vfd_upsx_debug.log.php） に記録します。このファイルはウェブから読み取ることができません。このオプションがオフでも、API エラーは常に記録されます。認証情報、トークン、顧客の住所は記録されることはありません。ファイルが 5 MB に達すると、vfd_upsx_debug.old.log.php に移動され、新しいログが開始されます。
Log：ログのサイズと最新のエントリを表示します。Clear log をクリックすると空になります。
Remove data on uninstall：オンにすると、拡張機能をアンインストールした際に、UPS の設定、キャッシュされたトークンと料金、ログが削除されます。注文とともに保存された UPS のサービスは常に保持されます。オフの場合は、再インストールに備えて、すべてが保持されます。
インポート / エクスポート
Export：Download JSON をクリックすると、設定が JSON ファイルとして保存されます。Client Secret はエクスポートされません。
Import：以前にエクスポートした JSON を貼り付け、Import をクリックすると、設定を復元できます（例：別のストアで）。値は通常の保存と同じように検証されます。保存済みの Client Secret は保持されます。
チェックアウトでの動作
OpenCart が配送方法を表示する際、拡張機能に UPS の料金を問い合わせます。Geo zone が設定されていて、住所がその外にある場合、UPS は提供されません（Ignore shipping zones を使う場合は、代わりに国のリストで判断されます）。Requires Shipping が Yes に設定された商品のみが対象です。それ以外の商品は重量に加算されず、小計にも含まれません。小計は、これらの商品のクーポン割引後、税前の価格です。ギフト券、リワードポイント、ストアクレジットは考慮されません。次に、拡張機能は条件を確認します。カートの重量と最低小計です。送料無料が適用される場合、料金は 0 になり、UPS へのリクエストは送信されません。
拡張機能は UPS から OAuth トークンを取得し、期限切れになるまで保持します。UPS に拒否されたトークンは自動的に更新され、リクエストは 1 回だけ繰り返されます。その後、カート全体を 1 個の荷物として、発送元住所から顧客の住所までのすべてのサービスについて、UPS Rating API に問い合わせます。OpenCart で郵便番号が必要な国では、顧客が郵便番号を入力するまで、リクエストは待機します。米国からカナダまたはプエルトリコへの発送では、UPS の要件に従って商品価額が送信されます。
顧客には、最も安い UPS サービスを含む 1 つの選択肢が表示されます。料金はストアの既定の通貨で計算され、その通貨の小数点桁数に丸められ、選択された Tax class の税とともに、顧客の通貨で表示されます。拡張機能は Access Point の住所を収集しないため、UPS Access Point Economy の料金は提示されません。
各料金は 1 時間キャッシュされます。失敗したリクエストは 10 分間、トークンのリクエストの失敗は 5 分間記憶されるため、障害があっても、チェックアウトの更新のたびに遅くなることはありません。HTTP のタイムアウトは 15 秒です。
UPS が料金を返さない場合（API が利用できない、認証情報が誤っている、利用可能なサービスがない、為替レートのない別の通貨など）、料金は Country prices から、次に Fallback cost から取得されます。どちらも適用されない場合、この方法は非表示になります。UPS のエラーメッセージが顧客に表示されることはありません。理由はデバッグログに記録されます。
拡張機能は料金を計算するだけです。UPS Access Point の選択、UPS の出荷ラベルや出荷の作成、集荷の予約、荷物の追跡は行いません。複数の UPS サービスではなく、1 つの選択肢だけを表示します。箱詰めの機能はありません。カートは 1 個の荷物として見積もられます。為替レートは自動ではありません。
OpenCart 4 では、顧客はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options ウィンドウで UPS を選択します。この方法は OpenCart 3 と同じように動作します。
注文
UPS のリアルタイム料金で注文が行われると、UPS のサービスが注文とともに保存されます。Sales > Orders の注文ページには、UPS service（例：UPS Ground）と Live rate (excl. tax) を示す UPS パネルが表示されます。これらの値は注文時に保存されます。固定料金または送料無料の注文には、このパネルはありません。
OpenCart 4 では、チェックアウトのために 1 つの注文を保持し、顧客が再度確定するたびにその注文を更新します。保存された UPS サービスもそれに合わせて更新されます。顧客が別の配送方法を選んだり、料金が固定料金または送料無料になったりすると、保存されたサービスは注文から削除されます。OpenCart 4 では、UPS パネルは History セクションの上に表示されます。
ライセンスキー
この拡張機能は、vibefox.net で取得した VibeFox ライセンスキーを使用します。License — VibeFox UPS のライセンスブロックは、Extensions > Extensions > Shipping > VibeFox UPS > Edit ページで設定の上にある最初のブロックです。キーを License key 欄に入力し、Activate をクリックしてください。その後、ブロックにはキーがマスクされた状態で表示され、ステータス（ライセンスの有効期限日やお使いのドメインなど）と、ボタンが表示されます。ボタンは、ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key です。その下には Product: opencart-shipping-ups の行と、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 つのドメインでのみ使用できます。ライセンスとドメインは vibefox.net のアカウントで管理します。
有効なキーがない場合、UPS はチェックアウトで顧客に表示されず、料金も計算されません。同じブラウザで管理画面にログインしている管理者ユーザーには、ストアで (unlicensed — visible to admins only) と表示されたうえで引き続き配送方法が見えるため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 ではこのプレビューは利用できません。ストアは管理画面のログインを認識しないため、有効なキーがないと全員に対して配送方法が非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると 7 日間非表示になります。既存の注文には影響しません。
ライセンスの期限が切れた後も拡張機能は動作し続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスは自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは必要ありません。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
UPS does not appear at checkout：ライセンスが有効であり、Enable UPS shipping がオンになっていることを確認してください。Geo zone を確認するか、Ignore shipping zones をオンにして Countries を確認してください。重量制限と Minimum subtotal を確認してください。有効な UPS の認証情報がない場合、この方法には固定料金（Country prices または Fallback cost）が必要です。商品の Requires Shipping が Yes に設定されているか確認してください。
Live rates do not appear：Edit ページの上部の警告を確認してください。Debug log をオンにし、チェックアウトを再読み込みして、拡張機能のページにある Log の欄を確認してください。OAuth のエラー（Client ID、Client Secret、Test mode を確認）、UPS のエラーメッセージ、通貨の問題が表示されます。
The rate is in USD but the store is not：UPS は発送者アカウントの通貨で料金を返します。UPS account currency と Exchange rate を設定してください。為替レートがない場合、そのような料金は無視され、固定料金が使われます。
"This measurement system is not valid for the selected country"：Measurement units を Automatic (by ship-from country) のままにするか、発送元の国に対して UPS が求める単位を選んでください。
The page warns about the weight or length unit：kg の重量クラスがない場合、不明な重量単位は kg として読み取られます。System > Localisation > Weight Classes で kg の重量クラスを追加してください。ストアの長さ単位が不明な場合、Box size は cm として読み取られます。ストアの長さクラスとして cm、mm、m、in のいずれかを使用してください（System > Settings、タブ Option）。
Rates look outdated after a change：拡張機能のページで Save をクリックするか、Clear cached UPS token and rates をクリックしてください。
The page says "Warning: You do not have permission to modify VibeFox UPS!"：管理者ユーザーグループが設定を閲覧するだけの権限しか持っていない可能性があります。System > Users > User Groups で、そのグループに extension/shipping/vfd_ups（OpenCart 3）または extension/vfd_ups/shipping/vfd_ups（OpenCart 4） の変更権限を付与してください。
For developers：本拡張機能は、他の拡張機能が監視できる OpenCart イベントを発生させます。vfd_ups/allowed_services と vfd_ups/excluded_services は表示できる UPS サービスを制限し、vfd_ups/rate_request は料金のリクエストを変更し、vfd_ups/api_base_url は API のアドレスを変更し、vfd_ups/currency_codes は UPS が返す通貨コードを対応付けます。
アンインストール
Extensions > Extensions に移動し、種類 Shipping を選んで、VibeFox UPS の横にある Uninstall（赤い − ボタン）をクリックします。OpenCart は、Enable UPS shipping、Sort order、Tax class、Geo zone を常にリセットします。キャッシュされた UPS トークンと料金は常に削除されます。Remove data on uninstall がオンの場合は、UPS の設定とデバッグログも削除されます。オフの場合、その他の設定は保持され、拡張機能を再インストールしたときに再び使われます。注文とともに保存された UPS のサービスは決して削除されず、既存の注文は配送方法と料金をそのまま保持します。
OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧で VibeFox UPS の横にある Uninstall（オレンジ色の − ボタン）をクリックしてから、アップロードしたパッケージを削除するために Delete（赤いゴミ箱のボタン）をクリックしてください。
UPS は、その所有者の商標です。本拡張機能は UPS と提携しておらず、UPS の支持も受けていません。