VibeFox USPS for OpenCart — ヘルプ
要件
OpenCart: 3.0.x（3.0.5.0 で検証）または 4.0.2 以降（4.1.0.3 で検証）。
PHP: 8.0 以降（cURL 拡張機能あり）。
USPS Developer Portal のアプリ（リアルタイム料金のみ）: 無料の USPS ビジネスアカウントで USPS Developer Portal（developers.usps.com）にサインインし、アプリを作成して、その Consumer Key と Consumer Secret をコピーします。この拡張機能は OAuth 2.0 による現在の USPS API を使用します。従来の Web Tools User ID では動作しません。キーがない場合は、固定料金のみが使用されます。
発送元郵便番号: リアルタイム料金には、荷物を発送する米国の 5 桁の郵便番号が必要です。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの ZIP ファイルです。お使いのコンピュータで解凍してください。内容は README.txt、OpenCart 3 用パッケージ vfd_usps-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ vfd_usps.ocmod.zip です。お使いの OpenCart バージョン用のパッケージだけをインストールしてください。ライセンスキーは両方のバージョンで同じです。
OpenCart 3
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_usps-oc3-(version).ocmod.zip を選択します。この拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。Installer を使う代わりに、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。
2. Extensions > Extensions に移動し、拡張機能の種類として Shipping を選択します。VibeFox USPS を見つけて、Install（緑色の + ボタン）をクリックします。
3. Edit（鉛筆のボタン）をクリックして、設定ページを開きます。
4. Edit ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを貼り付け、Activate をクリックします（License key を参照）。
5. Consumer Key と Consumer Secret、5 桁の Ship from ZIP code を入力し、Services を選択します。ストアの既定の通貨が USD でない場合は、USD exchange rate を入力します。
6. 必要に応じて、代替の固定料金を入力し、Enable USPS shipping をオンにして、Save をクリックします。
OpenCart 4
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_usps.ocmod.zip を選択します。ファイル名を変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変えたパッケージは動作しません。
2. 同じページのインストール済み拡張機能の一覧にパッケージが表示されます。その横の Install（緑色の + ボタン）をクリックします。
3. Extensions > Extensions に移動し、拡張機能の種類として Shipping を選択します。VibeFox USPS を見つけて、Install（緑色の + ボタン）をクリックしてから、Edit（鉛筆のボタン）をクリックします。
4. OpenCart 3 の手順 4 から 6 と同じようにライセンスキーと設定を入力します。設定ページとそのフィールドは両方のバージョンで同じです。
インストール後は、Enable USPS shipping をオンにして保存するまで、この配送方法はオフのままです。アンインストール後に拡張機能を再インストールした場合は、保持されていた USPS の設定が再び使用されます。
設定
すべての設定は拡張機能のページにあります: Extensions > Extensions > Shipping > VibeFox USPS > Edit。セクションは左側に一覧表示されます。ページ下部の Save ボタンで、ページを再読み込みせずにページ全体を保存します。保存のたびに、キャッシュされた USPS トークンと料金がクリアされます。この拡張機能の変更権限を持つ管理者ユーザーのみが、設定の保存、キャッシュのクリア、ログの消去を行えます。
無効な値は保存されません。ページは該当するフィールドを示し、以前の値を戻して、The other settings were saved. と表示します。これは、空・長すぎる・禁止文字を含む名前、負の値や数字でない値、5 桁でない郵便番号、誤った箱のサイズ、Max weight (kg) を超える Min weight (kg)（両方の上限は値を保持します）、整数でない並び順、不明な税区分またはジオゾーンに適用されます。数字でない国別料金は消去され、一覧に表示されます。設定の上部の警告は、2 つのキーのうち一方のみが設定されている場合、キーがなく固定料金もない場合（この場合は配送方法が表示されません）、郵便番号がない場合、サービスが選択されていない場合、USD の為替レートがない場合、テスト環境が有効な場合、またはストアの重量単位や長さ単位が拡張機能で認識されない場合に表示されます。
一般
設定はすべてのジオゾーンに適用されます。USPS は、チェックアウトで 1 つの配送オプションとして提供されます。
Enable USPS shipping: チェックアウトで USPS の配送を提供します。既定値: オフ。
Name: チェックアウトでお客様に表示される配送方法の名前。既定値: USPS。必須、最大 64 文字、< > ; = # { } は使用不可。
Tax class: 配送料の税区分。USPS の料金には税金は含まれません。No tax（既定）は、配送料に税金がかからないことを意味します。
Sort order: チェックアウトの配送方法の中での USPS の表示位置。整数。
USPS API（リアルタイム料金）
Consumer Key: USPS 開発者アプリの Consumer Key（client_id）。これを消去すると、保存済みの Consumer Secret も削除されます。
Consumer Secret: 同じアプリの Consumer Secret（client_secret）。保存後、このフィールドは空のままになり、Saved — leave empty to keep it. Clearing the Consumer Key removes it too. と表示されます。変更する場合にのみ新しい値を入力します。
Test environment: 発送者向けの USPS Testing Environment を使用します。これにアクセスできるアプリのみ対象です。実際の料金を使用する場合はオフのままにします。既定値: オフ。
Prices: 使用する USPS の料金表。
Services: 見積もりの対象にできる USPS のサービス。選択したサービスのうち、荷物に対して USPS が提供する最も安いものが表示されます。USPS Ground Advantage、Priority Mail / Priority Mail International、Priority Mail Express / Priority Mail Express International、First-Class Package International Service、Media Mail (books and media only)、Library Mail (libraries and schools only) から選択します。既定値: Ground Advantage、Priority Mail、First-Class Package International。Flat Rate、Cubic、Hold for Pickup、Sunday の料金は使用されません。サービスが 1 つも選択されていない場合、リアルタイム料金は使用されません。
USD exchange rate: USPS の料金は USD です。ストアの既定の通貨が USD でない場合は、1 USD の価格をお使いの通貨で入力します（例: 0.92）。0 より大きい値である必要があります。これがない場合、リアルタイム料金は使用されず、固定料金が適用されます。ストアの通貨が USD の場合は不要です。為替レートは自動では更新されません。
Cache: 見積もりは 1 時間、失敗した見積もりは 10 分間キャッシュされます。タイムアウト、サーバーエラー、レート制限、またはキーの拒否の後、5 分間は USPS に問い合わせません。Clear cached USPS token and rates をクリックすると、キャッシュをすぐに空にできます。
発送元と荷物（USPS の料金は発送元郵便番号、重量、荷物のサイズによって異なります。カートは 1 つの荷物として見積もられます）
Ship from ZIP code: 荷物を発送する 5 桁の米国郵便番号。ZIP+4 は 5 桁に切り詰められます。OpenCart にはストアの郵便番号がないため、ここに入力してください。
Box size (L x W x H): ストアの長さの単位（フィールド名に表示）での、箱の任意の寸法。例: 30x20x15。空欄の場合は商品の寸法を使用します。最も長い長さ、最も広い幅、積み重ねた高さです。寸法のない商品は、10 x 8 x 4 インチの箱として見積もられます。
Default product weight (kg): 重量のない商品に使用される重量。USPS の料金、重量制限、重量区分で使われます。既定値: 0.5。空欄も 0.5 kg を意味します。
固定料金（ストアの既定の通貨での料金、税抜き。API キーが入力されていない場合に使用され、USPS が料金を返さない場合の代替としても使われます。両方を空欄にすると、その場合は配送方法が非表示になります）
Country prices: 配送先の国とカートの重量ごとの料金。Add country をクリックして行を追加し、削除ボタンで行を削除します。重量区分は、XS が 1 kg まで、S が 1–2 kg、M が 2–3 kg、L が 3–5 kg、XL が 5 kg を超える場合です。空欄または 0 の区分は Price を使用します。* Default (any other country) は、その他すべての国に適用されます。
Fallback cost: どの国別料金も一致しない場合の固定料金。その場合に配送方法を非表示にするには、空欄にします。
Fixed price is: Per order（既定）は、カート全体の重量に対して料金を一度だけ請求します。Per item (each item priced by its own weight x quantity) は、商品ごとにその重量と数量を掛けて料金を決めます。USPS のリアルタイム料金は、常に荷物全体について見積もられます。
条件
Free shipping from: この配送方法が無料になる、配送が必要な商品の小計（クーポン適用後、税抜き）。その場合、USPS へのリクエストは送信されません。空欄にすると、無料配送は提供されません。
Minimum subtotal: 配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額以上の場合にのみ、この配送方法を表示します。空欄にすると、常に表示されます。
Min weight (kg): この配送方法が表示されるために必要な、カートの最小重量。0 は制限なし（既定）を意味します。
Max weight (kg): カートの重量がこの値を超えると、配送方法は非表示になります。既定値: 30。空欄は 30 kg、0 は制限なしを意味します。USPS は 70 lb（31.7 kg）までを受け付けます。それより重い荷物には固定料金が適用されます。
Geo zone: このジオゾーン内の住所に対してのみ USPS を提供します。All zones（既定）は制限なしを意味します。ジオゾーンは System > Localisation > Geo Zones で管理されます。Ignore shipping zones と併用されません。
配送ゾーンを使用しない場合の利用可否
Ignore shipping zones: ジオゾーンを確認しません。この配送方法は、以下の国に対して提供されます。
Countries: このモードの配送先の国。空欄にすると、すべての国が許可されます。このフィールドは、Ignore shipping zones がオンの場合にのみ使用されます。
詳細設定
Debug log: API リクエストと料金の計算を storage/logs/vfd_usps_debug.log.php（OpenCart 4 では system/storage/logs/vfd_usps_debug.log.php） に記録します。このファイルはウェブから読み取ることはできません。このオプションがオフの場合でも、API のエラーは常に記録されます。キー、トークン、郵便番号、お客様の住所は記録されません。ファイルが 5 MB に達すると、vfd_usps_debug.old.log.php に移動され、新しいログが開始されます。
Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログを消去します。
Remove data on uninstall: オンの場合、拡張機能をアンインストールすると、USPS の設定とログが削除されます。キャッシュされた料金は常に削除されます。注文済みの注文の USPS サービスは、常に保持されます。オフの場合、再インストール用に設定が保持されます。
インポート / エクスポート
Export: Download JSON をクリックすると、設定が JSON ファイルとして保存されます。Consumer Secret はエクスポートされません。
Import: 以前にエクスポートした JSON を貼り付けて、Import をクリックすると、設定が復元されます（例: 別のストアで）。値は通常の保存と同様に検証されます。保存済みの Consumer Secret は保持されます。
チェックアウト時の動作
OpenCart が配送方法を表示するとき、拡張機能に USPS の料金を問い合わせます。Geo zone が設定されていて住所がその外側にある場合、USPS は提供されません（Ignore shipping zones を使用すると、代わりに国のリストで判断されます）。Requires Shipping が Yes に設定されている商品のみが対象です。それ以外の商品は重量を加算せず、小計にも含まれません。ギフト券、ポイント、ストアクレジットは考慮されません。次に拡張機能は条件を確認します。カートの重量と最小小計です。無料配送が適用される場合、料金は 0 になり、USPS へのリクエストは送信されません。
拡張機能は USPS から OAuth トークンを取得し、有効期限が切れる少し前まで保持します。米国およびその属領（プエルトリコ、米領バージン諸島、グアム、米領サモア、北マリアナ諸島、ミクロネシア、マーシャル諸島、パラオ）への配送では、国内料金を要求し、お客様の 5 桁の郵便番号が必要です。郵便番号がない場合、リクエストは行われません。その他の国では、国際料金を要求します。
リクエストには、発送元郵便番号、カートの重量、荷物のサイズ、料金の種類が含まれます。70 lb を超える荷物には固定料金が適用されます。お客様には、選択されたサービスのうち最も安いものを含む 1 つの選択肢が表示されます。USD の料金は、ストアの既定の通貨に換算され、その通貨の小数桁数に丸められ、選択された Tax class の税金を含めてお客様の通貨で表示されます。
各見積もりは 1 時間キャッシュされます。失敗した見積もりは 10 分間記憶されます。タイムアウト、サーバーエラー、レート制限、またはキーの拒否の後、5 分間は USPS に問い合わせません。HTTP のタイムアウトは 10 秒です。
USPS が料金を返さない場合、料金は Country prices、次に Fallback cost から取得されます。いずれも該当しない場合、配送方法は非表示になります。お客様に USPS のエラーメッセージが表示されることはありません。理由はデバッグログに書き込まれます。
拡張機能は料金の計算のみを行います。郵便料金や配送ラベルの購入、集荷の予約、荷物の追跡は行わず、お客様が郵便局や受け取り場所を選ぶことも許可しません。複数の USPS サービスではなく、1 つの選択肢のみを表示します。箱詰めの機能はありません。カートは 1 つの荷物として見積もられます。保険やその他の追加サービスは含まれません。
OpenCart 4 では、お客様はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options ウィンドウで USPS を選択します。この方法は OpenCart 3 と同じように動作します。
注文
USPS で注文が行われると、拡張機能は配送料金がどのように決定されたかを保存します。Sales > Orders の注文ページには、USPS パネルが表示されます。このパネルには、USPS service（リアルタイム料金の場合は、例えば USPS Ground Advantage）、Price source（USPS live rate、Fixed price、または Free shipping）、Calculated price (excl. tax) が含まれます。これらの値は注文時に保存されます。
OpenCart 4 では、チェックアウト用の注文が 1 つだけ保持され、お客様が再度確定するたびに更新されます。保存された値もそれに合わせて更新されます。お客様が別の配送方法に変更すると、それらの値は注文から削除されます。OpenCart 4 では、USPS パネルが History セクションの上に表示されます。
ライセンスキー
この拡張機能は、vibefox.net で入手する VibeFox ライセンスキーを使用します。ライセンスブロック License — VibeFox USPS は、Extensions > Extensions > Shipping > VibeFox USPS > Edit ページの最初のブロックで、設定の上にあります。License key にキーを貼り付け、Activate をクリックしてください。その後、ブロックにはキーがマスクされて表示され、ステータス（例えばライセンスの有効期限日と、お使いのドメイン）と、次のボタンが表示されます。Check now はステータスを再確認、Change key は別のキーを入力、Remove key はこのストアからキーを削除します。その下には Product: opencart-shipping-usps の行と、Manage licenses and domains in your account のリンクがあり、後者は vibefox.net のアカウントを開きます。キーを変更できるのは、この拡張機能に対する Modify 権限を持つ管理者ユーザーのみです。ブロックのテキストは管理画面の言語に従います（英語とロシア語を含みます）。
キーが受け付けられない場合、ブロックに理由が表示されます（例: Key not found、This key belongs to another product、Domain limit reached、または日付付きの License expired on）。ストアのアドレスを変更した後、またはアカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、拡張機能は最後に確認された状態で動作を続けます。
1 つのキーは 1 つのドメインで使用できます。これは OpenCart の設定にあるストアのアドレスです。ストアからキーを削除しても、ドメインの枠は解放されません。枠は vibefox.net のアカウントで解放してください。
有効なキーがない場合、チェックアウトで USPS はお客様に表示されず、料金も計算されません。同じブラウザで管理画面にログインしている管理者ユーザーには、(unlicensed — visible to admins only) と表示された状態で、ストアにこの方法が表示されます。そのため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 ではこのプレビューは利用できません。ストアは管理画面へのログインを認識しないため、有効なキーがない場合はすべてのユーザーに対してこの方法が非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると 7 日間非表示になります。既存の注文には影響しません。
ライセンスの有効期限が切れた場合も拡張機能は動作を続けますが、アップデートとサポートを利用するには更新が必要です。ステータスは、管理画面の Dashboard または Edit ページを開いたときに自動的に再確認されます。キーの入力後最初の 14 日間は 1 日に 1 回、その後は週に 1 回です。cron ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
チェックアウトに USPS が表示されない: ライセンスが有効であり、Enable USPS shipping がオンになっていることを確認してください。Geo zone を確認するか、Ignore shipping zones をオンにして Countries を確認します。重量制限と Minimum subtotal を確認します。有効な USPS キーがない場合、この配送方法には固定料金（Country prices または Fallback cost）が必要です。商品の Requires Shipping が Yes に設定されていることを確認してください。
リアルタイム料金が表示されない: Edit ページの上部にある警告を確認してください。両方のキー、郵便番号、少なくとも 1 つのサービス、そして USD 以外のストアの場合は為替レートです。米国のお客様は郵便番号を入力する必要があります。Debug log をオンにし、チェックアウトを再読み込みして、拡張機能のページの Log フィールドを確認してください。
料金が実際の価格ではない: Test environment をオフにしてください。
ページに重量または長さの単位に関する警告が表示される: 単位が kg の重量クラスがない場合、不明な重量単位は kg として扱われます。System > Localisation > Weight Classes で kg の重量クラスを追加してください。ストアの不明な長さの単位は cm として扱われます。ストアの長さのクラスとして cm、mm、m、または in を使用してください（System > Settings、Option タブ）。
変更後に料金が古いように見える: 拡張機能のページで Save をクリックするか、Clear cached USPS token and rates をクリックしてください。
ページに "Warning: You do not have permission to modify VibeFox USPS!" と表示される: 管理者のユーザーグループには、設定の閲覧のみが許可されている可能性があります。System > Users > User Groups で、グループに extension/shipping/vfd_usps（OpenCart 3）または extension/vfd_usps/shipping/vfd_usps（OpenCart 4） の変更権限を付与してください。
開発者向け: USPS API のアドレスは、設定 vfd_usps_api_url（テスト用）で置き換えることができます。設定ページにはこの項目のフィールドはありません。
アンインストール
Extensions > Extensions に移動し、種類 Shipping を選択して、VibeFox USPS の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは常に削除されます。OpenCart は常に Enable USPS shipping、Sort order、Tax class、Geo zone をリセットします。キャッシュされた USPS トークンと料金は常に削除されます。Remove data on uninstall がオンの場合は、USPS の設定とデバッグログも削除されます。オフの場合は、他の設定が保持され、拡張機能を再インストールしたときに再び使用されます。注文済みの注文の USPS データは削除されず、既存の注文は配送方法と料金を保持します。
OpenCart 4 では、拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧で VibeFox USPS の横にある Uninstall（オレンジ色の − ボタン）をクリックしてから、Delete（赤いゴミ箱のボタン）をクリックして、アップロードしたパッケージを削除します。
USPS は各所有者の商標です。この拡張機能は USPS と提携しておらず、USPS による支持もありません。