VibeFox Instabee for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 でテスト済み）または 4.0.2 以降（4.1.0.3 でテスト済み）。

PHP: 8.0 以降。

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

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

インストール

このダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。コンピューターで解凍してください。README.txt、OpenCart 3 用のパッケージ vfd_instabee-oc3-(version).ocmod.zip、OpenCart 4 用のパッケージ vfd_instabee.ocmod.zip が含まれています。お使いの OpenCart のバージョンに対応するパッケージのみをインストールしてください。ライセンスキーは両方のバージョンで同じです。

OpenCart 3

1. 管理画面で Extensions > Installer に進み、Upload をクリックして、ファイル vfd_instabee-oc3-(version).ocmod.zip を選択します。本拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。インストーラーを使う代わりに、このパッケージの upload フォルダーの内容をストアのルートフォルダーにコピーすることもできます。

2. Extensions > Extensions に進み、拡張機能の種類で Shipping を選択します。VibeFox Instabee を見つけて、Install（緑色の + ボタン）をクリックします。

3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。

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

5. Prices セクションに入力し、宅配ボックスのセレクターを使う場合は Budbee の API key と API secret を入力します（「設定」を参照）。Enable/Disable をオンにして、Save をクリックします。

OpenCart 4

1. 管理画面で Extensions > Installer に進み、Upload をクリックして、ファイル vfd_instabee.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変更したパッケージは動作しません。

2. パッケージは同じページの、インストール済み拡張機能の一覧に表示されます。その横にある Install（緑色の + ボタン）をクリックします。

3. Extensions > Extensions に進み、拡張機能の種類で Shipping を選択します。VibeFox Instabee を見つけて、Install（緑色の + ボタン）をクリックし、次に Edit（鉛筆のボタン）をクリックします。

4. ライセンスキーと設定は、OpenCart 3 の手順 4 および 5 と同じように入力します。設定ページとその項目は、両方のバージョンで同じです。

インストール直後は、Enable/Disable をオンにして保存するまで、この配送方法は無効のままです。アンインストール後に拡張機能を再インストールした場合は、保持されていた Instabee の設定が再び使用されます。

設定

すべての設定は拡張機能のページにあります。Extensions > Extensions > Shipping > VibeFox Instabee > Edit です。セクションは左側に一覧表示されます。Save ボタンを 1 回押すと、ページを再読み込みせずにページ全体が保存されます。保存するたびに、キャッシュされたボックス一覧と直近の API エラーも消去されます。この拡張機能に対する変更権限を持つ管理者ユーザーだけが設定を保存できます。

設定の上部の警告は、API 認証情報が片方だけ入力されている場合、API 認証情報がない場合、国別料金もフォールバック料金もない場合、直近の Budbee API リクエストが失敗した場合（日付、時刻、理由付き）、そして、単位が kg の重量区分がストアになく、既定の重量区分の単位が認識できない場合（この場合、重量は kg として扱われます。System > Localisation > Weight Classes で kg の重量区分を追加してください）に表示されます。

Method name が空であるか長すぎる場合、Min weight (kg) が Max weight (kg) より大きい場合、Sort order が整数でない場合、または税クラスやジオゾーンが存在しない場合は、何も保存されず、エラーが表示されます。

一般

Enable/Disable: チェックアウトで Instabee を表示または非表示にします。既定値: off。

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

Tax class: None (the prices are final)（既定値）は、以下の料金が確定していることを意味します。税クラスを選ぶと、そのクラスの配送税が以下の料金に上乗せされます。

Sort order: チェックアウトの配送方法の中で Instabee が表示される順番。整数。

宅配ボックスのセレクター（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）。既定値: off。

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

すべての料金は、ストアの既定通貨で、税抜きで指定します。小数点はカンマでもピリオドでも入力できます（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 が使われます。保存時には、0 以上の数値ではない料金は消去され、不明な国の行は削除されます。警告にはその一覧が表示されます。商品の重量は、OpenCart の重量区分から 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 の値が 0 以上の数値でない場合は、保存されず、以前の値が残り、警告で該当する欄が示されます。

提供条件

