VibeFox Instabee for PrestaShop — ヘルプ

要件

PrestaShop：8.0 から 9.x。

PHP：8.0 以降。古いバージョンの PHP では、モジュールはインストールされません。

Budbee API 認証情報（宅配ボックスの選択にのみ必要）：API キーと API シークレット。Instabee が配送契約のある加盟店に発行します。Instabee の担当者に問い合わせるか、Instabee の加盟店ポータルをご利用ください。API のドキュメントは developer.budbee.com にあります。認証情報がなくても、配送業者は固定料金で機能しますが、購入者は宅配ボックスを選択できません。

VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。

インストール

1. 管理画面で Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択してください。

2. アップロードが完了したら、Configure をクリックします。後からモジュール一覧で VibeFox Instabee を探し、Configure をクリックすることもできます。

3. Configure ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。

4. Prices セクションに入力し、宅配ボックスのセレクター用に、Budbee の API key と API secret を入力します（設定を参照）。Save をクリックします。

インストール時に、モジュールは配送時間テキスト Delivery to an Instabee parcel box を設定した Instabee parcel box 配送業者を作成します。この配送業者は、すべての顧客グループと、スウェーデン、フィンランド、デンマーク、オランダ、ベルギーのゾーンに割り当てられます。ゾーン、顧客グループ、配送時間、ロゴは Shipping > Carriers で変更できます。ここでは料金を設定しないでください。料金は常にモジュールから取得されます。

設定

すべての設定は、モジュールページにあります：Modules > Module Manager > VibeFox Instabee > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。

設定の上に表示される警告は、次の場合に表示されます：API 認証情報が片方だけ入力されている場合、API 認証情報がない場合、国別料金も予備の送料もない場合、直近の Budbee API リクエストが失敗した場合（日時と理由を表示）、Instabee 配送業者が見つからない場合、ショップの重量単位が認識されない場合（International > Localization の Local units で kg、g、lb、oz のいずれかを設定してください）。設定を保存するたびに、キャッシュされた宅配ボックスの一覧と直近の API エラーが消去されます。メソッド名または税のステータスが無効な場合、または Min weight (kg) が Max weight (kg) より大きい場合は、何も保存されず、エラーが表示されます。

General

Enable/Disable：配送業者をオンまたはオフにします。これは Shipping > Carriers の配送業者のステータスと同じスイッチです。

Method name：チェックアウト時に購入者に表示される配送業者の名前です。既定値：Instabee parcel box。必須、最大 64 文字。

Tax status：None は、以下の料金が最終価格であることを意味します。税ルールを選んだ Taxable は、以下の料金に、そのルールの配送料の税金を PrestaShop が加算することを意味します。

宅配ボックスセレクター（Budbee API）

API 認証情報があると、購入者はチェックアウト時に郵便番号近くの宅配ボックスを選択でき、そのボックスは注文に保存されます。両方の項目が必要です。両方が設定されるまで、セレクターはオフのままです。

API key：Budbee の API キー（HTTP Basic のユーザー名）。

API secret：Budbee の API シークレット（HTTP Basic のパスワード）。ログには決して書き込まれません。

保存後、両方の項目は空欄のままになり、Saved - leave empty to keep it. と表示されます。変更したい場合のみ、新しい値を入力してください。保存済みの認証情報を削除するには、Remove the saved API key and secret にチェックを入れて保存します。何も保存されていない場合、ページには No credentials saved. と表示されます。

Test environment：Budbee のステージング API（api.staging.budbee.com）を使用します。Instabee から提供されたステージング用の認証情報を使う場合にのみオンにしてください。本番ストアではオフのままにします（api.budbee.com）。既定値：オフ。

料金（セクションのタイトルには、ショップの既定通貨が表示されます）

すべての料金は、ショップの既定通貨で、税抜きで設定します。小数点はカンマとピリオドのどちらでも入力できます（49,90 = 49.90）。料金は、カートの通貨で購入者に表示されます。

