VibeFox Balikobot for OpenCart — ヘルプ

要件

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

PHP: 8.0 以降。

Balikobot アカウント（リアルタイム料金と受け取りポイント用）: API アクセスが有効な Balikobot アカウントが必要です。API ユーザーと API キーは Balikobot のクライアントゾーン（client.balikobot.cz）にあります。Balikobot サポート（podpora@balikobot.cz）が、お客様のアカウントと配送業者の API を有効にします。リアルタイム料金には、Balikobot が「transportcosts」に対応している配送業者とサービスが必要です。受け取りポイントには、「branchlocator」に対応している配送業者が必要です（例: Česká pošta、Zásilkovna、PPL、DPD、GLS）。不明な場合は Balikobot サポートにお問い合わせください。固定料金はアカウントなしで利用できます。

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

インストール

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

OpenCart 3

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

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

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

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

5. API ユーザーと API キーを入力し、配送業者とサービスタイプ、料金の取得元、国ごとの料金を選択します（「設定」を参照）。受け取りサービスの場合は Pickup point selection を有効にします。Enable/Disable を有効にして Save をクリックします。

OpenCart 4

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

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

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

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

インストール時に、拡張機能はチェックアウトと注文の受け取りポイント用のテーブルを作成します。Enable/Disable を有効にして保存するまで、この方法はオフのままです。アンインストール後に再インストールすると、保存されていた Balikobot の設定が再び使用されます。

設定

すべての設定は拡張機能のページにあります: Extensions > Extensions > Shipping > VibeFox Balikobot > Edit。セクションは左側に表示されます。Save ボタンを 1 回押すと、ページを再読み込みせずにページ全体が保存されます。保存後には Settings saved. Cached rates and pickup points were cleared. と表示されます。この拡張機能の変更権限を持つ管理者ユーザーだけが設定を保存できます。

一部のエラーでは保存が中断され、何も保存されません。空または長すぎる Name、整数ではない Sort Order、または存在しない税クラスやジオゾーンがこれに当たります。その他の問題は警告として表示され、残りの設定は保存されます。数値ではない値（または負の値）は保存されず、警告にフィールド名が示されます。無効な Country prices の行は削除され、一覧表示されます。

方法、リアルタイム料金、または受け取りポイントを非表示にしてしまう設定については、ページ上部に警告が表示されます。API ユーザーまたは API キーがないリアルタイム料金や受け取りポイント、Exchange rate が未設定の CZK 以外のストア通貨、固定料金またはフォールバックモードでの空の Country prices、そして単位が kg の重量クラスがないストアが対象です（その場合、商品の重量は単位名（kg、g、lb、oz）で読み取られます）。

一般

Enable/Disable: チェックアウトでの Balikobot 配送を有効または無効にします。デフォルト: 無効。

Name: 購入者に表示される配送方法の名前。デフォルト: Balikobot。必須、64 文字以内。

Sort Order: 配送方法の一覧での表示順。整数。

Balikobot API アカウント（リアルタイム料金と受け取りポイントに必要）

API user: クライアントゾーンにある Balikobot の API ユーザー。

API key: クライアントゾーンにある Balikobot の API キー。保存後、このフィールドは空のままになり、Saved - leave empty to keep it. Clear the API user to remove the saved key. と表示されます。変更する場合にのみ新しい値を入力してください。

Carrier: 料金と受け取りポイントに使用する Balikobot の配送業者: Česká pošta（デフォルト）、Zásilkovna（Packeta）、PPL、DPD、GLS、DHL Express、UPS、TNT、FedEx、Geis、InTime、Uloženka、Toptrans、Pošta bez hranic、Slovenská pošta、SPS（Slovak Parcel Service）、Magyar Posta。Balikobot アカウントで有効化されている必要があります。

Service type: 配送業者の Balikobot サービスコード。デフォルト: NP。Česká pošta の場合: NP = 郵便局受け取りの荷物、NB = Balíkovna 宛の荷物、DR = 宅配。その他の配送業者のコードは、Balikobot のクライアントゾーンと API ドキュメントに記載されています。

料金（すべての料金はストアのデフォルト通貨です）

Price source: 料金の計算方法。

Country prices: 国と料金の一覧です。Add row をクリックして行を追加し、削除ボタンで行を削除します。独自の行がないすべての国には * All other countries を選択します。小数点はドットまたはカンマで入力できます。固定モードと API のフォールバックで使用されます。料金のない国（* 行もない国）には固定料金が設定されないため、その国では方法が非表示になります。

Fixed price per: Order（デフォルト）は料金を 1 回だけ請求します。Item (price x quantity) はカート内の商品数を掛けます。これは固定料金にのみ適用されます。Balikobot のリアルタイム料金は常に荷物全体に対するものです。

