VibeFox Blue Express for PrestaShop — ヘルプ
要件
PrestaShop：8.0 から 9.x。
PHP：8.0 以降。古いバージョンの PHP ではモジュールはインストールされません。
Blue Express アカウント（リアルタイム料金のみ）：リアルタイム料金には、Blue Express の電子商取引アカウントと API キー（x-api-key）が必要です。Blue Express に申し込んでください：developers.bluex.cl または gpo.integraciones@bx.cl。ご利用のサービス（EX、PY、MD）が Blue Express との契約で有効になっている必要があります。固定料金のみを利用する場合、API キーは不要です。
チリの地域：リアルタイム料金では、配送先住所にチリの地域が必要です。ストアにチリの地域がない場合、モジュールが追加できます（設定を参照）。
受取ポイント：Blue Express のマップは、お客様のブラウザで widget-pudo.blue.cl から読み込まれます。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
1. 管理画面で Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックするか、後でモジュール一覧から VibeFox Blue Express を探して Configure をクリックします。
3. Configure ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを貼り付け、Activate をクリックします（ライセンスキーを参照）。
4. API キー、サービス、発送元の地区コード（例：SCL）、ストアの通貨が CLP でない場合は CLP の為替レート、固定料金（例：CL=4500）を入力します。Blue Express のポイントでの受け取りを提供する場合は Pickup point carrier をオンにします。Save をクリックします。設定を参照してください。
インストール時、モジュールは 2 つの配送業者を作成します：Blue Express（自宅配送、配送時間のテキスト Home delivery、オン）と Blue Express pickup point（配送時間のテキスト Pickup at a Blue Express point、オンにするまでオフ）。どちらもチリのゾーンと全ての顧客グループに割り当てられます。ゾーン、顧客グループ、配送時間、ロゴ、サイズ制限は Shipping > Carriers で変更できます。そこでは料金を設定しないでください。料金は常にモジュールから取得されます。
設定
すべての設定はモジュールページにあります：Modules > Module Manager > VibeFox Blue Express > Configure。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。保存するたびに、キャッシュされた Blue Express の料金とコミューンのデータも消去されます。配送業者またはリアルタイム料金を非表示にしてしまう設定について、ページ上部に警告が表示されます：API キーがない、CLP 以外のストア通貨で為替レートがない、固定料金の表が空、チリの地域がない、モジュールが認識しないストアの重量または寸法の単位（その場合、重量は kg、寸法は cm として読み取られます）、または削除された配送業者。無効な値はエラーとともに拒否され、何も保存されません：配送業者名が空または無効、64 文字を超える名前、負の数または無効な数値、または Min weight (kg) が Max weight (kg) より大きい場合。以下の条件と料金は、両方の配送業者に適用されます。
一般
Enable/Disable: 自宅配送の配送業者をオンまたはオフにします。これは Shipping > Carriers の配送業者のステータスと同じスイッチです。
Name: 自宅配送のチェックアウトで表示される配送業者名。デフォルト：Blue Express。必須、最大 64 文字。
Tax status: None (no tax on shipping)、または税ルールの 1 つを選んだ Taxable。Blue Express の料金には IVA が含まれます。PrestaShop で送料に税を追加させたくない場合は None を選択します。両方の配送業者に適用されます。
Blue Express のポイントでの受け取り（PUDO）
Pickup point carrier: 自宅配送に加えて 2 つ目の配送業者として、お客様が選んだ Blue Express のポイントへの配送を提供します。デフォルトはオフです。これは Shipping > Carriers の Blue Express pickup point 配送業者のステータスと同じスイッチです。
Pickup point name: Blue Express のポイントでの受け取りに対してチェックアウトで表示される配送業者名。デフォルト：Blue Express pickup point。必須、最大 64 文字。
Blue Express API（リアルタイム料金に必要）
API key: Blue Express の API キー（ヘッダー x-api-key）。キーがない場合は固定料金のみが使用されます。保存後、このフィールドは空のままになり、A key is saved - leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。Remove the saved API key にチェックを入れて保存すると削除されます。
Service: 料金の計算に使用する Blue Express のサービス：Express (EX)（デフォルト）、Prioritario (PY)、または SameDay (MD)。Blue Express との契約で有効になっている必要があります。
Origin district code: 発送元の Blue Express の地区コード。例：サンティアゴの SCL（デフォルト）。不明な場合は Blue Express にお問い合わせください。
CLP per 1 unit of store currency: ストアのデフォルト通貨が CLP でない場合、ラベルに表示されます（例：CLP per 1 EUR）。Blue Express の料金はチリペソ（CLP）建てです。ストアのデフォルト通貨 1 単位が何 CLP に相当するかを入力してください（例：1050）。これがない場合、リアルタイム料金は使用されません。ストアの通貨が CLP の場合は無視されます。
料金
Rate source: 料金の計算方法。リアルタイム料金には、地域とコミューン（市）を含むチリの住所が必要です。エラーはログに記録され、お客様には表示されません。
Fixed prices: 国ごとに 1 行、COUNTRY_CODE=PRICE の形式で、ストアのデフォルト通貨、税抜きで入力します。例：CLP のストアなら CL=4500、EUR のストアなら CL=4.50。小数点の区切りとしてカンマまたはピリオドを使用できます。無効な行は無視され、保存時に警告として表示されます。行がない国には固定料金がないため、固定料金が必要な場合はその国の配送業者は非表示になります。固定料金はどの国にも使用できます。
Fixed price per: Order は料金を 1 回だけ請求します。Item (price x quantity) はカート内の商品数を掛けます。これは固定料金にのみ適用されます。API の料金は常に発送全体に対するものです。
条件
Min weight (kg): カートの重量がこれより軽い場合、配送業者を非表示にします。0 は制限なしを意味します。
Max weight (kg): カートの重量がこれより重い場合、配送業者を非表示にします。デフォルト：100。0 は制限なし、空欄は 100 kg を意味します。Min weight (kg) は Max weight (kg) より大きくできません。
Minimum order subtotal: このカート小計以上の場合にのみ配送業者を表示します（ストアの通貨、割引後、税抜き）。常に表示する場合は空欄のままにします。
送料無料
Free shipping: カート小計に基づく送料無料をオンにします。
Free from subtotal: 送料が無料になるカート小計（ストアの通貨、割引後、税抜き）。Free shipping がオンの場合にのみ使用されます。
配送ゾーンなしの利用
Ignore shipping zones: 両方の配送業者を全ゾーンで提供します。国は下のリストで制限されます。後から作成されたゾーンも追加されます。再びオフにすると、配送業者は以前のゾーンに戻ります。
Countries: このモードでの配送先の国。空欄の場合は、配送可能な全ての国を使用します。Ignore shipping zones を使用する場合にのみ使われます。
詳細設定
Debug log: リクエストと判断を、モジュールフォルダ内の logs/vfd_blex_debug.log.php に記録します。このファイルはウェブから開くことはできません。API エラーは常に記録されます。API キーとお客様の住所は決して記録されません。作業が終わったらログをオフにしてください。
Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると空になります。
Remove data on uninstall: オンの場合、モジュールをアンインストールすると設定と配送業者が削除されます。注文に保存された受取ポイントは保持されます。
チリの地域（ストアに使用可能なチリの地域がない場合にのみ表示）
Blue Express のリアルタイム料金では、チリの住所の地域（RM、VS など）が必要です。PrestaShop にはチリの地域がデフォルトで含まれていません。Add Chilean regions をクリックすると、Blue Express が使用するコードを持つ 16 のチリの地域がチリの州（states）として追加され、チリの住所フォームに地域フィールドが表示されます。コードまたは名前で既に存在する地域は、二重に追加されません。ボタンをクリックするまで、何も変更されません。International > Locations > States で、RM、VS などのコードを使って自分で追加することもできます。
チェックアウト時の動作
配送ステップで、PrestaShop は各 Blue Express 配送業者の料金をモジュールに問い合わせます。対象は実物の商品のみです。バーチャル商品は重量に加算されず、小計にも含まれません。モジュールは Countries（Ignore shipping zones と併用）、カートの重量、Minimum order subtotal を確認します。送料無料が適用される場合、料金は 0 となり、Blue Express へのリクエストは送信されません。
リアルタイム料金の場合、住所はチリ国内にあり、地域と市（コミューン）が必要です。モジュールはまず Blue Express にコミューンの認識を依頼し、その後、サービス、発送元の地区、配送先、荷物の料金を問い合わせます。各商品は、重量と寸法を kg と cm に変換して送信されます。重量または寸法のない商品は、0.01 kg、10 x 10 x 10 cm として送信されます。申告価格は CLP で送信されます。CLP の料金はストアのデフォルト通貨に換算され、その後お客様のカートの通貨で表示されます。
料金は 1 時間、コミューンのデータは 12 時間キャッシュされます。API 呼び出しが失敗した場合は 5 分間記憶され、タイムアウトは 10 秒です。そのため、API が遅い場合や利用できない場合でも、チェックアウトの更新のたびに遅くなることはありません。API エラーはお客様には表示されません。配送業者は非表示になるか、フォールバックモードでは固定料金が使用されます。理由はログに記録されます。
注文がある配送業者を Shipping > Carriers で編集した場合、PrestaShop はそれを配送業者の新しいバージョンとして保存します。モジュールは新しいバージョンに自動的に従います。
モジュールは Blue Express での出荷や送り状の作成、追跡番号の割り当て、追跡情報の表示は行いません。出荷は Blue Express のアカウントで作成してください。コミューンごとの地域別料金表はありません。Blue Express API の料金か、国ごとの固定料金のいずれかを使用してください。リアルタイム料金はチリでのみ利用できます。
受取ポイント
お客様が配送ステップで Blue Express pickup point を選択すると、その下に Choose pickup point ボタンのあるボックスが表示されます。このボタンは公式の Blue Express マップを開き、お客様はそこでポイントを選択します。選択したポイントは名前と住所とともに表示され、ボタンは Change pickup point に変わります。ポイントはカートに保存され、料金は Blue Express の受取（PUDO）料金で再計算されます。料金が変わる場合、ページは再読み込みされて新しい料金が表示されます。ポイントが選択されるまで、配送業者は自宅配送の荷物料金を表示します。
お客様はポイントを選択しないと先に進めません：Please choose a Blue Express pickup point. これは、お客様が配送ステップで Continue をクリックしたときにストアによって確認されます。形式の正しくないポイントコードは The selected Blue Express pickup point is not valid. Please choose it again on the map. と表示されて拒否され、以前の選択はそのまま残ります。
注文が確定すると、ポイントは Blue Express の代理店コード、名前、住所とともに注文に保存されます。管理画面の注文ページでは、Blue Express pickup point ブロックに表示されます。Edit をクリックすると、Choose on the Blue Express map で別のポイントを選択したり、Agency code、Name、Address を手入力したりできます。その後、Save pickup point をクリックします。変更は非公開の注文メッセージとして記録されます。ポイントの変更には注文の編集権限のみが必要で、Modules ページへのアクセスは不要です。お客様は、注文確認ページ、注文詳細ページ、注文確認メールで、配送業者名の横にポイントを確認できます。Mail alerts モジュールによるストア向けの新規注文メールにも代理店コードが表示されます。既存の注文は、受取ポイントのデータをそのまま保持します。
ライセンスキー
このモジュールは、vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Blue Express は、Modules > Module Manager > VibeFox Blue Express > Configure の最上部、設定より上にあります。キーを License key に貼り付けて Activate をクリックします。その後、ブロックにはキーが伏せ字で表示され、ステータス（ライセンスの有効期限日やお使いのドメインなど）と、ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key のボタンが表示されます。その下には Product: presta-shipping-blue-express の行と、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 のアカウントで枠を解放してください。
有効なキーがない場合、Blue Express の配送業者はチェックアウトでお客様に表示されず、料金も計算されません。PrestaShop のストアフロントは、バックオフィスにログインしていることを認識しないため、配送業者はお客様にも表示されません。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。
ライセンスの期限が切れても、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。バックオフィスで作業している間、ステータスは自動的に再確認されます。キー入力後最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
チェックアウトに Blue Express が表示されない：ライセンスが有効であることと、Enable/Disable（または Pickup point carrier）がオンであることを確認してください。Shipping > Carriers で、配送業者がお客様の国のゾーンとお客様のグループを対象にしているかを確認するか、Ignore shipping zones をオンにして Countries を確認してください。モジュールページ上部の警告を読んでください。重量の制限、Minimum order subtotal、固定料金またはフォールバックを使用する場合は Fixed prices にその国の行があるかを確認してください。商品ページで、特定の配送業者に制限されている場合もあります。
リアルタイム料金が表示されない：Blue Express API only を使用している場合、料金がないと配送業者は非表示になります。Debug log をオンにし、チェックアウトを再読み込みして、モジュールページの Log フィールドを確認してください。よくある原因：API キーがない、CLP 以外のストア通貨で為替レートがない、住所に地域やコミューンがない、Blue Express がコミューンを認識しない、または API エラー（API キーが拒否された場合の HTTP 401 や 403 など）。Blue Express API, fixed price if the API gives no rate を使用している場合、問題を修正している間もお客様は固定料金を受け取れます。
チリの住所に地域がない：ページに地域の欠落に関する警告が表示されます。モジュールページで Add Chilean regions をクリックしてください。地域なしで住所が保存されたお客様は、住所を編集して地域を選択する必要があります。
Blue Express の料金に税金が追加される：Blue Express の料金には IVA が含まれます。Tax status を None (no tax on shipping) に設定してください。
マップが開かない：マップはお客様のブラウザで widget-pudo.blue.cl から読み込まれるため、このアドレスに到達でき、お使いのサイトでブロックされていない必要があります。
変更後に料金が古く見える：モジュールページで Save をクリックしてください。これにより、キャッシュされた料金とコミューンのデータが消去されます。
Blue Express の配送業者が見つからないと表示される：配送業者は Shipping > Carriers で削除されています。Modules > Module Manager でモジュールをリセットすると、再作成されます。リセットしても、設定と配送業者のステータスは保持されます。
アンインストール
Modules > Module Manager に移動し、VibeFox Blue Express の横にあるメニューを開いて Uninstall を選択します。ライセンスキー、ライセンスステータス、キャッシュされた料金は常に削除されます。Remove data on uninstall がオンの場合、両方の配送業者が削除され（注文は履歴を保持します）、設定、ログ、どの注文にも関連付けられていない受取ポイントも削除されます。オフの場合、配送業者は無効になるだけで、すべての設定は保持されます。モジュールを再インストールすると、配送業者は以前のステータスで復元されます。注文に保存された受取ポイントは決して削除されません。
Blue Express は各所有者の商標です。このモジュールは Blue Express と提携しておらず、Blue Express による承認も受けていません。