Calculation type：料金の適用方法です。

Country prices：列が Country、Price、XS ≤1 kg、S ≤2 kg、M ≤3 kg、L ≤5 kg、XL >5 kg の表です。行を追加するには Add country をクリックし、行を削除するにはごみ箱のアイコンをクリックします。個別の行がないすべての国に適用される行には、* Any other country を選択します。空または 0 の区分では Price 列が使われます。Price が 0 の場合は配送無料です。国の行にカート重量に対する料金がない場合は、* の行が使われ、それもなければ Fallback cost が使われます。数値ではない料金は消去され、警告に表示されます。重量は、ショップの重量単位から kg に換算されます。

Fallback cost：配送先の国の行にも * の行にも料金がない場合に使われます。その国では配送業者を非表示にする場合は、空欄のままにしてください。

条件

Min weight (kg)：カートの重量がこの値未満の場合、配送業者を非表示にします。既定値：0（制限なし）。

Max weight (kg)：カートの重量がこの値を超える場合、配送業者を非表示にします。宅配ボックスは約 20 kg までの荷物に対応しています。既定値：20。0 は制限なしを意味します。Min weight (kg) より小さくすることはできません。

Minimum order amount：カートの小計（配送が必要な商品、割引後、税抜き）がこの金額に達した場合にのみ、配送業者を表示します。常に表示する場合は空欄のままにしてください。

Free shipping from：配送業者が無料になるカートの小計（割引後、税抜き）です。無料にしない場合は空欄のままにしてください。

これらの項目または Fallback cost の値が数値でない場合は、保存されず、以前の値が残り、警告で該当する項目名が示されます。

配送ゾーンを使わない場合の提供

通常、配送業者は Shipping > Carriers で紐付けられた配送ゾーンで提供されます。代わりに、ここで国のリストに対して有効にすることもできます。

Ignore shipping zones：配送業者のゾーンに下記の国が含まれていなくても、下記の国で配送業者を提供します。配送業者は、後から作成されたゾーンを含め、有効なすべてのゾーンに紐付けられます。このオプションを再度オフにすると、配送業者は以前のゾーンに戻ります。

Countries：このモードでの配送先の国です。すべての国を許可する場合は空欄のままにしてください。この項目は、Ignore shipping zones がオンのときにのみ使われます。

詳細設定

Debug log：デバッグメッセージを、モジュールフォルダー内の logs/vfd_ibee_debug.log.php に書き込みます。このファイルはウェブからは開けません。このオプションがオフでも、API エラーは常に記録されます。API キーと顧客データは、ログに決して記録されません。

Log：ログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログを空にできます。

Remove data on uninstall：オンの場合、モジュールをアンインストールすると、設定と配送業者が削除されます。オフの場合、アンインストールでは配送業者をオフにするだけです。注文に保存された宅配ボックスは、常に保持されます。

チェックアウト時の動作

配送ステップで、PrestaShop はモジュールに Instabee の料金を問い合わせます。対象となるのは実物の商品のみです。バーチャル商品は重量に加算されず、注文金額にも含まれません。モジュールは、カートの重量、最低注文金額、そして Ignore shipping zones を使用している場合は許可された国の条件を確認します。カートの小計が Free shipping from に達した場合、料金は 0 になります。それ以外の場合、料金は配送先の国の Country prices の行、* の行、または Fallback cost から取得されます。料金がない場合、配送業者は非表示になります。

購入者が Instabee 配送業者を選択し、API 認証情報が設定されている場合、スウェーデン、フィンランド、デンマーク、オランダ、ベルギーの場合は、配送業者の下に Parcel box ブロックが表示されます。このブロックには、配送先住所の郵便番号近くの宅配ボックスが、距離順に、名前、住所、距離とともに表示されます。購入者は別の郵便番号を入力して、Search をクリックする（または Enter キーを押す）ことができます。郵便番号が入力されるまで、ブロックは郵便番号を求めます。宅配ボックスが見つからない場合は、購入者に別の郵便番号を試すか、別の配送方法を選ぶよう促されます。その他の国では、宅配ボックスなしで配送業者が提供されます。

