VibeFox Balikobot for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: 8.0 以降。モジュールは、それより古い PHP バージョンではインストールできません。

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 つのドメインに対応します。

インストール

1. 管理画面で Modules > Module Manager を開き、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。

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

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

4. API ユーザーと API キーを入力し、配送業者とサービスタイプ、料金のソース、国ごとの料金を選択します（設定を参照）。取り扱いのある配送サービスでは、Pickup point selection を有効にします。Save をクリックします。

インストール時に、モジュールは Balikobot 配送業者を作成します。配送日数のテキストは Delivery by Balikobot です。この配送業者は、チェコ、スロバキア、ハンガリーのゾーンと、すべての顧客グループに割り当てられます。ゾーン、顧客グループ、配送日数のテキスト、ロゴ、サイズ制限は Shipping > Carriers で変更できます。料金はそこで設定しないでください。料金は常にモジュールから取得されます。

設定

すべての設定はモジュールページにあります: Modules > Module Manager > VibeFox Balikobot > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。保存後には Settings saved. Cached rates and pickup points were cleared. と表示されます。ページ上部には、配送業者、リアルタイム料金、ピックアップポイントを非表示にしてしまう設定についての警告が表示されます。API ユーザーまたは API キーがないのにリアルタイム料金やピックアップポイントを使用している場合、Exchange rate がないのにストアの通貨が CZK 以外になっている場合、固定料金またはフォールバックを使用しているのに Country prices が空の場合、モジュールが認識できないストアの重量単位がある場合（その場合、重量は kg として読み取られます。kg、g、lb、oz のいずれかを使用してください）、削除された配送業者がある場合です。数値ではない値は保存されず、フィールド名を示す警告が表示されます。

General

Enable/Disable: Balikobot の配送を有効または無効にします。これは Shipping > Carriers における配送業者のステータスと同じスイッチです。

Name: 顧客に表示される配送方法の名前（配送業者の名前）。既定値: Balikobot。必須、最大 64 文字。

Tax status: None、または税ルールのいずれかを選んだ Taxable。税ルールを選ぶと、その税額が配送料金に加算されます。この選択は配送業者に保存されます。Balikobot の料金は通常、税抜きです。既定値: None。

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: 2 文字の国コード（例: CZ、SK）と料金の表です。Add row をクリックすると国を追加でき、ゴミ箱のアイコンをクリックすると削除できます。その他すべての国には * を国コードとして使用します。小数点はドットまたはカンマで入力できます。固定モードと API のフォールバックで使用されます。料金が設定されていない国（* の行もない場合）には、固定料金は適用されません。無効な行は保存時に削除され、警告に一覧が表示されます。

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

Exchange rate: Balikobot の料金通貨（通常は CZK）の 1 単位に相当する、ストアの既定通貨での値（例: 0.04）。Balikobot が別の通貨で料金を返した場合にのみ使用されます。空欄のままにすると、そのような料金は拒否されるため、顧客が誤った金額を支払うことはありません。

条件

Min weight (kg): カートがこの重量より軽い場合、配送業者を非表示にします。0 は制限なしを意味します。商品の重量は、ストアの重量単位から換算されます。

Max weight (kg): カートがこの重量より重い場合、配送業者を非表示にします。既定値: 100。0 は制限なしを意味します。空欄は 100 kg を意味します。Min weight (kg) が最大値を超える場合は警告が表示され、以前の重量が保持されます。

Minimum order amount: カートの小計（割引後、税抜き）がこの金額以上の場合にのみ配送業者を表示します。空欄のままにすると、常に表示されます。

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

Free shipping from: 送料が無料になるカートの小計（割引後、税抜き）。この場合、API へのリクエストは行われません。

配送ゾーンなしでの利用

通常、配送業者は Shipping > Carriers で設定されたゾーンでのみ提供されます。

Ignore shipping zones: 配送業者がゾーンに紐付けられていなくても、下記の国で配送業者を提供します。モジュールは、後で作成するゾーンも含め、すべてのゾーンに配送業者を紐付けます。このオプションをオフにすると、この方法で追加されたゾーンは削除されます。お客様が作成したゾーンは残ります。

Countries: このモードの配送先の国。空欄のままにすると、お客様が配送しているすべての国が対象になります。Ignore shipping zones と組み合わせた場合にのみ使用されます。

ピックアップポイント

Pickup point selection: 顧客はピックアップポイントを選択する必要があります。Česká pošta NP や NB、Zásilkovna などのピックアップ型サービスに使用します。API ユーザーと API キーが必要です。

Selector width: ピックアップポイントの一覧の CSS 幅（例: 100% または 400px）。既定値: 100%。

詳細設定

Debug log: API リクエストと料金計算を、モジュールフォルダー内の logs/vfd_blkb_debug.log.php に記録します。このファイルは Web から開くことはできません。API のエラーは常に記録されます。認証情報と顧客の住所は記録されません。作業が終わったらログをオフにしてください。

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

Remove data on uninstall: オンにすると、モジュールをアンインストールしたときに、モジュールの設定と配送業者が削除されます。このオプションがオフの場合、アンインストールでデータが削除されることはありません。注文に保存されたピックアップポイントは保持されます。

チェックアウトでの動作

配送ステップで、PrestaShop はモジュールに Balikobot の料金を問い合わせます。計算の対象となるのは実物の商品のみです。バーチャル商品は重量に加算されず、注文金額にも含まれません。モジュールは最初に国（Ignore shipping zones を使用）、カートの重量、Minimum order amount を確認します。送料無料の条件に該当する場合、料金は 0 になり、Balikobot へのリクエストは送信されません。

