VibeFox Shippo for OpenCart — ヘルプ
必要環境
OpenCart：3.0.x（3.0.5.0 で動作確認済み）、または 4.0.2 以降（4.1.0.3 で動作確認済み）。
PHP：8.0 以降。
Shippo アカウント：Shippo アカウントを作成し、運送業者（USPS、UPS、FedEx、DHL など）を接続または有効化して、Shippo > Settings > Advanced > API から API トークンをコピーしてください。Shippo は購入した送り状に対して課金され、料金の照会には課金されません。新しい Shippo アカウントは、リアルタイム料金が返されるようになる前に Shippo による確認が必要な場合があります。トークンがなければ、代替料金のみが使われます。
商品：商品には重量と寸法を設定してください。寸法のない商品は既定の箱サイズを使います。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。お使いのコンピューターで解凍してください。README.txt、OpenCart 3 用のパッケージ vfd_shippo-oc3-(version).ocmod.zip、OpenCart 4 用のパッケージ vfd_shippo.ocmod.zip が含まれています。お使いの OpenCart バージョンに対応するパッケージだけをインストールしてください。ライセンスキーは両方のバージョンで共通です。
OpenCart 3
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_shippo-oc3-(version).ocmod.zip を選択します。本拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。Installer を使わず、パッケージの upload フォルダーの内容をストアのルートフォルダーにコピーすることもできます。
2. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選択します。VibeFox Shippo を見つけて、Install（緑色の + ボタン）をクリックします。
3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。
4. Edit ページ上部のライセンスブロックにある License key 欄に VibeFox ライセンスキーを入力し、Activate をクリックします（License key を参照）。
5. Shippo の API トークンを貼り付け、Ship from の住所を入力します。リアルタイム料金には郵便番号が必要です。
6. Shippo rate currency を選択します（米国から発送する場合は USD）。ストアの既定通貨が異なる場合は、Exchange rate を入力します。
7. 必要に応じて代替料金を入力し、Enable Shippo shipping をオンにして、Save をクリックします。
OpenCart 4
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_shippo.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変更したパッケージは動作しません。
2. パッケージは同じページのインストール済み拡張機能の一覧に表示されます。その横の Install（緑色の + ボタン）をクリックします。
3. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選択します。VibeFox Shippo を見つけて Install（緑色の + ボタン）をクリックし、次に Edit（鉛筆のボタン）をクリックします。
4. ライセンスキーと設定は、OpenCart 3 の手順 4 から 7 と同じように入力します。設定ページとそのフィールドは両方のバージョンで同じです。
インストール後は、Enable Shippo shipping をオンにして保存するまで、この配送方法はオフのままです。アンインストール後に拡張機能を再インストールした場合は、保持されていた Shippo の設定が再び使われます。
設定
すべての設定は拡張機能のページにあります：Extensions > Extensions > Shipping > VibeFox Shippo > Edit。セクションは左側に一覧表示されます。Save ボタンを押すと、ページを再読み込みせずにページ全体が保存されます。保存するたびに、キャッシュされた Shippo の料金も削除されます。この拡張機能の変更権限を持つ管理者ユーザーだけが設定を保存できます。
ページ上部の警告は、この方法が表示されることがない場合や、リアルタイム料金を使えない場合を知らせます。API トークンがない、発送元の郵便番号または国がない、為替レートがない、またはストアの重量単位や長さ単位が拡張機能で認識されない場合です（System > Settings の Local タブで kg、g、lb、oz、および cm、mm、m、in を使用してください）。テスト用トークンが設定されている場合は通知が表示されます。保存時に、無効な名前、数値ではない値、負の数や負の価格セル、Maximum weight (kg) より大きい Minimum weight (kg)、または整数ではない並び順は、エラーとして報告されます。修正するまで、何も保存されません。
一般
Enable Shippo shipping：チェックアウトでこの方法を提供します。これは Extensions > Extensions > Shipping における拡張機能の状態です。
Name：チェックアウトでお客様に表示される配送方法名。既定：Shippo Shipping。必須。最大 64 文字で、< > ; = # { } の文字は使用できません。
Tax class：送料の税クラス、または No tax。Shippo の料金には販売税が含まれていません。No tax では提示された料金がそのまま表示されます。税クラスを選ぶと、税務ルールに従って送料に税金が加算されます。
Sort order：チェックアウトで、配送方法の中でこの方法が表示される順番です。整数。
Shippo アカウント
API token：Shippo の API トークンです。本番ストアで実際の料金を取得するにはライブトークン（shippo_live_...）を、Shippo のテスト料金を取得するにはテストトークン（shippo_test_...）を使用してください。トークンは Shippo にのみ送信され、ログには記録されません。保存後、このフィールドは空になり、Saved — leave empty to keep it. と表示されます。変更する場合のみ新しい値を入力してください。
Remove the saved API token：これをオンにして保存すると、保存されたトークンが削除されます。
Allowed carriers / services：任意。カンマ区切りで入力します。運送業者は Shippo での名称（USPS、UPS、FedEx、DHL Express）で、または Shippo のサービスレベルトークン（usps_priority、ups_ground）で入力します。許可された中で最も安い料金が表示されます。空欄の場合は、どの運送業者の中でも最も安い料金が表示されます。
Ship from（荷物を発送する住所）
発送元の国がストアの国と同じ場合、空欄の送り主名と都道府県は、System > Settings のストア名と地域から補われます。OpenCart にはストアの番地、市区町村、郵便番号の構造化データがないため、ここで入力してください。
Sender name / company：送り主の名前です。税関申告書の署名にも使われます。空欄の場合は、ストア名が使われます。
Street address：送り主の番地です。
City：送り主の市区町村です。
State / province：2 文字の州コード（例：CA、NY）。一部の運送業者では必要です。
Postal / ZIP code：リアルタイム料金に必要です（例：94105）。
Country：発送元の国です。既定：United States。
料金
Parcels：カートを Shippo にどのように送信するかを設定します。
Default box size：ストアの長さの単位（フィールド名に表示されます）での、縦 x 横 x 高さ。例：30 x 20 x 10。Shippo には箱のサイズが必要です。カート内の商品に寸法がない場合に使われます。空欄の場合は 30 x 20 x 10 cm が使われます。読み取れない値は、保存後に通知付きで無視され、他の設定は保存されます。
Shippo rate currency：Shippo が運送業者の料金を見積もる通貨。つまり発送元の国の通貨です。USD（米国）、CAD（カナダ）、GBP（英国）、EUR（ユーロ圏）、AUD（オーストラリア）から選びます。既定：USD。Shippo がストアの既定通貨で返した料金は、常にそのまま使われます。
Exchange rate：Shippo の料金通貨 1 単位が、ストアの既定通貨で何単位にあたるか。例：0.92。両者が同じ場合は不要です。これが未設定の場合、別の通貨の料金は使われず、代替料金が適用されます。拡張機能は通貨を自動では換算しません。
代替料金（リアルタイム料金がない場合に使われます：API トークンがない、Shippo に接続できない、トークンが拒否された、または住所に対する運送業者の料金がない場合。料金はストアの既定通貨で、税抜きです。両方の欄を空欄にすると、この場合は方法を非表示にします）
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 行は、独自の行がない国に適用されます。すべてのセルが空欄のまま保存された行は 0 を請求するため、入力しない行は削除してください。
Other countries：上の表にない国の料金です（* Default 行がない場合）。空欄のままにすると、それらの国では方法が非表示になります。
条件
Free shipping from：送料が無料になる、配送が必要な商品の小計（クーポン適用後、税抜き）。その場合、Shippo へのリクエストは行われません。空欄にするとこの機能は無効になります。
Minimum subtotal：配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額以上の場合にのみ、この方法を表示します。空欄の場合は常に表示されます。
Minimum weight (kg)：この方法を表示するためのカートの最小重量。0 は制限なし（既定）を意味します。
Maximum weight (kg)：カートの重量がこの値を超えると、この方法は非表示になります。既定：30。0 は制限なしを意味します。空欄は 30 として保存されます。
配送ゾーンを使用しない場合の利用可否
通常は、ジオゾーンによって、この方法を提供する場所が決まります。別の方法として、ジオゾーンに関係なく、国ごとに提供することもできます。
Geo zone：このジオゾーン内の住所にのみこの方法を提供します。All zones（既定）は制限なしを意味します。Ignore shipping zones がオンの間は使用されません。ジオゾーンは System > Localisation > Geo Zones で管理されます。
Ignore shipping zones：ジオゾーンに含まれるかどうかに関係なく、下に指定した国に対してこの方法を提供します。
Countries：このモードでの配送先の国です。空欄の場合は、ストアで有効なすべての国を使用します。このフィールドは Ignore shipping zones がオンの場合にのみ使われます。
詳細設定
Debug log：Shippo へのリクエストを storage/logs/vfd_shpo_debug.log.php（OpenCart 4 では system/storage/logs/vfd_shpo_debug.log.php）に記録します。このファイルは Web から読み取ることはできません。このオプションがオフの場合でも、API のエラーは常に記録されます。API トークンと顧客の住所は、ログには決して記録されません。ファイルが 5 MB に達すると、vfd_shpo_debug.old.log.php に移動され、新しいログが開始されます。
Log：ログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログが空になります。
Remove data on uninstall：オンの場合、拡張機能をアンインストールすると、Shippo の設定とログが削除されます。オフ（既定）の場合は、再インストールのために保持されます。キャッシュされた料金は常に削除されます。注文とともに保存された運送業者とサービスは注文履歴の一部であるため、保持されます。
インポート / エクスポート
Export：Download JSON をクリックすると、設定を JSON ファイルとして保存します。API トークンはエクスポートされません。
Import：以前にエクスポートした JSON を貼り付け、Import をクリックすると、設定を復元します（例：別のストアでの利用）。値は通常の保存と同じように検証されます。保存済みの API トークンは変更されません。
チェックアウトでの動作
OpenCart が配送方法を表示するとき、拡張機能に Shippo の料金を問い合わせます。Geo zone が設定されている（かつ Ignore shipping zones がオフの）場合に住所がその外にあると、この方法は提供されません。Requires Shipping が Yes に設定された商品のみが計算に含まれます。それ以外の商品は重量を加算せず、小計にも含まれません。次に、拡張機能は条件を確認します。Ignore shipping zones の国、カートの重量、最低小計です。ギフト券、ポイント、ストアクレジットは考慮されません。送料無料が適用される場合、料金は 0 になり、Shippo へのリクエストは送信されません。
拡張機能は次に、ストアの発送元住所、お客様の住所、荷物を Shippo に送信します。OpenCart で郵便番号が必要な国の場合、お客様が入力するまでリクエストは待機します。国際配送の場合、商品名（選択されたオプションを含む）、数量、重量、価格を含む税関申告情報が追加されます。Shippo が運送業者の料金を返し、拡張機能は許可された中で最も安い料金を使います。料金はストアの既定通貨で計算され、小数点以下の桁数に丸められ、選択された Tax class の税金を加えた上で、お客様の通貨で表示されます。
注文ごとのモードでは、商品は 1 つの箱にまとめられます。最も大きな商品の最長辺と中間の辺、そしてすべての単位の最短辺を足し合わせたサイズです。寸法のない商品が 1 つでもあれば、荷物全体に既定の箱サイズが使われます。商品ごとのモードでは、各商品が個別の荷物として計算され、料金は数量分掛けられます。
各応答は、住所と荷物ごとに 1 時間キャッシュされます。Shippo が使用可能な料金を返さなかった場合、その住所は 10 分間記憶されます。タイムアウト、トークンの拒否、サーバーエラー、またはレート制限の後、拡張機能は 5 分間リクエストを停止し、代替料金を使います。リクエストのタイムアウトは 10 秒です。
リアルタイム料金がない場合、料金は代替料金表から取得され、次に Other countries から取得されます。どちらも適用されない場合、この方法は非表示になります。お客様にエラーが表示されることはありません。理由はデバッグログに記録されます。
この拡張機能が計算するのは料金のみです。送り状の購入、荷物の追跡、住所の検証、受け取りや持ち込みの場所の提供、保険、署名オプション、返品ラベルは行いません。すべてのサービスの一覧ではなく、許可された中で最も安い料金のみが表示されます。上記の詰め込み以外の箱詰め機能はなく、料金の上乗せや手数料もありません。
OpenCart 4 では、お客様はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options ウィンドウで Shippo を選択します。この方法は OpenCart 3 と同じように動作します。
注文
リアルタイムの Shippo 料金で注文が行われると、拡張機能は選択された Carrier / service を保存し、注文ごとに 1 個の荷物の場合は Estimated delivery days も保存します。Sales > Orders で注文を開くと、注文履歴の上にある Shippo パネルに表示されるため、Shippo で対応する送り状を購入できます。データは注文とともに保存されます。その後カートや設定を変更しても、データは変わりません。方法をオフにした後もパネルは表示されます。代替料金または送料無料の注文には、Shippo パネルはありません。
OpenCart 4 は、チェックアウトの注文を 1 つ保持し、お客様が再度確定するたびにその注文を更新します。保存された Shippo の料金も一緒に更新されます。お客様が別の配送方法に変更した場合、または代替料金が適用されるようになった場合、保存された料金は注文から削除されます。
ライセンスキー
本拡張機能は、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Shippo は、Extensions > Extensions > Shipping > VibeFox Shippo > Edit の設定の上にある最初のブロックです。キーを License key に貼り付け、Activate をクリックしてください。その後、ブロックにはキーがマスクされた状態で表示され、ステータス（ライセンスの有効期限日やドメインなど）と、ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key のボタンが表示されます。その下には Product: opencart-shipping-shippo の行と、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 つのドメインで使用できます。OpenCart 設定にあるストアのアドレスです。ストアからキーを削除しても、ドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。
有効なキーがない場合、Shippo の配送方法はチェックアウト時にお客様に表示されず、料金も計算されません。同じブラウザで管理画面にログインしている管理者ユーザーには、ストアで引き続きこの方法が表示され、(unlicensed — visible to admins only) と印が付きます。そのため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 ではこのプレビューは利用できません。ストアは管理者のログインを認識しないため、有効なキーがない場合、この方法は全員に対して非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると、7 日間非表示になります。既存の注文には影響しません。
ライセンスの有効期限が切れても、拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。ステータスは、管理画面の Dashboard または Edit ページを開いたときに自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日に 1 回、その後は週に 1 回です。cron ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
チェックアウトに Shippo が表示されない：ライセンスが有効で、Enable Shippo shipping がオンになっていることを確認してください。Geo zone（または、Ignore shipping zones がオンの場合は Countries）、重量制限、Minimum subtotal を確認してください。リアルタイム料金がない場合は、その国、* Default、または Other countries に料金が設定されていることを確認してください。商品の Requires Shipping が Yes に設定されていることを確認してください。
リアルタイム料金が表示されない：Debug log をオンにし、チェックアウトを再読み込みして、拡張機能ページの Log フィールドを確認してください。よくある原因は次のとおりです。API トークンまたは発送元の郵便番号がない。ストアの既定通貨が Shippo の料金通貨と異なり、為替レートがない。お客様がまだ郵便番号を入力していない。Shippo アカウントのどの運送業者もその住所に対応していない。Shippo アカウントがまだ確認されていない。
本番ストアでテスト料金が表示される：テストトークン（shippo_test_...）は Shippo のテスト料金を返します。ライブトークン（shippo_live_...）を使用してください。
想定外の国で送料が無料になる：料金表に空の行、特に空の * Default 行がないか確認してください。すべてのセルが空欄の行は 0 を請求します。
重量や箱のサイズが不正確：ページに不明な重量または長さの単位の警告が表示される場合は、System > Settings の Local タブで、kg、g、lb、oz の重量クラスと、cm、mm、m、in の長さクラスを設定してください。
変更後に料金が古く見える：拡張機能ページで Save をクリックしてください。これにより、キャッシュされた Shippo の料金が消去されます。
ページに "Warning: You do not have permission to modify VibeFox Shippo!" と表示される：管理者のユーザーグループには、設定の閲覧権限しかない可能性があります。System > Users > User Groups で、extension/shipping/vfd_shippo（OpenCart 3）または extension/vfd_shippo/shipping/vfd_shippo（OpenCart 4）の変更権限をグループに付与してください。
開発者向け：Shippo の API アドレスは、設定 vfd_shpo_api_url（テスト用）で置き換えることができます。設定ページにはこの項目の入力欄はありません。
アンインストール
Extensions > Extensions に移動し、種類として Shipping を選択して、VibeFox Shippo の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは常に削除されます。OpenCart は常に Enable Shippo shipping、Sort order、Tax class、Geo zone をリセットします。キャッシュされた料金は常に削除されます。Remove data on uninstall がオンの場合は、Shippo の設定とデバッグログも削除されます。オフの場合は、他の設定が保持され、拡張機能を再インストールしたときに再び使われます。既存の注文は、配送方法、料金、Shippo の運送業者とサービスのデータを保持します。
OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧で VibeFox Shippo の横にある Uninstall（オレンジ色の − ボタン）をクリックしてから、Delete（赤いゴミ箱のボタン）をクリックして、アップロードしたパッケージを削除してください。
Shippo は、各所有者の商標です。本拡張機能は Shippo との提携や承認を受けたものではありません。