VibeFox Shippo for PrestaShop — ヘルプ
要件
PrestaShop: 8.0 から 9.x。
PHP: 8.0 以降。モジュールは古い PHP バージョンへのインストールを拒否します。
Shippo アカウント: Shippo アカウントを作成し、配送業者（USPS、UPS、FedEx、DHL など）を接続または有効にして、Shippo > Settings > Advanced > API から API トークンをコピーします。Shippo は料金の照会ではなく、購入したラベルに対して課金します。新しい Shippo アカウントは、リアルタイム料金が返される前に Shippo による確認が必要な場合があります。トークンがない場合は、代替料金のみが使用されます。
商品: 商品には重量と寸法を設定してください。寸法が設定されていない商品は、デフォルトの箱サイズを使用します。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
1. 管理画面で Modules > Module Manager を開き、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックするか、後でモジュール一覧から VibeFox Shippo を探して Configure をクリックします。
3. Configure ページ上部のライセンスブロックの License key に、VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。
4. Shippo API トークンを貼り付け、Ship from の住所を入力します。リアルタイム料金には郵便番号が必要です。
5. Shippo rate currency を選択します（米国から発送する場合は USD）。ショップのデフォルト通貨が異なる場合は、Exchange rate を入力します。
6. 必要に応じて、国と重量の表に代替料金を入力し、Save をクリックします。
インストール時に、モジュールは配送業者 Shippo Shipping を作成します。配達日数のテキストは Shippo carriers (USPS, UPS, FedEx, DHL) です。配送業者はすべてのゾーンとすべての顧客グループに割り当てられます。ゾーン、顧客グループ、配達日数、ロゴ、サイズ制限は Shipping > Carriers で変更できます。そこで料金を設定しないでください。料金は常にモジュールから取得されます。
設定
すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Shippo > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。保存するたびに、キャッシュされた Shippo の料金も消去されます。
ページ上部の警告は、配送業者が表示されることがない場合や、リアルタイム料金を使用できない場合を知らせます。具体的には、API トークンがない、発送元の郵便番号または国がない、為替レートがない、またはショップの重量・寸法の単位がモジュールで認識されない場合です（International > Localization の Local units で、kg、g、lb、oz のいずれか、および cm、mm、m、in のいずれかを設定してください）。テスト用トークンが設定されている場合は、通知で知らされます。保存時、数値でない値、負の値、または Maximum weight (kg) より大きい Minimum weight (kg) は、エラーとして報告され、修正するまで何も保存されません。
一般
Enable Shippo shipping: 配送業者をオンまたはオフにします。これは Shipping > Carriers の配送業者ステータスと同じスイッチです。
Name: チェックアウトで購入者に表示される配送業者名。デフォルト：Shippo Shipping。必須、最大 64 文字。
Tax: 配送業者の税ルール、または No tax。Shippo の料金には消費税が含まれていません。No tax を選ぶと、料金は提示されたとおりに表示されます。税ルールを選ぶと、税ルールに従って配送料に税金が加算されます。
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）を入力します。許可された中で最も安い料金が表示されます。空欄にすると、どの配送業者でも最も安い料金が表示されます。
発送元（荷物を発送する住所。入力されていない欄は、同じ国の場合、Shop Parameters > Contact > Stores のショップ住所から補完されます）
Sender name / company: 発送者名。税関申告書の署名にも使用されます。空欄の場合は、ショップ名が使用されます。
Street address: 発送者の番地。
City: 発送者の市区町村。
State / province: 2 文字の州コード（例：CA、NY）。配送業者によっては必要です。
Postal / ZIP code: リアルタイム料金に必要です。
Country: 発送元の国。デフォルト：アメリカ合衆国。
料金
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（2 kg まで）、M（3 kg まで）、L（5 kg まで）、XL（5 kg 超）です。空欄または 0 の区分は、Price 列を使用します。* Default の行は、独自の行がない国に適用されます。新しい行は * Default として作成されます。すべてのセルが空の状態で保存された行は 0 の料金になるため、記入しない行は削除してください。
Other countries: 上の表にない国（* Default の行がない場合）の料金。空欄にすると、それらの国では配送業者が非表示になります。
条件
Free shipping from: 送料が無料になるカートの小計（割引後、税抜き）。その場合、Shippo へのリクエストは行われません。空欄にすると無効になります。
Minimum subtotal: カートの小計（割引後、税抜き）がこの金額以上の場合にのみ、配送業者を表示します。空欄の場合は常に表示されます。
Minimum weight (kg): 配送業者を表示するための最小カート重量。0 は制限なしを意味します。
Maximum weight (kg): このカート重量を超えると配送業者は非表示になります。デフォルト：30。0 は制限なしを意味します。空欄は 30 として保存されます。
配送ゾーンなしでの利用可否
通常、配送業者は Shipping > Carriers で設定された配送ゾーン内で提供されます。別の方法として、ゾーンに関係なく国ごとに提供することもできます。
Ignore shipping zones: 下記の国について、ゾーンが割り当てられているかどうかに関係なく、配送業者を提供します。これをオンにすると、後から作成されたゾーンを含むすべてのゾーンに配送業者が追加されます。オフにすると、追加されたゾーンは削除され、配送業者は独自のゾーンを維持します。
Countries: このモードの配送先の国。空欄の場合は、ショップで有効なすべての国が使用されます。この欄は Ignore shipping zones がオンの場合にのみ使用されます。
詳細設定
Debug log: Shippo へのリクエストを、モジュールフォルダ内の logs/vfd_shpo_debug.log.php に記録します。このファイルは Web からは開けません。このオプションがオフでも、API のエラーは常に記録されます。API トークンと顧客の住所は、一切記録されません。
Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログを消去できます。
Remove data on uninstall: オンの場合、モジュールをアンインストールすると、モジュールの設定、配送業者、ログが削除されます。オフの場合は、再インストールに備えてすべてが保持されます。キャッシュされた料金は常に削除されます。注文と一緒に保存された配送業者とサービスは注文履歴であるため、保持されます。
チェックアウトでの動作
配送ステップで PrestaShop はモジュールに Shippo の料金を問い合わせます。対象となるのは実物の商品のみです。仮想商品は重量に加算されず、小計にも含まれません。モジュールは最初に条件を確認します：Ignore shipping zones の国、カート重量、最低小計。送料無料が適用される場合、料金は 0 となり、Shippo へのリクエストは行われません。
次に、モジュールは発送元の住所、顧客の住所、荷物を Shippo に送信します。PrestaShop が郵便番号を必須としている国の場合、リクエストは顧客が郵便番号を入力するまで待機します。国際配送の場合は、商品名、数量、重量、価格を含む税関申告書が追加されます。Shippo は配送業者の料金を返し、モジュールは許可された中で最も安い料金を使用します。料金はショップのデフォルト通貨で計算され、その後、顧客のカート通貨で表示されます。
注文ごとのモードでは、商品は 1 つの箱にまとめられます。最も大きい商品の最も長い辺と中間の辺、およびすべての単位の最も短い辺を合計します。いずれかの商品に寸法がない場合は、荷物全体にデフォルトの箱サイズが使用されます。商品ごとのモードでは、各商品が個別の荷物として料金計算され、料金は数量を掛けたものになります。
各応答は、住所と荷物ごとに 1 時間キャッシュされます。Shippo が使用可能な料金を返さなかった場合、その住所は 10 分間記録されます。タイムアウト、トークンの拒否、サーバーエラー、またはレート制限の後は、モジュールが 5 分間リクエストを停止し、代替料金を使用します。リクエストのタイムアウトは 10 秒です。
リアルタイム料金がない場合、料金は代替料金の表から取得され、次に Other countries から取得されます。どちらも該当しない場合は、配送業者が非表示になります。顧客にエラーが表示されることはありません。理由はデバッグログに記録されます。
注文がある配送業者を Shipping > Carriers で編集すると、PrestaShop はそれを配送業者の新しいバージョンとして保存します。モジュールは新しいバージョンに自動的に従います。
モジュールが行うのは料金の計算のみです。ラベルの購入、荷物の追跡、住所の検証、集荷・受け取り拠点の提供、保険、署名オプション、返品ラベルには対応していません。表示されるのは許可された中で最も安い料金のみで、すべてのサービスの一覧は表示されません。上記の積み重ね以外の箱詰めは行わず、料金の上乗せや手数料も加算されません。
注文
リアルタイムの Shippo 料金で注文が行われると、モジュールは選択された Carrier / service を保存し、注文ごとに 1 つの荷物の場合は Estimated delivery days も保存します。これらは管理画面の注文ページにある Shippo ブロックに表示されるため、Shippo で対応するラベルを購入できます。データは注文と一緒に固定されます。その後カートを変更しても、データは変わりません。代替料金または送料無料の注文には、Shippo ブロックは表示されません。
ライセンスキー
このモジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Shippo は、Modules > Module Manager > VibeFox Shippo > Configure の最初のブロックで、設定の上にあります。キーを License key に貼り付けて Activate をクリックします。その後、ブロックにはキーがマスクされて表示され、ステータス（例：ライセンスの有効期限日とドメイン）と、ボタン Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このショップからキーを削除）が表示されます。その下には Product: presta-shipping-shippo の行と、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 アカウントで枠を解放してください。
有効なキーがない場合、Shippo の配送業者はチェックアウト時にお客様に表示されず、料金も計算されません。PrestaShop のフロントエンドは、バックオフィスにログインしていることを認識しないため、配送業者はあなたにも表示されません。キーを購入する前にモジュールを設定することはできますが、チェックアウトで試すことはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。
ライセンスの期限が切れても、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。バックオフィスで作業している間、ステータスは自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
Shippo がチェックアウトに表示されない: ライセンスが有効であること、Enable Shippo shipping がオンであることを確認してください。Shipping > Carriers で、配送業者が購入者の国のゾーンと購入者の顧客グループをカバーしていることを確認します（または Ignore shipping zones がオンで、その国が許可されていること）。重量制限と Minimum subtotal を確認してください。リアルタイム料金がない場合は、その国、* Default、または Other countries に料金が設定されているか確認します。商品ページで、商品を特定の配送業者に限定することもできます。
リアルタイム料金が表示されない: Debug log をオンにし、チェックアウトを再読み込みして、モジュールページの Log フィールドを確認してください。よくある原因：API トークンまたは発送元の郵便番号がない、為替レートがないままショップのデフォルト通貨と Shippo の料金通貨が異なる、顧客の郵便番号がまだ入力されていない、Shippo アカウントのどの配送業者もその住所に対応していない、または Shippo アカウントがまだ確認されていない。
本番ショップでテスト料金が表示される: テストトークン（shippo_test_...）は Shippo のテスト料金を返します。ライブトークン（shippo_live_...）を使用してください。
予期しない国で送料が無料になる: 料金表に空の行がないか確認してください。特に空の * Default 行に注意してください。すべてのセルが空の行は 0 になります。
変更後に料金が古く見える: モジュールページで Save をクリックしてください。これにより、キャッシュされた Shippo の料金が消去されます。
Shippo の配送業者が見つからないと表示される: Shipping > Carriers で配送業者が削除されています。Modules > Module Manager でモジュールをリセットすると、再作成されます。
アンインストール
Modules > Module Manager を開き、VibeFox Shippo の横のメニューを開いて Uninstall を選択します。ライセンスキーとライセンスステータスは常に削除されます。キャッシュされた料金は常に削除されます。Remove data on uninstall がオンの場合、配送業者は削除され（注文は履歴を保持します）、設定とログも削除されます。オフの場合、配送業者は無効になるだけで、すべての設定は保持されます。モジュールを再インストールすると、配送業者は以前のステータスに戻ります。既存の注文は、Shippo の配送業者とサービスのデータを保持します。
Shippo は、それぞれの所有者の商標です。本モジュールは Shippo とは提携しておらず、Shippo による推奨も受けていません。