VibeFox Blue Express for OpenCart — ヘルプ
要件
OpenCart: 3.0.x（3.0.5.0 で動作確認）、または 4.0.2 以降（4.1.0.3 で動作確認）。
PHP: 8.0 以降。
Blue Express アカウント（リアルタイム料金のみ）: リアルタイム料金には、Blue Express の e-commerce アカウントと 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 つのドメインで使用できます。
インストール
ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。コンピュータで展開してください。README.txt、OpenCart 3 用パッケージ vfd_blue_express-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ vfd_blue_express.ocmod.zip が含まれています。お使いの OpenCart バージョンのパッケージのみをインストールしてください。ライセンスキーは両方のバージョンで同じです。
OpenCart 3
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_blue_express-oc3-(version).ocmod.zip を選択します。本拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。Installer を使わず、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。
2. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選択します。VibeFox Blue Express を見つけて Install（緑色の + ボタン）をクリックします。
3. Edit（鉛筆ボタン）をクリックして設定ページを開きます。
4. VibeFox ライセンスキーを、Edit ページ上部のライセンスブロックにある License key に入力し、Activate をクリックします（ライセンスキーを参照）。
5. API キー、サービス、発送元の地区コード（例: SCL）、ストアの通貨が CLP でない場合は CLP の為替レート、固定料金（例: CL=4500）を入力します。自宅への配送には Enable/Disable を、Blue Express の拠点での受け取りを提供する場合は Pickup point option を有効にします。Save をクリックします。設定を参照してください。
OpenCart 4
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_blue_express.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変えたパッケージは動作しません。
2. パッケージは、同じページのインストール済み拡張機能の一覧に表示されます。その横の Install（緑色の + ボタン）をクリックします。
3. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選択します。VibeFox Blue Express を見つけ、Install（緑色の + ボタン）をクリックしてから、Edit（鉛筆ボタン）をクリックします。
4. OpenCart 3 の手順 4 と 5 と同じように、ライセンスキーと設定を入力します。設定ページとそのフィールドは両方のバージョンで同じです。
インストール時に、拡張機能は注文の受け取りポイント用のテーブルを作成します。自宅配送または受け取りオプションを有効にして保存するまで、この方法はオフのままです。アンインストール後に再インストールすると、保存されていた Blue Express の設定が再び使用されます。
設定
すべての設定は拡張機能のページにあります: Extensions > Extensions > Shipping > VibeFox Blue Express > Edit。セクションは左側に表示されます。Save ボタンを 1 回押すと、ページを再読み込みせずにページ全体が保存されます。また、保存するたびに、キャッシュされた Blue Express の料金とコミューンのデータが消去されます。この拡張機能の変更権限を持つ管理者ユーザーだけが設定を保存できます。以下の条件、料金、税クラスは、両方のオプションに適用されます。
無効な値は、エラーとともに拒否され、何も保存されません。空の名前、または < > ; = # { } の文字を含む名前、64 文字を超える名前、負の数または無効な数値、Min weight (kg) が Max weight (kg) より大きい場合、整数ではない Sort order、存在しない税クラスやジオゾーンがこれに当たります。
オプションやリアルタイム料金を非表示にしてしまう設定については、ページ上部に警告が表示されます。API キーがない場合、Exchange rate が未設定の CLP 以外のストア通貨、固定料金の表が空の場合、チリのゾーンがない場合、そして拡張機能が既定の単位を認識できない kg の重量クラスや cm の長さクラスがないストアが対象です（その場合、重量は kg、寸法は cm として読み取られます）。
一般
Enable/Disable: チェックアウトでの Blue Express の自宅配送を有効または無効にします。
Name: 自宅配送のためにチェックアウトに表示される配送方法の名前。デフォルト: Blue Express。必須、64 文字以内。
Tax class: 配送料の税クラス、または None (no tax on shipping)（デフォルト）。Blue Express の料金には IVA（付加価値税）が含まれます。OpenCart で上乗せ課税をしない場合は None を選択してください。両方のオプションに適用されます。
Sort order: チェックアウトの配送方法の中での Blue Express の表示順。整数。
Blue Express の拠点での受け取り（PUDO）
Pickup point option: 顧客が選んだ Blue Express の拠点への配送を、自宅配送の横の 2 つ目のオプションとして提供します。デフォルトでは無効です。
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 (your currency): ラベルには、ストアのデフォルト通貨が表示されます。例: CLP per 1 EUR。Blue Express の料金はチリペソ（CLP）で表示されます。ストアのデフォルト通貨の 1 単位が何 CLP に相当するかを入力してください。例: 1050。これがないと、リアルタイム料金は使用されません。ストアの通貨が CLP の場合は無視されます。
料金
Rate source: 料金の計算方法。リアルタイム料金には、地域とコミュニ（市区町村）を含むチリの住所が必要です。エラーはログに記録され、顧客に表示されることはありません。
Fixed prices: 国ごとに 1 行、国コード=料金の形式で、ストアのデフォルト通貨で、税抜きで入力します。例: 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 を意味します。
Minimum order subtotal: カートの小計（ストアの通貨、配送が必要な商品、クーポン適用後、税抜き）がこの金額以上の場合にのみ、方法を表示します。常に表示する場合は空欄のままにします。
送料無料
Free shipping: カートの小計に基づき、送料無料を有効にします。
Free from subtotal: 送料が無料になるカートの小計（ストアの通貨、配送が必要な商品、クーポン適用後、税抜き）。その場合、Blue Express へのリクエストは送信されません。Free shipping が有効な場合にのみ使用されます。
提供条件
Geo zone: このジオゾーン内の住所に対してのみ Blue Express を提供します。All zones（デフォルト）は制限なしを意味します。ジオゾーンは System > Localisation > Geo Zones で管理します。Ignore shipping zones では確認されません。
Ignore shipping zones: どのジオゾーンでも両方のオプションを提供します。その場合、国は以下のリストで制限されます。
Countries: このモードの配送先の国。空欄の場合はすべての国を許可します。Ignore shipping zones と一緒に使用される場合にのみ適用されます。
チリの地域（ストアにチリの地域がない場合にのみ表示）
Blue Express では、リアルタイム料金のためにチリの住所の地域（RM、VS など）が必要です。地域は住所のゾーンから、そのコードまたは名前によって取得されます。このセクションでは、ストアのチリのゾーン数と、不足している地域が表示されます（標準の OpenCart 3.0.5 ストアでは、16 地域のうち 15 地域があり、Ñuble がありません）。Add Chilean regions をクリックすると、不足している地域が Blue Express で使われるコードとともに、チリのゾーンとして追加されます。コードまたは名前で既にある地域は、二重に追加されません。ボタンをクリックするまで何も変更されません。System > Localisation > Zones で自分で追加することもできます。
詳細設定
Debug log: リクエストと判断を storage/logs/vfd_blex_debug.log.php に記録します。このファイルは Web から読み取ることはできません。API エラーは常に記録されます。API キーと顧客の住所は決して記録されません。作業が終わったらログをオフにしてください。ログが 5 MB に達するとローテーションされます。
Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログが空になります。
Remove data on uninstall: オンの場合、拡張機能をアンインストールすると、設定、キャッシュされた料金、ログが削除されます。オフの場合（デフォルト）は、再インストール用に保持されます。注文に保存された受け取りポイントは常に保持されます。
インポート / エクスポート
Export: Download JSON をクリックすると、設定が JSON ファイルとして保存されます。API キーはエクスポートされません。
Import: 以前にエクスポートした JSON を貼り付けて Import をクリックすると、設定が復元されます（別のストアでの利用など）。値は通常の保存と同様に検証されます。保存済みの API キーは保持されます。
チェックアウトでの動作
OpenCart が配送方法を表示するとき、有効な各オプションの料金を拡張機能に問い合わせます。Geo zone が設定されていて（かつ Ignore shipping zones がオフの）、住所がその外にある場合、Blue Express は提供されません。Ignore shipping zones が有効な場合は、Countries のリストが適用されます。Requires Shipping が Yes に設定された商品のみが対象です。それ以外の商品は重量に加算されず、小計にも含まれません。拡張機能は次に、カートの重量と Minimum order subtotal を確認します。小計は、配送が必要な商品の価格で、クーポン割引後、税抜きです。ギフトカード、ポイント、ストアクレジットは考慮されません。送料無料が適用される場合、料金は 0 となり、Blue Express へのリクエストは送信されません。
リアルタイム料金の場合、住所はチリにあり、地域と市区町村（コミューン）が必要です。拡張機能は最初に、Blue Express にコミューンを認識するよう要求し、その後、サービス、発送元の地区、配送先、荷物の料金を要求します。各商品は、重量と寸法を重量クラスと長さクラスから kg と cm に変換して送信されます。重量や寸法がない商品は、0.01 kg、10 x 10 x 10 cm として送信されます。申告額は CLP で送信されます。CLP の料金は、ストアのデフォルト通貨に換算され、その小数桁に丸められ、選択した Tax class の税金を含めて、顧客の通貨で表示されます。
料金は 1 時間、コミューンのデータは最大 12 時間キャッシュされますが、OpenCart のキャッシュの有効期間（デフォルトは 1 時間）を超えることはありません。API の呼び出しが失敗した場合は 5 分間記憶され、タイムアウトは 10 秒です。そのため、API が遅い場合や利用できない場合でも、チェックアウトの更新のたびに遅くなることはありません。API のエラーが顧客に表示されることはありません。オプションが非表示になるか、フォールバックモードでは固定料金が使用されます。理由はログに記録されます。
拡張機能は、Blue Express での発送データやラベルの作成、追跡番号の割り当て、追跡情報の表示を行いません。発送は Blue Express のアカウントで作成してください。コミューン単位の地域別料金表はありません。Blue Express API の料金か、国ごとの固定料金を使用してください。リアルタイム料金はチリでのみ利用できます。
OpenCart 4 では、お客様はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options ウィンドウで Blue Express または Blue Express pickup point を選びます。オプションの動作は OpenCart 3 と同じです。受け取りポイントのボックスについては、受け取りポイントの項目を参照してください。
受け取りポイント
Pickup point option が有効な場合、OpenCart のチェックアウトの Delivery Method ステップで、Blue Express pickup point の下に、Choose pickup point ボタンのあるボックスが表示されます。このボタンを押すと、顧客がポイントを選べる Blue Express の公式地図が開きます。選んだポイントは名前と住所とともに表示され、ボタンは Change pickup point に変わります。ポイントはチェックアウトのセッションに保存され、料金は Blue Express の受け取り（PUDO）料金で再計算されます。料金が変わった場合、オプションには新しい料金が表示されます。そのポイントでこのオプションが提供されなくなった場合は、配送ステップが再読み込みされます。ポイントを選ぶまでは、オプションに自宅配送の料金が表示されます。
顧客はポイントを選ばないと先に進めません。配送ステップの Continue は、Please choose a Blue Express pickup point. と表示されて拒否されます。これはブラウザ上で確認され、さらにストアでも確認されます。形式の正しくないポイントコードは、The selected Blue Express pickup point is not valid. Please choose it again on the map. と表示されて拒否され、以前の選択は保持されます。保存に失敗した場合、顧客には The pickup point could not be saved. Please try again. と表示されます。
OpenCart 4 では、お客様はチェックアウトページの配送方法ブロックで Choose をクリックします。このオプションが選択されている間、Shipping method options ウィンドウには、Blue Express pickup point の下に Choose pickup point を含む同じボックスが表示されます。選んだポイントで料金が変わると、ウィンドウ内のオプションに新しい料金が表示されます。受け取りオプションがチェックアウト用にすでに保存されていた場合は、配送方法のフィールドと注文確認ブロックも更新されます。そのポイントでこのオプションが提供されなくなった場合は、ウィンドウが閉じられ、配送方法の一覧が再度読み込まれます。ポイントを選ばずにウィンドウ内で Continue をクリックすると、ボックス内で Please choose a Blue Express pickup point. と表示されて止まり、ストアが再度確認します。OpenCart 4 はチェックアウト用に 1 つの注文を保持し、確認のたびに更新します。注文の受け取りポイントもそれに合わせて更新され、注文を別の配送方法に変更すると削除されます。
注文が確定すると、ポイントは Blue Express の代理店コード、名前、住所、地域とともに注文に保存されます。また、受け取りオプションの名前の後に、注文の配送方法にも追加されます。例: Blue Express pickup point: Blue Point Providencia, Av. Providencia 1234。これにより、顧客は注文メールとアカウントの注文ページでこれを確認できます。
管理画面の注文ページ（Sales > Orders、View）では、Blue Express pickup point パネルに、ポイントがそのコードと地域とともに表示されます。注文にポイントがない場合、パネルには Not chosen と表示されます。Edit をクリックし、Choose on the Blue Express map で別のポイントを選ぶか、Agency code、Name、Address を手動で入力してから、Save pickup point をクリックします。注文の配送方法のテキストも更新され、この変更は顧客に通知されることなく注文履歴に追加されます（Blue Express pickup point changed: 旧コード -> 新コード）。ポイントの変更には注文の変更権限のみが必要で、拡張機能の設定へのアクセス権は不要です。既存の注文は受け取りポイントのデータを保持します。
ライセンスキー
この拡張機能は、vibefox.net で発行された VibeFox ライセンスキーで動作します。License — VibeFox Blue Express のライセンスブロックは、Extensions > Extensions > Shipping > VibeFox Blue Express > Edit ページで、設定の上にある最初のブロックです。キーを License key に貼り付けて Activate をクリックします。その後、ブロックにはキーがマスクされた状態で表示され、ステータス（例: ライセンスの有効期限日と、お使いのドメイン）、および Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）のボタンが表示されます。その下には Product: opencart-shipping-blue-express の行と Manage licenses and domains in your account のリンクがあり、vibefox.net のアカウントが開きます。キーを変更できるのは、この拡張機能の変更権限を持つ管理者ユーザーだけです。ブロックのテキストは管理画面の言語に従います（英語とロシア語が含まれます）。
キーが受け付けられない場合、ブロックには理由が表示されます。例: Key not found、This key belongs to another product、Domain limit reached、または日付付きの License expired on。ストアのアドレスを変更した後、またはアカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、拡張機能は最後に確認できた状態で動作を続けます。
1 つのキーは 1 つのドメインで使用できます。このドメインとは、OpenCart の設定にあるストアのアドレスのことです。ストアからキーを削除しても、ドメインの枠は解放されません。枠は vibefox.net のアカウントで解放してください。
有効なキーがない場合、Blue Express はチェックアウトでお客様に表示されず、料金も計算されません。同じブラウザで管理画面にログインしている管理者ユーザーには、(unlicensed — visible to admins only) と表示された状態で、ストアにこの方法が引き続き表示されます。そのため、キーを購入する前に拡張機能を設定してテストできます。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると、7 日間非表示になります。既存の注文には影響しません。
ライセンスが期限切れになっても、拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスは自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日に 1 回、その後は週に 1 回です。cron ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
チェックアウトに Blue Express が表示されない: ライセンスが有効で、Enable/Disable（または Pickup point option）がオンになっているか確認してください。拡張機能ページの上部にある警告を確認してください。Geo zone（または Ignore shipping zones と Countries）、重量制限、Minimum order subtotal を確認してください。固定料金またはフォールバックを使う場合は、Fixed prices にその国の行があるか確認してください。商品の Requires Shipping が Yes に設定されているか確認してください。
リアルタイム料金が表示されない: Blue Express API only の場合、料金がなければオプションは非表示になります。Debug log をオンにし、チェックアウトを再読み込みして、拡張機能ページの Log フィールドを確認してください。よくある原因は、API キーがない、Exchange rate が未設定のままで 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 class を None (no tax on shipping) に設定してください。
地図が開かない: 地図は顧客のブラウザで widget-pudo.blue.cl から読み込まれるため、このアドレスにアクセスできて、サイトでブロックされていない必要があります。
変更後に料金が古く見える: 拡張機能のページで Save をクリックしてください。キャッシュされた料金とコミューンのデータが消去されます。
ページに「Warning: You do not have permission to modify VibeFox Blue Express!」と表示される: 管理者のユーザーグループには設定の閲覧権限しかない可能性があります。System > Users > User Groups で、そのグループに extension/shipping/vfd_blue_express（OpenCart 3）または extension/vfd_blue_express/shipping/vfd_blue_express（OpenCart 4）の変更権限を付与してください。
開発者向け: Blue Express の API と地図のアドレスは、設定 vfd_blex_api_url と vfd_blex_widget_url（テスト用）で置き換えられます。設定ページにはこれらの項目のフィールドはありません。
アンインストール
Extensions > Extensions に移動し、種類 Shipping を選択して、VibeFox Blue Express の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは常に削除されます。OpenCart は常に、方法のステータス、Sort order、Tax class、Geo zone をリセットします。キャッシュされた料金は常に削除されます。Remove data on uninstall がオンの場合、Blue Express の設定とログも削除されます。オフの場合、その他の設定は保持され、拡張機能を再インストールしたときに再び使用されます。注文に保存された受け取りポイントは削除されず、既存の注文の配送方法のテキストにも受け取りポイントが残ります。
OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧で VibeFox Blue Express の横にある Uninstall（オレンジ色の − ボタン）をクリックしてから、Delete（赤いゴミ箱ボタン）をクリックして、アップロードしたパッケージを削除します。
Blue Express は、それぞれの所有者の商標です。本拡張機能は Blue Express と提携しておらず、Blue Express による推奨も受けていません。