VibeFox bpost Cubee for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 で動作確認済み）または 4.0.2 以降（4.1.0.3 で動作確認済み）。

PHP: 8.0 以降。

bpost Shipping Platform アカウント（受け取りポイントセレクターのみに必要）: この拡張機能は bpost Shipping Platform API を通じて受け取りポイントを検索します。plugins.bpost.be で bpost Shipping Platform アカウントにログインし、Settings > Key management でキーを作成してください。必要な値は 3 つです: Account ID（公開キー）、Passphrase（秘密キー）、App ID（X-APPID）。App ID は bpost が貴社の連携用に発行します。bpost の e-commerce サポート（eol@bpost.be）にお問い合わせください。また、契約のキャリア ID（68 = bpost）も必要です。キーが完全でなくても、この方法は固定料金で機能しますが、購入者に受け取りポイントを選ぶよう求めることはありません。

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

インストール

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

OpenCart 3

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

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

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

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

5. 料金を入力します（例: BE=4.95 と *=9.95）。受け取りポイントセレクターを使う場合は bpost API キーも入力します（設定の項を参照）。Enable/Disable をオンにして、Save をクリックします。

OpenCart 4

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

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

3. Extensions > Extensions に移動し、種類 Shipping を選択します。VibeFox bpost Cubee を見つけて、Install（緑色の + ボタン）をクリックし、次に Edit（鉛筆のボタン）をクリックします。

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

インストール後は、オンにして保存するまで、この方法はオフのままです。アンインストール後に拡張機能を再インストールすると、保持しておいた設定が再び使用されます。

設定

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

一部のエラーは保存を止めるため、何も保存されません: 64 文字を超える Name、整数ではない Sort Order、または不明な税クラスやジオゾーン。その他の問題は警告として報告され、残りは保存されます。数値ではない、または負の値の重量や金額は保存されず、以前の値が保持されます。Min weight (kg) が Max weight (kg) より大きい場合、重量は保存されません。読み取れなかった Country prices の行は一覧表示されて無視されます。Size prices の値でサイズが 1 つも認識されなかった場合は報告されます。

ページ上部には、何かによって方法またはセレクターが黙って非表示になっている場合に警告が表示されます: 受け取りポイントセレクターは有効だが API キーが不完全である場合、ベルギー（BE）の料金がなく既定料金（*=料金）もない場合、bpost API への最後の接続が失敗した場合、またはストアに単位 "kg" の重量クラスがない場合（System > Localisation > Weight Classes）。最後の場合、商品の重量は単位名（kg、g、lb、oz）に従って読み取られます。

全般

Enable/Disable: チェックアウトで bpost パーセルロッカー配送を表示するかどうかを切り替えます。既定値: オフ。

Name: チェックアウトで購入者に表示される配送方法の名称です。既定値: bpost parcel locker。空欄の場合は既定値が使われます。最大 64 文字。

Tax Class: このクラスの税金が料金に加算されます。--- None ---（既定）は、料金が最終価格であることを意味します。

Sort Order: 配送方法の一覧での、この方法の位置です。

bpost API（受け取りポイント検索）（受け取りポイントセレクターにのみ必要）

Account ID (public key): bpost Shipping Platform アカウントの公開キーです。plugins.bpost.be の Key management で確認できます。このフィールドを空にすると、保存済みの passphrase も削除されます。

Passphrase (private key): 各リクエストの署名に使用される秘密キーです（HMAC-SHA256）。bpost に送信されることも、ログに書き込まれることもありません。保存後、このフィールドは空になり、Saved - leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。

App ID (X-APPID): 貴社の連携用に bpost が発行したアプリケーション識別子です。X-APPID ヘッダーで送信されます。

Carrier ID: 受け取りポイントとパーセルロッカーを一覧表示する、bpost Shipping Platform 契約のキャリアです。既定値: 68（bpost）。契約で有効になっている他のキャリアには、それぞれ別の ID があります。

受け取りポイントセレクター

Pickup points: チェックアウトに受け取りポイントとパーセルロッカーのセレクターを表示します。既定でオンです。セレクターは、Account ID、Passphrase、App ID がすべて入力されている場合にのみ表示され、受け取りポイントの選択が必須になります。

Search field width: 郵便番号 / 市区町村フィールドの CSS 幅です。例: 100% または 300px。既定値: 100%。

Pickup point list width: 受け取りポイント一覧の CSS 幅です。例: 100% または 400px。既定値: 100%。

料金（ストアの既定通貨、税抜き。bpost はこの API を通じて配送料金を返しません）

Price by: 料金の選び方です。

Country (Country prices): 料金は Country prices の一覧から取得されます。これが既定です。

Parcel size by weight (Size prices, country price as fallback): 料金は、カートの重量に基づいて Size prices から取得されます。そのサイズに料金がない場合は、国の料金が使われます。

Country prices: 国ごとに 1 行、CC=料金の形式で入力します（例: BE=4.95）。*=料金の行は、その他すべての国の料金を設定します（例: *=9.95）。小数点区切りとしてピリオドとカンマの両方が使えます。無効な行は無視されます。料金のない国（* の行がない場合）には、この方法は提供されません。