Exchange rate: Balikobot の料金通貨（通常は CZK）の 1 単位を、ストアのデフォルト通貨に換算した値。例: 0.04。Balikobot が別の通貨で料金を返す場合にのみ使用されます。空欄のままにすると、そのような料金は拒否され、購入者に誤った金額が請求されることはありません。

条件

Min weight (kg): カートがこの重量より軽い場合、方法を非表示にします。0 は制限なし（デフォルト）を意味します。商品の重量は OpenCart の重量クラスから変換されます。

Max weight (kg): カートがこの重量より重い場合、方法を非表示にします。デフォルト: 100。0 は制限なしを意味します。空欄は 100 kg を意味します。Min weight (kg) が最大値より大きい場合は警告が表示され、以前の重量が保持されます。

Minimum order amount: カートの小計（クーポン適用後、税抜き）がこの金額以上の場合にのみ、方法を表示します。常に表示する場合は空欄のままにします。

Free shipping: 下記の金額以上で送料無料にします。

Free shipping from: 送料が無料になるカートの小計（クーポン適用後、税抜き）。その場合、Balikobot へのリクエストは送信されません。Free shipping が有効な場合にのみ使用されます。

Tax Class: このクラスの税金が配送料に加算されます。Balikobot の料金は通常、消費税（VAT）を含みません。デフォルト: --- None ---。

提供条件

通常、この方法はここで選択したジオゾーン内で提供されます（All Zones は全地域を意味します）。Ignore geo zone を有効にすると、代わりにリストにある国で提供されます。

Geo Zone: このジオゾーン内の住所に対してのみ方法を提供します。ジオゾーンは System > Localisation > Geo Zones で管理します。

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

Countries: このモードの配送先の国。空欄の場合はすべての国を許可します。Ignore geo zone 使用時にのみ使われます。

受け取りポイント

Pickup point selection: 購入者は受け取りポイントを選択する必要があります。Česká pošta NP または NB、Zásilkovna などの受け取りサービスに使用します。API ユーザーと API キーが必要です。

Selector width: 受け取りポイントの一覧の CSS 幅（例: 100% または 400px）。デフォルト: 100%。

詳細設定

Debug log: API リクエストと料金計算を storage/logs/vfd_blkb_debug.log.php に記録します。このファイルは Web から読み取ることはできません。API エラーは常に記録されます。認証情報と購入者の住所は一切記録されません。作業が終わったらログをオフにしてください。ファイルが 5 MB に達すると、vfd_blkb_debug.old.log.php に移動され、新しいログが開始されます。

Log: ログのサイズと最新のエントリを表示します。Clear log をクリックするとログが消去されます。

Remove data on uninstall: オンにすると、拡張機能のアンインストール時に、設定、ログ、注文のないチェックアウトの受け取りポイントが削除されます。オフの場合（デフォルト）は設定が保持されます。注文に保存された受け取りポイントは常に保持されます。

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

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

Import: 以前にエクスポートした JSON を貼り付けて Import をクリックすると、設定が復元されます（別のストアでの利用など）。値は通常の保存と同様に検証されます。保存済みの API キーは保持されます。

チェックアウトでの動作

OpenCart が配送方法を表示するとき、拡張機能に Balikobot の料金を問い合わせます。Geo Zone が設定されていて（かつ Ignore geo zone がオフの）、住所がその外にある場合、Balikobot は提供されません。Ignore geo zone が有効な場合は、Countries のリストが適用されます。Requires Shipping が Yes に設定された商品のみが対象です。それ以外の商品は重量に加算されず、注文金額にも含まれません。その後、拡張機能はカートの重量と Minimum order amount を確認します。注文金額は、クーポン割引後、税抜きで、配送が必要な商品の価格です。送料無料が適用される場合、料金は 0 となり、Balikobot へのリクエストは送信されません。

固定モードでは、料金は Country prices から取得されます。リアルタイムモードでは、拡張機能は配送業者、サービスタイプ、配送先の国と郵便番号、およびカートの重量（kg）を Balikobot に送信します。配送先住所に郵便番号がある場合にのみ、リアルタイム料金が要求されます。他の通貨の料金は Exchange rate で換算されます。レートが設定されていない場合は拒否されます。料金はストアのデフォルト通貨で計算され、その小数桁に丸められ、選択した Tax Class の税金を含めて購入者の通貨で表示されます。

リアルタイム料金は 1 時間キャッシュされるため、同じカートで新たなリクエストが発生することはありません。失敗したリクエストは 5 分間キャッシュされ、API のタイムアウトは 12 秒です。これにより、更新のたびにチェックアウトが Balikobot の応答を待つことがなくなります。API のエラーが購入者に表示されることはありません。方法が非表示になるか、フォールバックモードでは固定料金が使用されます。詳細はデバッグログに記録されます。

拡張機能は Balikobot で配送を作成したり、ラベルを印刷したり、集荷を依頼したりはしません。配送は Balikobot のクライアントゾーンで注文してください。荷物を追跡することも、注文ステータスを変更することもありません。すべての配送先に 1 つの配送業者と 1 つのサービスタイプが使用されます。受け取りポイントはドロップダウンリストで表示され、地図は表示されません。

