VibeFox USPS for PrestaShop — ヘルプ
要件
PrestaShop: 8.0 ～ 9.x。
PHP: 8.0 以降。モジュールは、それより古い PHP バージョンではインストールを拒否します。
USPS Developer Portal のアプリ（リアルタイム送料の場合のみ）：無料の USPS ビジネスアカウントで USPS Developer Portal（developers.usps.com）にサインインし、アプリを作成して、その Consumer Key と Consumer Secret をコピーします。モジュールは OAuth 2.0 を使用する現在の USPS API を利用します。USPS は従来の Web Tools API（User ID と XML）を 2026 年 1 月 25 日に停止したため、Web Tools User ID はもう使用できません。キーがない場合は、固定料金のみが使用されます。
Ship-from ZIP code：リアルタイム送料には、荷物の発送元となる米国の 5 桁の郵便番号が必要です。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
1. 管理画面で Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックします。または、後でモジュール一覧から VibeFox USPS を探し、Configure をクリックします。
3. Configure ページ上部のライセンスブロックにある License key 欄に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。
4. Consumer Key と Consumer Secret、5 桁の Ship from ZIP code を入力し、サービスを選択します。ショップのデフォルト通貨が USD でない場合は、USD exchange rate を入力します。必要に応じて、代替用の固定料金を入力します。Save をクリックします。
インストール時に、モジュールは配送時間のテキスト Delivery by USPS を付けた USPS 配送業者を作成します。配送業者はすべてのゾーンとすべての顧客グループに割り当てられます。ゾーン、顧客グループ、配送時間、ロゴ、サイズ制限は Shipping > Carriers で変更できます。ここで料金は設定しないでください。料金は常にモジュールから取得されます。
設定
すべての設定はモジュールページにあります：Modules > Module Manager > VibeFox USPS > Configure。設定は配送業者のすべてのゾーンに適用されます。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。保存するたびに、キャッシュされた USPS トークンと送料もクリアされます。
無効な値は保存されません。以前の値が残り、エラーで該当フィールドが示されますが、他のフィールドは保存されます。ページ上部の警告は、キーが片方だけ設定されている場合、キーも固定料金もない場合（この場合、配送業者は表示されません）、発送元の郵便番号がない場合、サービスが選択されていない場合、USD 為替レートがない場合、テスト環境が有効な場合、ショップの重量または寸法の単位が不明な場合（International > Localization の Local units で設定してください）、USPS 配送業者が削除された場合などに表示されます。
一般
Enable USPS shipping: 配送業者をオンまたはオフにします。これは Shipping > Carriers の配送業者のステータスと同じスイッチです。
Name: チェックアウト時に顧客に表示される配送業者名です。デフォルト：USPS。必須、最大 64 文字。
Tax status: 配送業者の税ルールです。USPS の料金には税金は含まれません。送料に税を加える場合は税ルールを選択し、送料に税をかけない場合は None を選択します。
USPS API（リアルタイム送料）
Consumer Key: USPS 開発者アプリの Consumer Key（client_id）です。
Consumer Secret: 同じアプリの Consumer Secret（client_secret）です。保存後、フィールドは空のままになり、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。Consumer Key を空にすると、保存されている Secret も削除されます。
Test environment: USPS Testing Environment for Mailers（apis-tem.usps.com）を使用します。この環境にアクセス権があるアプリ専用です。実際の料金を使用する場合はオフのままにしてください（apis.usps.com）。デフォルト：オフ。
Prices: 使用する USPS の料金です。
Services: 提供してよい USPS のサービスです。荷物に対して USPS が提供する選択済みサービスのうち最も安いものが表示されます。Flat Rate、Cubic、Hold for Pickup、Sunday の料金は使用されません。デフォルト：USPS Ground Advantage、Priority Mail、First-Class Package International Service。サービスが 1 つも選択されていない場合、リアルタイム送料は使用されません。
USD exchange rate: USPS の料金は米ドル建てです。ショップのデフォルト通貨が USD でない場合は、その通貨での 1 USD の価格を入力します（例：0.92）。これがないと、リアルタイム送料は使用されず、固定料金が適用されます。デフォルト通貨が USD の場合は不要です。0 より大きい値である必要があります。
Cache: Clear cached USPS token and rates ボタンを押すと、キャッシュがすぐに空になります。見積もりは 1 時間、失敗した見積もりは 10 分間キャッシュされます。タイムアウト、サーバーエラー、レート制限、またはキーの拒否の後は、5 分間 USPS に問い合わせません。
発送と荷物（USPS の料金は発送元の郵便番号、重量、荷物のサイズによって決まります。カートは 1 つの荷物として見積もられ、70 lb を超える荷物は固定料金を使用します）
Ship from ZIP code: 荷物の発送元となる米国の 5 桁の郵便番号です。ZIP+4 は 5 桁に切り詰められます。それ以外の値は、メッセージとともに拒否されます。
Box size: ショップの寸法単位による箱の寸法（任意）です。例：30x20x15。空欄にすると、商品の寸法から、最も長い長さ、最も広い幅、積み重ねた高さによってサイズが決まります。商品に寸法がない場合は、10 x 8 x 4 インチの箱が使用されます。
Default product weight: 重量が設定されていない商品に使用する重量（kg）です。USPS の送料、重量制限、重量区分に使用されます。デフォルト：0.5。
固定料金（ショップのデフォルト通貨、税抜きの料金です。API キーが入力されていない場合に使用され、USPS が送料を返さない場合（API 停止、キーの誤り、サービスなし、米国の郵便番号がない配送先など）の代替としても使用されます。この場合に配送業者を非表示にするには、両方の欄を空欄にしてください）
Country prices: 配送先の国とカートの重量ごとの料金です。Add country をクリックして行を追加し、ゴミ箱アイコンで削除します。列は Price と重量区分 XS（1 kg まで）、S（1～2 kg）、M（2～3 kg）、L（3～5 kg）、XL（5 kg 超）です。空欄または 0 の区分は Price を使用します。* Default (any other country) の行は、それ以外のすべての国に適用されます。料金が 1 つも入力されていない国の行は、その国を Fallback cost に振り分けます。数値でない値は、メッセージとともに消去されます。
Fallback cost: どの国別料金も一致しない場合に使用される固定料金です。空欄にすると、この場合に配送業者を非表示にします。
Fixed price is: Per order は、カート全体の重量に基づいて料金を 1 回だけ請求します。Per item (each item priced by its own weight x quantity) は、商品ごとに 1 個分の重量（重量がない場合はデフォルトの重量）で料金を計算し、数量を掛けます。USPS のリアルタイム送料は、常に荷物全体に対して見積もられます。
条件
Free shipping from: この配送業者が無料になるカートの小計（割引後、税抜き）です。この場合、USPS へのリクエストは送信されません。空欄にすると、送料無料は提供されません。
Minimum subtotal: カートの小計がこの金額以上の場合にのみ配送業者を表示します。空欄にすると、常に表示されます。
Min weight: この配送業者が表示されるために必要な、カートの最低重量（kg）です。0 は制限なしを意味します。
Max weight: カートの重量（kg）がこの値を超える場合、配送業者を非表示にします。デフォルト：30。USPS は最大 70 lb（31.7 kg）まで受け付けます。0 は制限なしを意味します。Min weight が Max weight より大きい場合は、エラーが表示され、以前の制限が維持されます。
配送ゾーンなしでの利用可否
Ignore shipping zones: 下記の国について、すべてのゾーンで配送業者を提供します。保存すると、配送業者はショップのすべてのゾーン（後から作成されたゾーンを含む）に関連付けられます。オフにすると、配送業者は以前のゾーンに戻ります。
Countries: このモードの配送先の国です。空欄にすると、ショップが配送するすべての国が許可されます。このフィールドは Ignore shipping zones がオンの場合にのみ使用されます。
詳細設定
Debug log: API リクエストと送料計算を、モジュールフォルダ内の logs/vfd_usps_debug.log.php に記録します。このファイルは Web からは開けません。このオプションがオフでも、API エラーは常に記録されます。キー、トークン、顧客の住所は決して記録されません。
Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると空になります。
Remove data on uninstall: オンの場合、モジュールをアンインストールすると、USPS の設定、配送業者、保存された注文サービス、キャッシュされた送料、ログが削除されます。オフの場合は、再インストールに備えてすべてが保持されます。
チェックアウト時の動作
配送のステップで、PrestaShop はモジュールに USPS の料金を問い合わせます。対象となるのは実物の商品のみです。仮想商品は重量に加算されず、小計にも含まれません。モジュールはまず条件を確認します：許可された国（Ignore shipping zones を使用する場合）、カートの重量、最低小計。送料無料が適用される場合、料金は 0 となり、USPS へのリクエストは送信されません。
モジュールは USPS から OAuth トークンを取得し、有効期限が近づくまで保持します。USPS に拒否されたトークンは更新され、見積もりが再試行されます。米国とその属領（プエルトリコ、米領バージン諸島、グアム、米領サモア、北マリアナ諸島、ミクロネシア連邦、マーシャル諸島、パラオ）への配送先の場合は、Domestic Prices API を使用し、顧客の 5 桁の郵便番号が必要です。その他の国の場合は、国と郵便番号を指定して International Prices API を使用します。
リクエストには、発送元の郵便番号、カートの重量（ポンド）、荷物のサイズ（インチ）、料金の種類が含まれます。70 lb を超える荷物には固定料金が適用されます。顧客に表示されるのは、選択したサービスのうち最も安いものを 1 つだけ含む選択肢です。その料金は USD からショップのデフォルト通貨に換算され、さらに顧客のカート通貨で表示されます。
各見積もりは 1 時間キャッシュされます。失敗した見積もりは 10 分間記憶されます。タイムアウト、サーバーエラー、レート制限、またはキーの拒否の後は、5 分間 USPS に問い合わせません。HTTP のタイムアウトは 10 秒です。
USPS が送料を返さない場合、料金は Country prices、次に Fallback cost から取得されます。どちらも該当しない場合、配送業者は非表示になります。顧客に USPS のエラーメッセージが表示されることはありません。理由はログに記録されます。
配送業者に注文がある状態で Shipping > Carriers から編集すると、PrestaShop はそれを新しい配送業者のバージョンとして保存します。モジュールは自動的に新しいバージョンに従います。
モジュールは送料の計算のみを行います。郵便料金や配送ラベルの購入、集荷の予約、荷物の追跡、顧客による郵便局や受け取り場所の選択はできません。複数の USPS サービスではなく、1 つの選択肢のみを表示します。箱詰めの機能はありません。カートは 1 つの荷物として見積もられます。保険やその他の追加サービスは含まれません。
注文
USPS 配送業者で注文が行われると、モジュールは配送料金がどのように決定されたかを保存します。管理画面の注文ページには USPS ブロックが表示され、USPS service（リアルタイム送料の場合の例：USPS Ground Advantage）と Price source（USPS live rate、Fixed price、Free shipping のいずれか）が表示されます。
ライセンスキー
モジュールは vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox USPS は、Modules > Module Manager > VibeFox USPS > Configure ページの設定の上にある最初のブロックです。キーを License key 欄に入力し、Activate をクリックします。その後、ブロックにはキーがマスクされた状態で表示され、ステータス（例：ライセンスの有効期限日とドメイン）と、ステータスを再確認する Check now、別のキーを入力する Change key、このショップからキーを削除する Remove key のボタンが表示されます。その下には Product: presta-shipping-usps の行と、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 アカウントで枠を解放してください。
有効なキーがない場合、USPS 配送業者はチェックアウト時に顧客に表示されず、送料も計算されません。PrestaShop のストアフロントは、管理画面にログインしていることを認識しないため、配送業者は管理者にも表示されません。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。
ライセンスの期限が切れても、モジュールは動作し続けますが、アップデートとサポートには更新が必要です。管理画面での作業中、ステータスは自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日 1 回、その後は週に 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは必ず削除されます。
トラブルシューティング
チェックアウトに USPS が表示されない：ライセンスが有効であること、そして Enable USPS shipping がオンであることを確認してください。Shipping > Carriers で、配送業者が顧客の国のゾーンと顧客のグループをカバーしていることを確認するか、Ignore shipping zones をオンにして Countries を確認してください。重量制限と Minimum subtotal も確認してください。有効な USPS キーがない場合、配送業者には固定料金（Country prices または Fallback cost）が必要です。また、商品ページで商品を特定の配送業者に限定している場合もあります。
リアルタイム送料が表示されない：モジュールページ上部の警告を確認してください。Debug log をオンにし、チェックアウトを再読み込みして、Log フィールドを確認します。キーの誤り、環境の誤り、USPS のエラーメッセージはそこに記録されます。国内の送料には顧客の 5 桁の郵便番号が必要です。
ショップの通貨が USD ではない：USPS は USD でのみ見積もります。USD exchange rate を入力してください。これがないと、リアルタイム送料は使用されず、代わりに固定料金が表示されます。
Web Tools User ID が機能しない：従来の Web Tools API は停止しています。USPS Developer Portal でアプリを作成し、その Consumer Key と Consumer Secret を使用してください。
変更後に送料が古く見える：設定を保存するとキャッシュがクリアされます。Clear cached USPS token and rates をクリックすることもできます。
USPS 配送業者が見つからないというページが表示される：配送業者が Shipping > Carriers で削除されています。Modules > Module Manager でモジュールをリセットすると、再作成されます。
アンインストール
Modules > Module Manager に移動し、VibeFox USPS の横にあるメニューを開いて、Uninstall を選択します。ライセンスキーとライセンスステータスは常に削除されます。キャッシュされたトークンと送料も常に削除されます。Remove data on uninstall がオンの場合、配送業者は削除され（注文は履歴を保持します）、設定、保存された注文サービス、ログも削除されます。オフの場合、配送業者は無効になるだけで、すべての設定は保持されます。モジュールを再インストールするか、Reset を実行すると、保存されていた配送業者は以前のステータスに戻ります。オンだった配送業者は再びオンになり、無効だったものは無効のままです。
USPS は各所有者の商標です。本モジュールは USPS と提携しておらず、USPS による推奨も受けていません。