Size prices: Price by がパーセルサイズの場合に使われます。S=3.50、M=4.50、L=6.00、XL=8.00 の形式で入力します。サイズはカートの重量で決まります: S は 2 kg まで、M は 5 kg まで、L は 10 kg まで、XL はそれを超える場合。

Calculation: Per order（既定）は料金を 1 回だけ請求します。Per item (price x number of items) は、料金にカート内の商品数を掛けます。

料金は、ストアの既定通貨の小数桁に丸められ、その後、購入者の通貨で表示されます。

条件

Min weight (kg): この方法が表示されるために必要なカートの最小重量です。商品の重量は kg に換算されます。0 は制限なし（既定）を意味します。

Max weight (kg): このカート重量を超えると、この方法は非表示になります。既定値: 30。bpost のパーセルロッカーは 30 kg までの荷物を受け付けるためです。0 は制限なしを意味します。

Minimum order amount: カートの小計がこの金額に達した場合にのみ、この方法を表示します。小計は、配送が必要な商品について、クーポン適用後、税抜きで計算されます。常に表示する場合は空欄にしてください。

送料無料

Free shipping: 下の金額に達すると、送料無料を有効にします。

Free shipping from: 送料無料になるカートの小計（配送が必要な商品、クーポン適用後、税抜き）です。Free shipping がオンの場合にのみ使用されます。国にはやはり料金が必要で、料金がなければこの方法は提供されません。

提供条件

通常、この方法は下で選択したジオゾーン内で提供されます。Ignore geo zone をオンにすると、代わりに一覧の国で提供されます。

Geo Zone: このジオゾーン内の住所にのみ、この方法を提供します。All Zones（既定）は、すべての地域を意味します。ジオゾーンは System > Localisation > Geo Zones で管理されます。

Ignore geo zone: ジオゾーンに関係なく、下の国でこの方法を提供します。

Countries: このモードの配送先の国です。既定値: Belgium。空欄にすると、すべての国を許可します。Ignore geo zone がオンの場合にのみ使用されます。

詳細設定

Debug log: API リクエストと料金計算を storage/logs/vfd_bpst_debug.log.php に書き込みます。このファイルは Web から読み取れません。このオプションがオフでも、API のエラーは常に記録されます。キーとトークンがログに記録されることはありません。

Log: デバッグログのサイズと最新の記録を表示します。Clear log をクリックすると空にできます。

Remove data on uninstall: オンにすると、拡張機能をアンインストールしたときに、設定、ログ、未完了のチェックアウトの受け取りポイントの選択が削除されます。注文に保存された受け取りポイントは、常に残ります。既定値: オフ。

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

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

Import: 以前エクスポートした JSON を貼り付け、Import をクリックすると設定を復元します。たとえば別のストアに復元する場合に使えます。値は通常の保存と同じように検証されます。保存済みの passphrase は保持されます。

チェックアウトでの動作

OpenCart が配送方法を表示するとき、拡張機能に bpost の料金を問い合わせます。Geo Zone が設定されていて（かつ Ignore geo zone がオフ）、住所がその外にある場合、この方法は提供されません。Requires Shipping が Yes に設定された商品だけが対象になります。それ以外の商品は重量に加算されず、注文金額にも含まれません。拡張機能は条件を確認します: Ignore geo zone の国（オンの場合）、カートの重量、最低注文金額。次に、国の一覧またはパーセルサイズから料金を取得し、商品ごとのモードでは商品数を掛け、送料無料が適用される場合は 0 にします。料金の計算のために bpost へのリクエストは送られません。

bpost の選択肢の下に、購入者には Postal code or city フィールド、Search ボタン、受け取りポイントの一覧が表示されます。購入者が bpost を選び、一覧がまだ読み込まれていない場合、配送先住所の郵便番号（または購入者の前回の検索）が自動的に検索されます。購入者は別の郵便番号または市区町村名を入力できます。各ポイントは名称と住所で表示されます。最大 50 件が一覧表示されます。一覧は、ストアの言語がオランダ語の場合はオランダ語で、それ以外の場合はフランス語で取得されます。

購入者は受け取りポイントを選ぶ必要があります。選ばないと、配送方法の段階の Continue で Please select a bpost pickup point. と表示されます。検索結果の bpost 一覧にある受け取りポイントのみが受け付けられます。そうでなければ、購入者には The selected bpost pickup point is not in the list of your search. Please choose another one. と表示されます。検索と選択はチェックアウトのために保存されるため、ページを再読み込みしても失われません。新しく検索すると、以前の選択は消去されます。

OpenCart 4 では、購入者はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options ウィンドウで bpost を選択します。受け取りポイントの検索と一覧は、そのウィンドウの bpost の選択肢の下に表示されます。受け取りポイントを選ばずにウィンドウの Continue をクリックすると Please select a bpost pickup point. が表示されます。その他の動作は OpenCart 3 と同じです。