宅配ボックスの選択は必須です。選択されたボックスは、その郵便番号の Budbee のリストに含まれている場合にのみ、カートに保存されます。購入者が配送ステップで Continue をクリックすると、モジュールはサーバー側でボックスを再度確認します。確認できない場合、購入者には Please choose an Instabee parcel box. と表示されます。ボックス名はブラウザからではなく、Budbee のリストから取得されます。購入者が住所の配送先の国または郵便番号を変更した場合、以前の選択は破棄されます。

モジュールが Budbee に送信するのは、配送先の国と郵便番号だけです。氏名、住所、メールアドレス、注文データは送信しません。宅配ボックスの一覧は、郵便番号ごとに 12 時間、宅配ボックスがない郵便番号は 1 時間、失敗したリクエストは 5 分間キャッシュされます。そのため、API が遅い、または停止している場合でも、チェックアウトページの更新が遅くなることはありません。チェックアウトページ自体は Budbee を待つことはありません。一覧は、配送業者が選択されるとすぐにバックグラウンドで読み込まれます。API のタイムアウトは 10 秒です。

Budbee API に接続できない場合、購入者には Parcel boxes cannot be loaded right now. You can place the order without choosing a box - the shop will assign one. と表示されます。その注文にはフラグが付き、配送を手配するときに貴店がボックスを選択します。以前に選択されたボックスで、その時点で確認できないものは保持され、未確認としてマークされます。

セレクターは Classic と Hummingbird テーマで動作します。注文が入った後に Shipping > Carriers で配送業者を編集すると、PrestaShop はそれを新しいバージョンの配送業者として保存します。モジュールは自動的に新しいバージョンに従います。

本モジュールは、リアルタイムの運賃計算、配送の手配、伝票の印刷、追跡番号や追跡メールの発行、Budbee Home の配達時間枠の提供、地図の表示は行いません。選択した宅配ボックス宛の荷物は、Instabee / Budbee の加盟店ツールで手配してください。

受け取り場所

注文が作成されると、ボックスはもう一度確認され、注文に保存されます。それ以降、ストアフロントからボックスを変更することはできません。ボックスは次の場所に表示されます：

管理画面の注文ページ：ボックスの名前、住所、Box ID を表示する Instabee parcel box ブロックです。チェックアウト時にボックスを確認できなかった場合は、not verified (Budbee API was unavailable at checkout) と表示されます。API が利用できなかったためにボックスが選択されなかった場合、ブロックには Not chosen - the Budbee API was unavailable at checkout. Choose the box when you book the shipment. と表示されます。

注文確認ページと顧客アカウントの注文詳細：Instabee parcel box: ボックスの名前と住所を表示します。

注文メール：購入者宛ての注文確認メールでは、配送業者名にボックスが追加されます。ストア宛ての新規注文メール（PrestaShop の Mail alerts モジュールによるもの）にも、ボックス ID が表示されます。API が利用できなかったためにボックスが選択されなかった場合、ストア宛てのメールのみがそのことに言及します。

ライセンスキー

本モジュールは、vibefox.net から取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Instabee は、Modules > Module Manager > VibeFox Instabee > Configure ページの最初のブロックで、設定の上にあります。キーを License key に入力し、Activate をクリックしてください。その後、ブロックにはキーがマスクされて表示され、ステータス（ライセンスの有効期限日やドメインなど）と、ボタン Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このショップからキーを削除）が表示されます。その下には、Product: presta-shipping-instabee の行と、Manage licenses and domains in your account のリンクがあり、vibefox.net のアカウントが開きます。キーを変更できるのは、モジュールの Configure 権限を持つ従業員だけです。ブロックのテキストは管理画面の言語に従います（英語とロシア語を含みます）。