Geo zone: このジオゾーン内の住所にのみ Instabee を提供します。All zones（既定値）は、どこでもという意味です。Ignore shipping zones がオンのときは、ジオゾーンは確認されません。ジオゾーンは System > Localisation > Geo Zones で管理します。

Ignore shipping zones: オンにすると、Geo zone は確認されず、以下の国に対して配送方法が提供されます。オフ（既定値）の場合は、Geo zone のみが適用されます。

Countries: このモードの配送先の国。すべての国を許可する場合は空欄のままにします。この欄は、Ignore shipping zones がオンの場合にのみ使用されます。

詳細設定

Debug log: デバッグメッセージを storage/logs/vfd_ibee_debug.log.php（OpenCart 4 では system/storage/logs/vfd_ibee_debug.log.php）に書き込みます。このファイルは Web から読み取ることはできません。API エラーや、API が正常に動作している間に宅配ボックスなしで行われた注文は、この設定がオフでも常に記録されます。API キーと顧客データは決して記録されません。ファイルが 5 MB に達すると、vfd_ibee_debug.old.log.php に移動され、新しいログが開始されます。

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

Remove data on uninstall: オンにすると、拡張機能をアンインストールしたときに、設定、キャッシュされたボックス一覧、ログ、未完了のチェックアウトのボックスが削除されます。オフ（既定値）の場合、再インストールに備えて設定は保持されます。注文に保存された宅配ボックスは常に保持されます。

インポート / エクスポート

Export: Download JSON をクリックすると、設定が JSON ファイルとして保存されます。API キーとシークレットはエクスポートされません。

Import: 以前にエクスポートした JSON を貼り付けて Import をクリックすると、設定を復元できます（別のストアに移行する場合など）。値は通常の保存と同じように検証されます。保存されている API キーとシークレットは保持されます。

チェックアウトでの動作

OpenCart が配送方法を表示するとき、拡張機能に Instabee の料金を問い合わせます。Ignore shipping zones がオンの場合、その国が許可されているときにのみ Instabee が提供されます（ジオゾーンは確認されません）。それ以外の場合、Geo zone が設定されていて住所がその外にあれば、Instabee は提供されません。Requires Shipping が Yes に設定された商品のみが計算に含まれます。他の商品は重量に加算されず、注文金額にも含まれません。注文金額は、配送が必要な商品の料金の合計で、クーポン割引後、税抜きの金額です。拡張機能はカート重量と最低注文金額を確認します。小計が Free shipping from に達した場合、料金は 0 になります。それ以外の場合、料金は配送先の国の Country prices の行、* の行、または Fallback cost から取得されます。料金がない場合、配送方法は非表示になります。料金は、貴店の既定通貨で計算され、その通貨の小数桁に丸められ、選択した Tax class の税額を加えて購入者の通貨で表示されます。

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

宅配ボックスは必須です。選択したボックスは、その郵便番号の Budbee のリストに含まれている場合にのみ、チェックアウト用に保存されます。Search をクリックせずに入力された郵便番号は使用されません。購入者が配送方法の手順で Continue をクリックすると、拡張機能はサーバー上でボックスを再度確認します。確認できない場合、購入者には Please choose an Instabee parcel box. と表示されます。ボックス名はブラウザからではなく、Budbee のリストから取得されます。購入者が配送先の国または住所の郵便番号を変更すると、以前の選択は破棄されます。

OpenCart 4 では、チェックアウトページの配送方法のブロックで Choose をクリックし、Shipping method options のウィンドウで Instabee を選択します。Parcel box のブロックは、そのウィンドウ内の Instabee の選択肢の下に表示され、同じように動作します。ウィンドウの Continue ボタンは、リストからボックスを選ばない限り先に進みません。表示されるメッセージも同じです。

拡張機能が 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. と表示されます。注文にはフラグが付けられ、配送を手配するときにボックスを選択します。以前に選択されたボックスで、その時点では確認できないものは保持され、未確認としてマークされます。

拡張機能は、リアルタイムの料金計算、配送の手配、ラベルの印刷、追跡番号や追跡メールの発行、Budbee Home の配送時間帯の提供、地図の表示は行いません。選択したボックス宛ての荷物は、Instabee / Budbee の販売者ツールで手配してください。

受け取りポイント