固定モードでは、料金は Country prices から取得されます。リアルタイムモードでは、モジュールは配送業者、サービスタイプ、配送先の国と郵便番号、そしてカートの重量（kg）を Balikobot に送信します。リアルタイム料金は、配送先住所に郵便番号がある場合にのみ問い合わせられます。別の通貨の料金は Exchange rate で換算されます。為替レートが設定されていない場合は拒否されます。料金はストアの既定通貨で計算され、その後、顧客のカートの通貨で表示されます。

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

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

モジュールは Balikobot で発送を作成したり、ラベルを印刷したり、集荷を依頼したりはしません。発送は Balikobot のクライアントゾーンで手配してください。荷物の追跡や注文ステータスの更新も行いません。すべてのゾーンで、1 つの配送業者と 1 つのサービスタイプが使用されます。ピックアップポイントはドロップダウンリストとして表示され、地図はありません。

ピックアップポイント

Pickup point selection をオンにすると、配送ステップで Balikobot 配送業者の下にピックアップポイントの一覧が表示されます。一覧は、配送先住所の国、市区町村、郵便番号に基づいて、Balikobot の "branchlocator" から読み込まれます。住所に市区町村が入力されるまで、顧客には Enter your city to see the pickup points. と表示されます。一覧は 12 時間キャッシュされます。

顧客がポイントを選択すると、その選択はすぐにカートに保存されます。ピックアップポイントの選択は必須で、配送ステップの Continue と Place order は Please select a pickup point. と表示されてブロックされます。サーバーは、選択されたポイントが配送先住所に属しているかどうかも確認します。属していない場合、顧客には The selected pickup point is not available for your shipping address. Please choose a pickup point again. と表示されます。ポイントが見つからない場合は、市区町村と郵便番号を確認するか、別の配送方法を選ぶよう顧客に案内されます。ポイントを読み込めない場合は、後で再度お試しいただくか、別の配送方法を選ぶよう案内されます。

選択されたピックアップポイントは注文に保存されます。管理画面の注文ページでは、Balikobot pickup point ブロックに、Balikobot の支店 ID と配送業者とともに表示されます。これらは Balikobot で発送を作成する際に必要です。Change をクリックすると、注文住所の近くにある別のポイントを選択でき、その後 Save をクリックします。ポイントの変更には注文を編集する権限だけが必要で、モジュールページへのアクセス権は必要ありません。注文にピックアップポイントがない場合、ブロックには No pickup point was selected for this order. と表示されます。

顧客には、注文確認ページと注文の詳細に Pickup point: としてポイントが表示されます。注文確認メールと、ストア向けの新規注文メール（Mail alerts モジュール）では、配送業者名の後に追加されます。既存の注文は、ピックアップポイントのデータを保持します。

ライセンスキー

このモジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Balikobot は、Modules > Module Manager > VibeFox Balikobot > Configure の最上部、設定より上にあります。キーを License key に貼り付けて Activate をクリックします。その後、ブロックにはキーが伏せ字で表示され、ステータス（ライセンスの有効期限日やお使いのドメインなど）と、ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key のボタンが表示されます。その下には Product: presta-shipping-balikobot の行と、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 のアカウントで枠を解放してください。

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

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

トラブルシューティング

チェックアウトに Balikobot が表示されない: ライセンスが有効であること、Enable/Disable がオンであることを確認してください。モジュールページ上部の警告を確認してください。Shipping > Carriers で、配送業者が顧客の国のゾーンと顧客グループを対象としているかを確認するか、Ignore shipping zones をオンにして Countries を確認してください。重量制限と Minimum order amount も確認してください。固定モードでは、国または * に料金が設定されていることを確認してください。商品ページで、商品が特定の配送業者に限定されている場合もあります。

リアルタイム料金が表示されない: Debug log をオンにし、チェックアウトを再読み込みして、モジュールページの Log フィールドを確認してください。そこに原因が表示されます。API 認証情報の不足、郵便番号がまだ入力されていない、配送業者とサービスに対する Balikobot のエラー（例: authorization failed。API ユーザーと API キーを確認してください）、または Exchange rate が未設定で別の通貨の料金が返された場合などです。問題を修正している間も、Live Balikobot rate, fixed price if the API fails を使用すれば、顧客は固定料金を受け取れます。

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

税込みか: Balikobot の料金は通常、税抜きです。Tax status に税ルールを設定すると、PrestaShop が配送料の税を加算します。

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

変更後に料金やピックアップポイントが古いようだ: モジュールページの Save をクリックしてください。これにより、キャッシュされた料金とピックアップポイントが消去されます。

Balikobot 配送業者が見つからないと表示される: 配送業者は Shipping > Carriers で削除されています。Modules > Module Manager でモジュールをリセットすると、再作成されます。

開発者向け: このモジュールには、API アドレス（actionVfdBlkbApiUrl）、"transportcosts" パッケージ（actionVfdBlkbTransportcostsPackage）、ピックアップポイントの件数（actionVfdBlkbPickupMaxResults、既定値 30）を変更するための独自のフックがあります。

アンインストール

Modules > Module Manager に移動し、VibeFox Balikobot の横にあるメニューを開いて Uninstall を選択します。ライセンスキー、ライセンスステータス、キャッシュされた料金とピックアップポイントは常に削除されます。Remove data on uninstall がオンの場合は、配送業者が削除されます（注文は履歴を保持します）。また、設定、ログ、注文のないカートのピックアップポイントも削除されます。オフの場合は、配送業者が無効になるだけで、すべての設定は保持されます。モジュールを再インストール（またはリセット）すると、保存された配送業者は、アンインストール前のステータスに戻ります。オンのものはオンのまま、オフのものはオフのままです。注文に保存されたピックアップポイントのデータは、削除されることはありません。

Balikobot は、それぞれの所有者の商標です。本モジュールは Balikobot と提携しておらず、Balikobot による承認も受けていません。