OpenCart 4 では、購入者はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options ウィンドウで Balikobot を選択します。この方法は OpenCart 3 と同じように動作します。受け取りポイントの一覧については「受け取りポイント」で説明しています。

受け取りポイント

Pickup point selection を有効にすると、OpenCart チェックアウトの Delivery Method ステップで、Balikobot の方法の下に受け取りポイントの一覧が表示されます。一覧は、配送先住所の国、市区町村、郵便番号をもとに Balikobot の「branchlocator」から読み込まれます。住所に市区町村が入力されるまで、購入者には Enter your city to see the pickup points. と表示されます。一覧の読み込み中は Loading pickup points... と表示されます。一覧は最長 12 時間キャッシュされます。

購入者が受け取りポイントを選択すると、すぐに保存されます。選択は必須です。配送ステップの Continue は、Please select a pickup point. と表示されて拒否されます。サーバーは、選択されたポイントが配送先住所に属しているかも確認します。そうでない場合、購入者には The selected pickup point is not available for your shipping address. Please choose a pickup point again. と表示されます。その時点で Balikobot に接続できない場合は、すでに選択されているポイントが受け入れられます。ポイントが見つからない場合は、購入者に市区町村と郵便番号の確認、または別の配送方法の選択が求められます。ポイントを読み込めない場合は、後で再試行するか、別の配送方法を選択するよう求められます。

OpenCart 4 では、購入者はチェックアウトページの配送方法ブロックで Choose をクリックします。Shipping method options ウィンドウには、Balikobot の方法の下に受け取りポイントの一覧が表示されます。テキストとチェックは同じです。同じチェックアウトページで住所が変わる可能性があるため、ウィンドウを開くたびに一覧を読み込み、可能な場合はキャッシュから取得します。購入者が有効なポイントを選ばずにウィンドウで Continue をクリックすると、チェックアウトページの上部にメッセージが表示され、ウィンドウは開いたままになります。OpenCart 4 はチェックアウト用の注文を 1 件保持し、確認のたびに更新します。注文の受け取りポイントもそれに合わせて更新されます。

選択されたポイントは、注文の配送方法に - Pickup point: として、その名前と住所とともに追加されます。購入者はアカウントの注文ページや注文メールでこれを確認でき、請求書にも印刷されます。

管理画面の注文ページ（Sales > Orders、View）では、Balikobot pickup point パネルにポイント、その Balikobot ID、配送業者が表示されます。これらは Balikobot で配送を作成する際に必要です。Change をクリックして、注文住所の近くにある別のポイントを選び、Save をクリックします。注文の配送方法のテキストも更新され、Pickup point updated. と表示されます。ポイントの変更には注文の変更権限のみが必要で、拡張機能の設定へのアクセス権は不要です。注文にポイントがない場合、パネルには No pickup point was selected for this order. と表示されます。Balikobot が無効になっていても、パネルは機能します。既存の注文は受け取りポイントのデータを保持し、ポイントも変更できます。

ライセンスキー

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

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

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

トラブルシューティング

チェックアウトに Balikobot が表示されない: ライセンスが有効で、Enable/Disable がオンになっているか確認してください。拡張機能ページの上部にある警告を確認してください。Geo Zone（または Ignore geo zone と Countries）、重量制限、Minimum order amount を確認してください。固定モードでは、その国または * All other countries に料金が設定されているか確認してください。商品の Requires Shipping が Yes に設定されているか確認してください。

リアルタイム料金が表示されない: Debug log をオンにし、チェックアウトを再読み込みして、拡張機能ページの Log フィールドを確認してください。理由が表示されます。API 認証情報の不足、郵便番号未入力、配送業者とサービスに対する Balikobot のエラー（例: "authorization failed: check the API user and API key"）、Exchange rate が未設定の他通貨の料金などです。Live Balikobot rate, fixed price if the API fails を選択している場合、問題を修正している間も購入者には固定料金が提供されます。

料金の通貨が違う: 固定料金はストアのデフォルト通貨です。Balikobot はお客様の Balikobot 契約の通貨（通常は CZK）でリアルタイム料金を返します。デフォルト通貨と異なる場合は、Exchange rate を設定してください。

税込みですか: Balikobot の料金は通常、VAT を含みません。Tax Class が選択されている場合、OpenCart は配送料に税金を加算します。

一覧に受け取りポイントがない: API ユーザーと API キーが設定されているか、配送業者が「branchlocator」に対応しているか、配送先住所に市区町村と郵便番号があるかを確認してください。ログで Balikobot のエラーを確認してください。

変更後に料金や受け取りポイントが古く見える: 拡張機能ページで Save をクリックしてください。キャッシュされた料金と受け取りポイントが消去されます。

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

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

アンインストール

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

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

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