注文が作成されると、ボックスは改めて確認され、注文に保存されます。その後は、ストアのフロントエンドから変更できません。OpenCart 4 では、チェックアウトごとに 1 つの注文が保持され、顧客が確定し直すたびに更新されます。その際、注文のボックスも一緒に更新されます。顧客がその注文を別の配送方法に切り替えると、そのボックスは削除されます。ボックスは次の場所に表示されます。

注文の配送方法: ボックスは方法名に追加されます。例えば、Instabee parcel box:（方法名）に続けてボックス名と住所が表示されます。このテキストは、管理画面と購入者のアカウントの注文ページ、注文確認メール、請求書に表示されます。

管理画面の注文ページ（Sales > Orders）: ボックス名、住所、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. と表示されます。このパネルは読み取り専用で、配送方法がオフの場合でも表示されます。OpenCart 4 では、このパネルは History の上に表示されます。

ストアへの新規注文メール: ボックス名と ID、または Instabee parcel box: not chosen (Budbee API unavailable at checkout).

ライセンスキー

この拡張機能は、vibefox.net から取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Instabee は、Extensions > Extensions > Shipping > VibeFox Instabee > Edit ページの最上部、設定の上にあります。License key にキーを入力し、Activate をクリックしてください。その後、ブロックにはキーがマスクされた状態で表示され、ステータス（ライセンスの有効期限日やご利用のドメインなど）と、ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key のボタンが表示されます。その下には Product: opencart-shipping-instabee の行と、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 のアカウントで枠を解放してください。

有効なキーがない場合、Instabee の配送方法はチェックアウトで購入者に表示されず、料金も計算されません。ただし、同じブラウザで管理画面にログインしている管理者ユーザーには、ストアでこの方法が (unlicensed — visible to admins only) と表示されます。そのため、キーを購入する前に拡張機能の設定と動作確認を行えます。OpenCart 4 では、このプレビューは利用できません。ストアは管理画面へのログイン状態を認識しないため、有効なキーがない場合は、すべての購入者にこの方法が表示されません。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると、7 日間は非表示になります。既存の注文には影響ありません。

ライセンスの有効期限が切れても拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスは自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日に 1 回、その後は週に 1 回です。cron ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは必ず削除されます。

トラブルシューティング

チェックアウトに Instabee が表示されない: ライセンスが有効であること、Enable/Disable がオンであることを確認してください。Geo zone を確認するか、Ignore shipping zones がオンの場合は、その国が Countries で許可されていることを確認してください。その国に料金があるか、* の行や Fallback cost があることを確認してください。重量の制限と Minimum order amount を確認し、商品の Requires Shipping が Yes に設定されていることを確認してください。料金が設定されていない場合は、設定の上部に警告が表示されます。理由を 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 をクリックしてください。キャッシュされたボックス一覧が消去されます。

ページに「Warning: You do not have permission to modify VibeFox Instabee!」と表示される: 管理者のユーザーグループには、設定の閲覧権限しかない可能性があります。System > Users > User Groups で、そのグループに extension/shipping/vfd_instabee（OpenCart 3）または extension/vfd_instabee/shipping/vfd_instabee（OpenCart 4）の変更権限を付与してください。

アンインストール

Extensions > Extensions に進み、種類で Shipping を選択し、VibeFox Instabee の横にある Uninstall（赤色の − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは常に削除されます。OpenCart は、Enable/Disable、Sort order、Tax class、Geo zone を常にリセットします。キャッシュされたボックス一覧は常に削除されます。Remove data on uninstall がオンの場合は、設定、ログ、注文にならなかったチェックアウトで選択されたボックスも削除されます。オフの場合、その他の設定は保持され、拡張機能を再インストールしたときに再び使用されます。注文に保存された宅配ボックスは常に保持され、既存の注文は配送方法と料金をそのまま保持します。

OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に進み、インストール済み拡張機能の一覧で VibeFox Instabee の横にある Uninstall（オレンジ色の − ボタン）をクリックします。次に、アップロードしたパッケージを削除するために Delete（赤色のゴミ箱ボタン）をクリックしてください。

Instabee と Budbee は、それぞれの所有者の商標です。本拡張機能は Instabee または Budbee とは提携しておらず、両社の承認も受けていません。