VibeFox Chilexpress for OpenCart — ヘルプ
要件
OpenCart: 3.0.x（3.0.5.0 でテスト済み）、または 4.0.2 以降（4.1.0.3 でテスト済み）。
PHP: 8.0 以降。
Chilexpress API キー（リアルタイム料金のみ）: Chilexpress デベロッパーポータル（developers.wschilexpress.com）でアカウントを作成し、2 つの製品に登録します: Rating (Cotizador) と Coverage (Coberturas / Georreferencia)。製品ごとに個別のサブスクリプションキーがあります。テストキーはテスト環境でのみ使用できます。本番キーは、契約を結んだ Chilexpress の法人顧客に発行されます。発送元の comuna の Chilexpress county コード（例: STGO）も必要です。固定料金のみを使用する場合、API キーは不要です。
チリの地域（リアルタイム料金のみ）: リアルタイム料金には、配送先住所の地域（ゾーン）が必要です。OpenCart 3.0.5.0 には、チリの 16 地域のうち 15 地域が含まれています。拡張機能は不足している地域を追加できます（下記 Chilean regions を参照）。ストアに Chile の国が存在している必要があります。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインでのみ使用できます。
インストール
ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。お使いのコンピューターで解凍してください。含まれるのは、README.txt、OpenCart 3 用パッケージ vfd_chilexpress-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ vfd_chilexpress.ocmod.zip です。お使いの OpenCart バージョンのパッケージのみをインストールしてください。ライセンスキーは両方のバージョンで共通です。
OpenCart 3
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_chilexpress-oc3-(version).ocmod.zip を選択します。拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。Installer を使う代わりに、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。
2. Extensions > Extensions に移動し、拡張機能の種類 Shipping を選択します。VibeFox Chilexpress を見つけて、Install（緑色の + ボタン）をクリックします。
3. Edit（鉛筆のボタン）をクリックして、設定ページを開きます。
4. Edit ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。
5. Country prices の表を入力します。リアルタイム料金を使う場合は、両方のサブスクリプションキー、発送元の county コードを入力し、ストアの通貨が CLP でなければ CLP の為替レートも入力します。ページに不足している地域が表示される場合は Add Chilean regions をクリックし、続いて料金ソースを選択します（設定を参照）。Enable/Disable をオンにして Save をクリックします。
OpenCart 4
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_chilexpress.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 はファイル名から拡張機能のコードを取得するため、名前を変えたパッケージは動作しません。
2. パッケージは、同じページのインストール済み拡張機能の一覧に表示されます。その横の Install（緑色の + ボタン）をクリックします。
3. Extensions > Extensions に移動し、拡張機能の種類 Shipping を選択します。VibeFox Chilexpress を見つけ、Install（緑色の + ボタン）をクリックしてから、Edit（鉛筆のボタン）をクリックします。
4. OpenCart 3 の手順 4 と 5 と同じようにライセンスキーと設定を入力します。設定ページとその項目は、両方のバージョンで同じです。
インストール後は、Enable/Disable をオンにして保存するまで、この方法はオフのままです。アンインストール後に拡張機能を再インストールした場合、保存されていた Chilexpress の設定が再び使われます。
設定
すべての設定は拡張機能のページにあります: Extensions > Extensions > Shipping > VibeFox Chilexpress > Edit。セクションは左側に並んでいます。下部の 1 つの Save ボタンで、ページを再読み込みせずにページ全体を保存します。保存後、Settings saved. Cached Chilexpress rates and comuna lists were cleared. と表示されます。設定の保存、ログのクリア、地域の追加ができるのは、この拡張機能の変更権限を持つ管理者ユーザーだけです。
ページの上部には問題が表示されます。API 料金が選択されているのに Rating API キーが空である、Coverage API キーが空である、発送元の county コードが空または無効である、ストアの通貨が CLP ではなく CLP の為替レートが設定されていない、Country prices にチリまたはデフォルトの行がない、ストアにチリのゾーンがない、ストアの重量または長さの単位が拡張機能で認識されない（その場合、重量は kg、寸法は cm として読み取られます。System > Localisation で kg、g、lb、oz のいずれか、および cm、mm、m、in のいずれかを使用してください）などです。数字は小数点またはカンマで入力できます。Name が空である、または < > ; = # { } のいずれかの文字を含む、または 64 文字を超える、数値が無効または負である、CLP exchange rate が 0 である、Min weight (kg) が Max weight (kg) より大きい、Origin county code が county コードではない、または Sort order が整数ではない場合、何も保存されず、ページにエラーが一覧表示されます。
一般
すべてのジオゾーンに対して 1 つの配送方法「Chilexpress」、または Availability で選択したジオゾーンに対して提供します。
Enable/Disable:チェックアウトで Chilexpress を表示するか非表示にします。既定値: オフ。
Name:チェックアウトで購入者に表示される配送方法の名前。既定値: Chilexpress。必須。64 文字まで。
Tax class:配送料の税クラス、または No tax（既定値）。Chilexpress API の料金は、見積もられたとおりに使用されます。見積もりに IVA がすでに含まれていて、ストアがその上にさらに税を加える場合は、No tax を選択します。
Sort order:チェックアウトの配送方法の中で Chilexpress が表示される位置。整数です。
料金
Rate source:料金の取得元。
リアルタイム料金は、チリ国内の宛先でのみ利用できます。それ以外の国では常に固定料金が使われます。
Country prices:宛先の国のリスト。Price の列と、任意の荷物サイズ別の料金（ストアの既定の通貨、税抜き）を含みます。サイズはカートの重量から決まります: XS は 1 kg まで、S は 2 kg まで、M は 3 kg まで、L は 5 kg まで、XL は 5 kg 超。サイズ欄が 0 の場合は Price が使われます。Add country をクリックすると行が追加されます。* Default (other countries) の行は、独自の行がない国に適用されます。行がない国（デフォルトの行もない場合）には固定料金がないため、その国ではこの方法が非表示になります。保存された行で、料金とサイズ別料金がすべて 0 の場合は送料無料になります。空の表には、0 のチリの行が 1 つ表示されるため、ページを保存する前に実際の料金を入力してください。重複する国や無効な料金は自動的に修正されます（重複は無視され、料金は 0 になります）。修正内容は警告に一覧表示されます。
Calculation type:Per order（既定値）は固定料金を 1 回だけ請求します。Per item (fixed price x number of items) は、カート内の商品数を掛けます。Chilexpress API の料金は常に荷物全体に対して見積もられます。
Chilexpress API（リアルタイム料金）
このセクションは、デベロッパーポータルと Rating および Coverage のサブスクリプションページへのリンクで始まります。
Test environment:Chilexpress のテスト環境（qaservices.wschilexpress.com）を使用します。テストキーと併用し、本番ストアではオフにしてください。既定値: オフ。
Rating API key:Rating (Cotizador) 製品のサブスクリプションキー。
Coverage API key:Coverage (Coberturas / Georreferencia) 製品のサブスクリプションキー。購入者の comuna の Chilexpress county コードを見つけるために使われます（住所の City 欄と、その地域を組み合わせて使用します）。
保存後、キーの欄は空のままになり、Saved — leave empty to keep it. と表示されます。変更したい場合にのみ、新しい値を入力してください。キーは入力したとおりに保存され、前後の空白のみが削除されます。
Remove the saved Rating API key と Remove the saved Coverage API key:いずれかをオンにして Save をクリックすると、そのキーが削除されます。
Origin county code:発送元の comuna の Chilexpress county コード。2〜5 文字で、例として STGO（Santiago Centro）、PROV（Providencia）、VALP（Valparaíso）があります。インストール直後は空です。county コードではない値は、エラーで拒否されます。
Service:料金の計算に使われる Chilexpress のサービス。宛先で提供されていない場合は、提供されている中で最も安いサービスが使われます。
CLP exchange rate:Chilexpress はチリペソで見積もります。ストアの既定の通貨が CLP でない場合にのみ必要です。その通貨での 1 CLP の価格を入力します（例: 0.001）。これがないと API の料金は使用されません。ストアの通貨が CLP の場合は空欄のままにしてください。値は 0 より大きくなければなりません。
Chilean regions:チリの comuna は地域ごとに検索されるため、リアルタイム料金には住所の地域（ゾーン）が必要です。この欄には、チリにあるゾーンの数と不足している地域が表示され、Add Chilean regions ボタンが付いています。不足している地域のみをチリのゾーンとして追加し、既存のゾーンは変更せず、同じ地域を 2 回追加することもありません。16 地域すべてが揃うと、欄には All 16 Chilean regions are zones of Chile と表示されます。チリがストアの国に含まれていない場合は、その旨が表示されます。System > Localisation > Countries で追加してください。
提供条件
Min weight (kg):この方法が表示されるために必要なカートの最小重量。0 は制限なし（既定値）。
Max weight (kg):カートの重量がこの値を超えると、この方法は非表示になります。既定値: 25。0 は制限なし。空欄の場合は 25 kg として扱われます。
Minimum subtotal:カートの小計（配送が必要な商品、クーポン適用後、税抜き）がこの金額以上の場合にのみ、この方法を表示します。空欄の場合は常に表示されます。
Geo zone:このジオゾーン内の住所に対してのみ、この方法を提供します。All zones（既定値）は制限なしを意味します。ジオゾーンは System > Localisation > Geo Zones で管理されます。Ignore shipping zones がオンの間は使用されません。
Ignore shipping zones:ジオゾーンを確認せずに、以下の国に対してこの方法を提供します。
Countries:このモードで対象となる宛先の国。空欄の場合はすべての国を許可します。この欄は Ignore shipping zones がオンの場合にのみ使用されます。
送料無料
Free shipping:送料無料のしきい値をオンにします。
Free shipping from:送料が無料になるカートの小計（配送が必要な商品、クーポン適用後、税抜き）。Free shipping がオンの場合にのみ使用されます。この場合、API へのリクエストは行われません。
詳細設定
Debug log:API リクエストと料金計算を storage/logs/vfd_chx_debug.log.php に書き込みます。このファイルはウェブから読み取ることはできません。このオプションがオフでも、API のエラーは常に記録されます。API キーと購入者の住所は、記録されることはありません。ファイルが 5 MB に達すると、vfd_chx_debug.old.log.php に移動され、新しいログが開始されます。
Log:デバッグログのサイズと最新のエントリを表示します。Clear log をクリックすると空になります。
Remove data on uninstall:オンにすると、拡張機能をアンインストールした際に、そのすべての設定、キャッシュされた料金、ログが削除されます。オフ（既定値）の場合は、再インストールのためにすべてが保持されます。注文とそれに保存された Chilexpress のサービスは、常に保持されます。
インポート / エクスポート
Export:Download JSON をクリックして、設定を JSON ファイルとして保存します。API キーはエクスポートされません。
Import:以前にエクスポートした JSON を貼り付け、Import をクリックすると設定が復元されます（別のストアでの利用など）。値は通常の保存と同じように検証されます。保存済みの API キーは保持されます。
チェックアウト時の動作
OpenCart が配送方法を表示するとき、拡張機能に Chilexpress の料金を問い合わせます。Geo zone が設定されていて、Ignore shipping zones がオフで、住所がゾーン外の場合、Chilexpress は提供されません。Requires Shipping が Yes に設定されている商品だけが対象になります。それ以外の商品は重量に加算されず、小計にも含まれません。重量は商品の重量クラスとサイズのクラスに基づいてキログラムに、寸法はセンチメートルに変換されます。小計は、配送が必要な商品の価格で、クーポン割引適用後、税抜き、ストアの既定の通貨によるものです。ギフト券、ポイント、ストアクレジットは考慮されません。拡張機能はまず条件を確認します: 許可された国（Ignore shipping zones を使用時）、カートの重量、最小小計。送料無料が適用される場合、料金は 0 になり、Chilexpress へのリクエストは送信されません。
チリの住所で API の料金ソースを使う場合、拡張機能は住所の地域（ゾーン）と City 欄の comuna を取得し、その地域の comuna リストから Chilexpress の county コードを探します（Coverage API）。アクセント記号、空白、表記のゆれは無視されるため、Ñuñoa と Nunoa は一致し、Santiago は Santiago Centro と一致します。City 欄に入力された county コードも受け付けられます。その後、拡張機能は発送元と宛先の county コード、カートの重量（最低 0.1 kg）、荷物のサイズ（最も大きい商品の長さと幅、高さは積み重ねた合計）、そしてカートの小計（CLP 建て）を申告価格として Rating API に送信します。Chilexpress はそのサービスを返します。拡張機能は選択されたサービスまたは最も安いサービスを使用し、ペソの金額をストアの既定の通貨に換算します。料金はその通貨の小数桁に丸められ、Tax class の税を加えて購入者の通貨で表示されます。
料金は 1 時間キャッシュされます。comuna のリストは最大 7 日間キャッシュされますが、OpenCart がそのキャッシュの項目を保持する期間（既定では 1 時間）を超えることはありません。失敗したリクエストは 5 分間記憶されるため、遅い、または利用できない API がチェックアウトの更新のたびに遅延を生じさせることはありません。API のタイムアウトは 10 秒です。Chilexpress がエラーを返した場合、料金付きのサービスがない場合、または comuna や地域が不明な場合でも、購入者にエラーは表示されません。API のみのモードでは、この方法は非表示になります。または固定料金が使われます。理由はデバッグログに書き込まれます。
拡張機能は料金の計算のみを行います。発送伝票や輸送注文（OT）の作成、ラベルの印刷、集荷の予約、荷物の追跡は行いません。発送は Chilexpress のアカウントで予約してください。購入者は Chilexpress の営業所を選択できず、comuna のセレクターもありません。購入者は標準の City 欄に comuna を入力します。国際配送には固定料金が使われます。
OpenCart 4 では、購入者はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options ウィンドウで Chilexpress を選びます（例: Chilexpress - $5.49）。この方法の動作は OpenCart 3 と同じです。
注文
Chilexpress で注文が行われると、拡張機能はその料金の計算方法を保存します。Sales > Orders の注文ページには、Chilexpress パネルが表示されます。このパネルには Chilexpress service（リアルタイム料金の場合は Chilexpress が見積もったサービス（例: Express）。それ以外の場合はダッシュ）と Price（Live rate (Chilexpress Rating API)、Fixed price、または Free shipping）が含まれます。このパネルは、この方法がオフのときも表示されます。OpenCart 4 では、Chilexpress パネルは History の上に表示され、注文がチェックアウトで再確認されたり、別の配送方法に変更されたりすると、パネルも変更に合わせて更新されます。
ライセンスキー
この拡張機能は、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Chilexpress は、Extensions > Extensions > Shipping > VibeFox Chilexpress > Edit の最初のブロックで、設定の上にあります。キーを License key に貼り付けて Activate をクリックします。その後、ブロックにはキーがマスクされて表示され、ステータス（ライセンスが有効な期限の日付や、お使いのドメインなど）と、ボタンが表示されます。ボタンは、Check now でステータスを再確認、Change key で別のキーを入力、Remove key でこのストアからキーを削除します。その下には Product: opencart-shipping-chilexpress の行と、お使いの 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 のアカウントで枠を解放してください。
有効なキーがない場合、チェックアウトで Chilexpress は購入者に表示されず、料金も計算されません。同じブラウザで管理画面にログインしている管理者ユーザーには、(unlicensed — visible to admins only) と表示された状態で、ストアにこの方法が表示されます。そのため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 ではこのプレビューは利用できません。ストアは管理画面へのログインを認識しないため、有効なキーがない場合は全員にこの方法が表示されません。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると、7 日間非表示になります。既存の注文には影響しません。
ライセンスの期限が切れても、拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。キーを入力してから最初の 14 日間は 1 日に 1 回、その後は週に 1 回、管理画面の Dashboard または Edit ページを開いたときに、ステータスが自動的に再確認されます。cron ジョブは必要ありません。拡張機能をアンインストールすると、ライセンスキーとライセンスのステータスは常に削除されます。
トラブルシューティング
Chilexpress がチェックアウトに表示されない:ライセンスが有効で、Enable/Disable がオンになっていることを確認してください。Geo zone（または Ignore shipping zones と Countries）、重量の制限、Minimum subtotal を確認します。固定料金の場合は、その国または * Default (other countries) に行があることを確認してください。商品の Requires Shipping が Yes になっていることを確認します。
チリの配送料が無料になっているが、無料であるべきではない:チリの Country prices の行（またはデフォルトの行）の Price とサイズの列が 0 になっています。料金を入力して Save をクリックしてください。
リアルタイム料金が表示されず、固定料金が使われる:まず拡張機能のページ上部の警告を確認してください。何もなければ Debug log をオンにし、チェックアウトを再読み込みして、拡張機能のページにある Log 欄を確認します。典型的な原因: 住所に地域がない、またはチリに地域が不足している（Add Chilean regions を使用）、Chilexpress が認識しない comuna（City 欄と地域を確認）、誤った製品または環境のキー、または Chilexpress の提供エリア外の宛先。
ログに HTTP 401 または 403 が表示される:サブスクリプションキーが誤っている、無効である、または別の製品や環境のものです。テストキーは Test environment がオンのときにのみ機能します。
別の通貨のストアで API の料金が使われない:CLP exchange rate を入力してください。
API の料金に IVA は含まれているか？Chilexpress が見積もったとおりに使われます。ストアが配送料に税を加える場合で、見積もりに IVA がすでに含まれている場合は、Tax class を No tax に設定してください。
変更後に料金が古く見える:拡張機能のページで Save をクリックしてください。キャッシュされた料金と comuna のリストが消去されます。
ページに "Warning: You do not have permission to modify VibeFox Chilexpress!" と表示される:管理者のユーザーグループに設定の閲覧権限しかない可能性があります。System > Users > User Groups で、そのグループに extension/shipping/vfd_chilexpress（OpenCart 3）または extension/vfd_chilexpress/shipping/vfd_chilexpress（OpenCart 4）の変更権限を付与してください。
開発者向け:Chilexpress API の基本アドレスは、設定 vfd_chx_api_base_url（テスト用）で置き換えることができます。設定ページには、その欄はありません。
アンインストール
Extensions > Extensions に移動し、種類 Shipping を選択して、VibeFox Chilexpress の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスのステータスは、常に削除されます。OpenCart は常に Enable/Disable、Sort order、Tax class、Geo zone をリセットします。キャッシュされた料金と comuna のリストは、常に削除されます。Remove data on uninstall がオンの場合、その他の設定とデバッグログも削除されます。オフの場合は、それらが保持され、拡張機能を再インストールしたときに再び使用されます。注文と共に保存された Chilexpress のサービスは削除されることはなく、既存の注文は配送方法と送料を保持します。Add Chilean regions で追加されたチリの地域は、ストアに残ります。
OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧で VibeFox Chilexpress の横にある Uninstall（オレンジ色の − ボタン）をクリックし、次にアップロードしたパッケージを削除するため Delete（赤いゴミ箱のボタン）をクリックします。
Chilexpress は、各所有者の商標です。本拡張機能は Chilexpress とは提携しておらず、Chilexpress による推奨もされていません。