受け取りポイントを一覧表示するため、拡張機能は検索した郵便番号または市区町村、国、キャリア ID のみを、貴社のキーで署名して bpost に送信します。API トークンは自動的に取得され、更新されます。bpost がトークンを拒否した場合は、新しいトークンを 1 回取得して検索を繰り返します。検索結果は最大 6 時間キャッシュされますが、OpenCart のキャッシュ有効期間（既定では 1 時間）を超えることはありません。bpost が応答しない場合、購入者には Pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method. と表示され、拡張機能は 5 分後に再試行します。API のタイムアウトは 15 秒です。

この拡張機能は固定料金のみを使用します。bpost からリアルタイムの料金を取得せず、発送の作成、ラベルの印刷、荷物の追跡も行いません。受け取りポイントは地図ではなく一覧で表示されます。発送は bpost Shipping Platform または Shipping Manager アカウントで作成してください。受け取りポイントの ID は管理画面の注文ページにあります。

受け取りポイント

注文が確定すると、選択された受け取りポイントが、ポイントの名称と住所とともに bpost pickup point: として注文の配送方法に追加されます。例: "bpost parcel locker - bpost pickup point: …"。そのため購入者は、注文確認、アカウントの注文履歴、注文メール、請求書でこれを確認できます。ID を含む完全な受け取りポイントの情報は、拡張機能の別のテーブルにも保存されます。OpenCart 4 では、チェックアウトは注文を 1 つだけ保持します。購入者が注文を再度確定すると（例: 別の受け取りポイントを選び直した後）、注文の受け取りポイントが更新されます。

管理画面では、Sales > Orders の注文ページに bpost pickup point パネルが表示され、受け取りポイントとその ID、または No pickup point was selected for this order. が示されます。Change をクリックし、郵便番号または市区町村を検索して、一覧から別の受け取りポイントを選び、Save をクリックしてください。注文とその配送方法のテキストはすぐに更新され、ページには Pickup point updated. と表示されます。その受け取りポイントが検索結果の bpost 一覧にない場合、ページには Pickup point not found in the bpost list of this search. と表示されます。Debug log がオンの場合、この変更はデバッグログに書き込まれます。Change は、API キーが入力されており、管理者ユーザーが注文を変更できる場合にのみ利用できます。拡張機能の設定へのアクセスは不要です。

パーセルロッカーと自宅への配送を両方提供するには、自宅への配送には別の配送方法を使用してください。受け取りポイントセレクターは、bpost の選択肢の下にのみ表示されます。

ライセンスキー

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

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

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

トラブルシューティング

bpost がチェックアウトに表示されない: ライセンスが有効であること、Enable/Disable がオンであることを確認してください。Geo Zone を確認するか、Ignore geo zone をオンにして、国が Countries に含まれているかを確認します。その国に料金があるか、*=料金の行があるかを確認し、重量の制限と Minimum order amount を確認してください。商品の Requires Shipping が Yes になっていることも確認してください。ベルギーに料金がない場合、設定ページに警告が表示されます。

チェックアウトに受け取りポイントセレクターが表示されない: Pickup points がオンであること、そして Account ID (public key)、Passphrase (private key)、App ID (X-APPID) がすべて入力されていることを確認してください。キーが不完全な場合、設定ページに警告が表示されます。

購入者に "Pickup points cannot be loaded right now" と表示される: bpost が応答しなかったか、キーを拒否しました。理由は設定ページの上部と、デバッグログ（拡張機能のページの Log フィールド）に表示されます。拡張機能は 5 分後に自動的に再試行します。設定を保存すると、すぐに再試行されます。

この郵便番号または市区町村の受け取りポイントが見つからない: bpost はこの検索に対して受け取りポイントを返しませんでした。購入者に近隣の郵便番号または市区町村名を試すよう伝え、Carrier ID を確認してください。

カンマを含む料金が使われない: 5,50 と 5.50 はどちらも受け付けられます。CC=料金の形式に従わない Country prices の行は無視されます。保存後の警告に、それらの行が一覧表示されます。

料金に税金は含まれていますか？ Tax Class が --- None --- の場合、料金は最終価格です。税クラスを設定すると、OpenCart はその税金を料金に加算します。

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

開発者向け: bpost API のアドレスは、設定 vfd_bpst_api_url（テスト用）で置き換えることができます。設定ページにはこの項目のフィールドはありません。

アンインストール

Extensions > Extensions に移動し、種類 Shipping を選択して、VibeFox bpost Cubee の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは常に削除されます。OpenCart は常に Enable/Disable、Sort Order、Tax Class、Geo Zone をリセットします。保存済みの API トークンと、キャッシュされた受け取りポイントの一覧は常に削除されます。Remove data on uninstall がオンの場合は、設定、ログ、未完了のチェックアウトの受け取りポイントも削除されます。オフの場合、ほかの設定は保持され、拡張機能を再インストールしたときに再び使用されます。注文に保存された受け取りポイントは注文履歴の一部であり、削除されることはありません。既存の注文は配送方法と料金を保持します。

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

bpost は、それぞれの所有者の商標です。この拡張機能は bpost とは提携しておらず、bpost による承認も受けていません。