キーが受け付けられない場合、ブロックにその理由が表示されます。例：Key not found、This key belongs to another product、Domain limit reached、License expired on と日付。ショップのアドレスを変更した後、またはアカウントでドメインの枠を解放した後に、Check now をクリックしてください。ライセンスサーバーに接続できない場合、モジュールは最後に確認されたステータスのまま動作し続けます。

1 つのキーは 1 つのドメインで使用できます。メインショップのドメインを指し、マルチストア構成でも同様です。ショップからキーを削除しても、そのドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。

有効なキーがない場合、チェックアウト時に Instabee 配送業者は購入者に表示されず、料金も計算されません。PrestaShop のストアフロントは、管理画面にログインしていることを認識しないため、配送業者は管理者にも表示されません。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。

ライセンスの有効期限が切れた場合も、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。管理画面で作業している間、ステータスは自動的に再確認されます。キーを入力後最初の 14 日間は 1 日 1 回、その後は週に 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。

トラブルシューティング

チェックアウトに Instabee が表示されない：ライセンスが有効で、Enable/Disable がオンになっているか確認してください。Shipping > Carriers で、配送業者が顧客の国のゾーンと顧客グループを対象にしているか、または Ignore shipping zones がオンで、その国が許可されているかを確認してください。その国に料金が設定されているか、* の行または Fallback cost があるかを確認してください。重量の制限と Minimum order amount を確認してください。料金が設定されていない場合は、設定の上に警告が表示されます。商品ページで、商品を特定の配送業者に限定している場合もあります。理由を Log 欄で確認するには、Debug log をオンにしてください。

購入者に宅配ボックスの一覧が表示されない：一覧が表示されるのは、API key と API secret の両方が入力され、国がスウェーデン、フィンランド、デンマーク、オランダ、ベルギーのいずれかで、郵便番号が入力された後だけです。直近の API エラーは設定の上に表示されます。詳細は、モジュールページの Log 欄にあります。さらに詳しく確認するには、Debug log をオンにしてください。

ログに HTTP 401 または 403 が出ている：Budbee が API キーまたはシークレットを拒否しました。それらを確認し、Test environment が認証情報と一致しているかを確認してください（ステージング用の認証情報は、テスト環境がオンの場合にのみ使用できます）。

郵便番号に対応する宅配ボックスがない：Budbee はその郵便番号に対応していません。購入者は、別の郵便番号を検索するか、別の配送方法を選択できます。

購入者が配送ステップから先に進めない：Budbee API に接続できない場合を除き、一覧から宅配ボックスを選択する必要があります。検索した郵便番号の一覧にないボックスは保存されず、購入者には This parcel box is not in the Budbee list for the postal code. Please choose the parcel box again. と表示されます。

変更後に古いボックス一覧が表示される：モジュールページで Save をクリックしてください。これにより、キャッシュされたボックス一覧が消去されます。

Instabee 配送業者が見つからないと表示される：Shipping > Carriers で配送業者が削除されています。Modules > Module Manager でモジュールをリセットすると、再作成されます。The settings were saved, but the carrier could not be updated. というメッセージも同様です。リセットしても配送業者のステータスは保持されます。オフにした配送業者は、オフのままです。

アンインストール

Modules > Module Manager に移動し、VibeFox Instabee の横にあるメニューを開いて、Uninstall を選択します。ライセンスキーとライセンスステータスは、常に削除されます。キャッシュされた宅配ボックスの一覧は、常に削除されます。Remove data on uninstall がオンの場合、配送業者は削除されます（注文の履歴は残ります）。また、設定、ログ、そして注文にならなかったカートで選択されたボックスも削除されます。オフの場合、配送業者はオフになるだけで、すべての設定は保持されます。モジュールを再インストールすると、保存されていた配送業者には、以前のステータスが戻ります。注文に保存された宅配ボックスは、常に保持されます。

Instabee および Budbee は、それぞれの所有者の商標です。本モジュールは Instabee または Budbee と提携しておらず、両社による推奨も受けていません。