VibeFox UPS for WooCommerce — ヘルプ
要件
WordPress: 5.8 以降。
WooCommerce: 7.0 以降。インストールされていて有効であること。WooCommerce がない場合、プラグインは有効化できません。
PHP: 8.0 以降。
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. WordPress で Plugins > Add New > Upload Plugin に進み、プラグインの ZIP ファイルを選択して Install Now をクリックします。FTP で vfd_ups フォルダを /wp-content/plugins/ にアップロードすることもできます。
2. Activate をクリックします。
3. 設定を開きます。WooCommerce > Settings > Shipping > VibeFox UPS、またはプラグイン一覧ページでプラグイン名の下にある Settings をクリックします。
4. ページ上部のライセンスブロックに VibeFox ライセンスキーを入力し、Activate をクリックします。
5. Client ID と Client Secret、UPS アカウント番号（契約料金を使う場合）、Ship from の住所を入力します。郵便番号と、米国およびカナダの場合は 2 文字の州コードを入力してください。
6. UPS アカウントの通貨がストアの通貨と異なる場合は、UPS account currency と Exchange rate を入力します。
7. WooCommerce > Settings > Shipping > Shipping zones で VibeFox UPS を配送ゾーンに追加するか、Ignore shipping zones を有効にして国を選択します。
8. 必要に応じて、フォールバックとして固定料金を入力します。
設定
すべての設定は 1 つのページにあります。WooCommerce > Settings > Shipping > VibeFox UPS です。設定はすべての配送ゾーンに適用されます。ゾーンにこの方法を追加すると、ゾーンのウィンドウには項目が 1 つだけ表示されます。
Title (zone): チェックアウトに表示されるこの選択肢の名前。空欄にすると、全体の Name が使われます。
設定を保存するたびに、キャッシュされた UPS トークンと料金が消去されます。UPS API セクションの Clear cached UPS token and rates をクリックすることもできます。設定の上部には警告が表示されます。Client ID と Client Secret のどちらか一方だけが設定されている場合、認証情報も固定料金もない場合、発送元の郵便番号や州が未入力の場合、アカウント番号なしで契約料金が選ばれている場合、為替レートが未入力の場合に表示されます。
General
Enable/Disable: すべてのゾーンでこの方法を一度に有効または無効にします。
Name: チェックアウトに表示される配送方法の名前。既定値: UPS。
Tax status: Taxable にすると、WooCommerce が配送税を加算します。None では加算しません。UPS の料金は税抜きで見積もられるため、税金が二重にかかることはありません。
UPS API（リアルタイム料金）
Test mode: UPS のテスト環境を使用します。テスト料金は実際の価格ではありません。リアルタイム料金を使うには無効にしてください。既定値: オフ。
Client ID: UPS Developer Portal で作成したアプリの Client ID。
Client Secret: 同じアプリの Client Secret。
UPS account number: 6 文字の UPS 荷送人番号（例: A1B2C3）。契約料金（ネゴシエート料金）には必須で、公開料金には任意です。
Rates: 使用する UPS の料金の種類。
Measurement units: UPS に送信される単位。ストアの重量とサイズは変換されます。
Residential delivery: 購入者の住所を、UPS の住宅地割増料金付きの住宅として見積もります。主に法人向けに発送する場合はオフにしてください。既定値: オン。
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 をクリックして行を追加し、× をクリックして削除します。* Default の行は、それ以外のすべての国に適用されます。重量の列（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: この方法が無料になるカートの小計。購入者には「(Free)」付きの方法名が表示され、UPS へのリクエストは送信されません。空欄にすると、送料無料は提供されません。
Minimum subtotal: カートの小計がこの金額以上の場合にのみ、この方法を表示します。空欄にすると、常に表示されます。
Min weight (kg): この方法が表示されるために必要なカートの最低重量。0 は制限なしを意味します。
Max weight (kg): カートの重量がこの値を超えると、方法は非表示になります。既定値: 70。これは UPS の 1 梱包あたりの上限です（70 kg / 150 lbs）。0 は制限なしを意味します。
Default product weight (kg): 重量のない商品に使われる重量。UPS の料金、重量の列、重量制限で使われます。既定値: 0.5。
Excluded shipping classes: カートに、これらの WooCommerce 配送クラスのいずれかの商品が含まれている場合、この方法を非表示にします。
配送ゾーンを使わない場合の利用可否
Ignore shipping zones: 配送ゾーンに追加していなくても、下記の国に対してこの方法を提供します。
Countries: このモードの配送先の国。空欄にすると、ストアのすべての配送対象国が使われます。このフィールドは Ignore shipping zones が有効な場合にのみ使われます。
詳細設定
Debug log: API のリクエストと料金の計算を WooCommerce > Status > Logs に記録します。ソースは vfd-ups です。このオプションがオフでも、API のエラーは常に記録されます。認証情報、トークン、購入者の住所は記録されることはありません。
Remove data on uninstall: オンにすると、プラグインを削除したときに、すべてのプラグイン設定とゾーンの方法が削除されます。無効化しても設定が削除されることはありません。
チェックアウト時の動作
購入者が配送先住所を入力すると、WooCommerce がプラグインに料金を問い合わせます。プラグインはまず条件を確認します。カートの重量、最低小計、除外する配送クラスです。送料無料が適用される場合、この方法は無料として表示され、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 のエラーメッセージが表示されることはありません。
この方法は、クラシックチェックアウトと、カートブロックおよびチェックアウトブロックの両方で動作します。WooCommerce High-Performance Order Storage（HPOS）に対応しています。
本プラグインは送料の計算のみを行います。UPS Access Point の選択、配送ラベルや UPS の発送データの作成、集荷の手配、荷物の追跡は行いません。複数の UPS サービスではなく、1 つの選択肢のみを表示します。箱詰めの機能はありません。カートは 1 梱包として見積もられます。為替レートは自動では更新されません。
注文
リアルタイム料金の場合、注文の配送行には UPS service（例: UPS Ground）が保存されます。ストア管理者は、管理画面の注文画面でこれを確認できます。
ライセンスキー
本プラグインは、vibefox.net で入手した VibeFox ライセンスキーを使用します。ライセンスブロックは WooCommerce > Settings > Shipping > VibeFox UPS の上部にあります。キーを License key に貼り付け、Activate をクリックしてください。ブロックには、ライセンスの有効期限日や、お使いのドメインなどのステータスが表示されます。Check now でステータスを再確認し、Change key で別のキーを入力し、Remove key でこのサイトからキーを削除します。Manage licenses and domains in your account のリンクから、vibefox.net のアカウントを開けます。
1 つのキーは 1 つのドメインでのみ使用できます。サイトからキーを削除しても、そのドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。
有効なキーがない場合、UPS はチェックアウトで購入者には表示されません。ログイン中のストア管理者には、(unlicensed — visible to admins only) と表示された状態で引き続き表示されるため、キーを購入する前にプラグインを設定してテストできます。プラグイン一覧ページと WooCommerce のページには通知が表示されます。既存の注文には影響しません。
ライセンスの有効期限が切れた場合、プラグインは引き続き動作しますが、アップデートとサポートには更新が必要です。ステータスはバックグラウンドで自動的に再確認されます。
トラブルシューティング
チェックアウトに UPS が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、この方法が購入者の国のゾーンに追加されていることを確認してください（または Ignore shipping zones がオンで、その国が許可されていること）。重量制限、Minimum subtotal、Excluded shipping classes も確認してください。UPS の認証情報が正しく機能していない場合、この方法には固定料金（Country prices または Fallback cost）が必要です。
リアルタイム料金が表示されない: 設定ページの上部にある警告を確認してください。Debug log をオンにして、WooCommerce > Status > Logs を開き、ソースとして vfd-ups を選択します。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 が求める単位を選択してください。
変更後に料金が古いように見える: 設定ページを保存するか、Clear cached UPS token and rates をクリックしてください。
開発者向け: フィルター vfd_upsx_allowed_services と vfd_upsx_excluded_services は、表示できる UPS サービスを制限します。vfd_upsx_rate_request は料金のリクエストを変更し、vfd_upsx_api_base_url は API の URL を変更し、vfd_upsx_currency_codes は UPS が返す通貨コードを対応付けます。
ライセンスブロックにエラーが表示される: ブロック内のメッセージに従ってください。例えば、そのキーが別のドメインで既に使われている場合は、vibefox.net のアカウントで枠を解放し、Check now をクリックします。サイトのアドレスが変わった場合は、Check now をクリックして、新しいドメインでキーを有効化します。ライセンスサーバーに接続できない場合、プラグインは最後に確認できたステータスで動作を続けます。
アンインストール
プラグインを無効化しても設定は残り、キャッシュされたトークンと料金だけが消去されます。削除するには、無効化してから Plugins ページで削除してください。このプラグインのライセンスキーとライセンスステータス、キャッシュされたトークンと料金は、常に削除されます。設定とゾーンの方法は、Remove data on uninstall がオンだった場合にのみ削除されます。そうでない場合は、後で再インストールするために残ります。既存の注文は、配送行を保持します。
UPS は各所有者の商標です。本プラグインは UPS と提携しておらず、UPS の承認も受けていません。