VibeFox Estafeta for OpenCart — ヘルプ
動作要件
OpenCart：3.0.x（3.0.5.0 で動作確認済み）または 4.0.2 以降（4.1.0.3 で動作確認済み）。
PHP：8.0 以降（cURL 拡張機能を含む）。
DrEnvio アカウント（リアルタイム料金の場合のみ）：Estafeta のリアルタイム料金は、メキシコにおける Estafeta のパートナーである DrEnvio から取得されます。drenvio.com でアカウントを作成し、Estafeta を有効にして、集荷先の住所をそこで設定し、DrEnvio の管理画面から API キーをコピーしてください。これは公式の DrEnvio プラグインが使うものと同じキーです。独自の料金だけを使う場合、DrEnvio アカウントは不要です。
商品：リアルタイム料金を使うには、商品に重量が必要です。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。お使いのコンピューターで解凍してください。内容は README.txt、OpenCart 3 用パッケージ vfd_estafeta-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ vfd_estafeta.ocmod.zip です。お使いの OpenCart バージョンのパッケージだけをインストールしてください。ライセンスキーは両方のバージョンで同じです。
OpenCart 3
1.管理画面で Extensions > Installer に移動し、Upload をクリックして vfd_estafeta-oc3-(version).ocmod.zip を選択します。この拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。インストーラーの代わりに、パッケージ内の upload フォルダの中身をストアのルートフォルダにコピーすることもできます。
2. Extensions > Extensions に移動し、拡張機能の種類として Shipping を選択します。VibeFox Estafeta を見つけて、Install（緑の + ボタン）をクリックします。
3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。
4. Edit ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを貼り付け、Activate をクリックします（「ライセンスキー」の項を参照）。
5. DrEnvio API key を入力し、必要に応じて Origin postcode を入力します。デフォルト通貨が MXN でない場合は、MXN exchange rate を入力します。DrEnvio から料金が返されない場合にもこの配送方法を表示させたいときは、MX の国別料金または Fallback cost を設定します。Enable/Disable をオンにして、Save をクリックします。
OpenCart 4
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして vfd_estafeta.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変えたパッケージは動作しません。
2. パッケージは同じページの、インストール済み拡張機能の一覧に表示されます。その横にある Install（緑の + ボタン）をクリックします。
3. Extensions > Extensions に移動し、拡張機能の種類として Shipping を選択します。VibeFox Estafeta を見つけ、Install（緑の + ボタン）をクリックしてから、Edit（鉛筆のボタン）をクリックします。
4. ライセンスキーと設定は、OpenCart 3 の手順 4 と 5 と同じように入力します。設定ページとそのフィールドは両方のバージョンで同じです。
インストール後は、Enable/Disable をオンにして保存するまで配送方法はオフのままです。アンインストール後に拡張機能を再インストールした場合は、保持されていた Estafeta の設定が再び使われます。
設定
すべての設定は拡張機能のページにあります：Extensions > Extensions > Shipping > VibeFox Estafeta > Edit。セクションは左側に並んでいます。ページ下部の Save ボタンで、ページを再読み込みせずにページ全体を保存できます。保存するたびに、キャッシュされた DrEnvio の料金も消去されます。この拡張機能の変更権限を持つ管理者ユーザーのみが設定を保存できます。
ページ上部には、次のような警告が表示されることがあります：DrEnvio API キーが未入力、デフォルト通貨が MXN でなく為替レートが未設定、MX の国別料金もフォールバック料金も未設定（リアルタイム料金がない場合は配送方法が非表示になり、API キーがない場合は表示されません）、あるいは単位が kg の重量クラスがない（その場合、商品の重量は重量クラスの単位名に基づいて換算され、不明な単位は kg として扱われます。System > Localisation > Weight Classes で kg のクラスを追加してください）。数値のフィールドは小数点とカンマのどちらも受け付けます。保存時に不正な値があると通知され、各フィールドの説明のとおりに消去またはリセットされます。フォームには保存された値が表示され、他の設定は引き続き保存されます（The other settings were saved.）。
一般
この配送方法は、下記のジオゾーン（またはすべての住所）、あるいは Availability without shipping zones の国に対して提供されます。
Enable/Disable：Estafeta の配送を有効または無効にします。デフォルト：無効。
Name：チェックアウト時に顧客に表示される配送方法の名前。デフォルト：Estafeta。必須：1〜64 文字。< > ; = # { } は使用できません。無効な名前は通知され、以前の名前が保持されます。
Tax class：配送料に加算される税クラス、または No tax（デフォルト）。DrEnvio の料金に IVA が含まれるかどうかは、DrEnvio アカウントによって異なります。すでに IVA が含まれている場合は No tax を選択してください。
Geo zone：この地域内の住所に対してのみ Estafeta を提供します（例：「メキシコ」のジオゾーン）。All zones（デフォルト）は制限なしを意味します。ジオゾーンは System > Localisation > Geo Zones で管理します。Ignore shipping zones がオンのときは使用されません。
Sort order：チェックアウト時に表示される配送方法の中での Estafeta の位置。整数で指定します。
リアルタイム料金（DrEnvio API）
このセクションでは、キーの入手方法を説明しています。その住所に対して最も安い Estafeta サービスが提示されます。キーがない場合は、Prices without a live rate の料金が使われます。
DrEnvio API key：DrEnvio の管理画面にある API キー。保存後、このフィールドは空になり、Saved — leave empty to keep it. と表示されます。値を変更する場合のみ新しい値を入力してください。
Remove the saved API key：保存済みのキーがあるときだけ表示されます。オンにして保存するとキーが削除されます。その後は Country prices と Fallback cost のみが使われます。上のフィールドに入力したキーは、保存済みのキーを置き換えます。
Origin country：集荷先住所の 2 文字の国コード。デフォルト：MX。出発地の郵便番号と一緒にのみ送信されます。無効なコードは通知され、MX にリセットされます。
Origin postcode：集荷先住所の 5 桁の郵便番号。空欄にすると、DrEnvio アカウントに保存された発送元住所が使われます。5 桁でない郵便番号は、保存時に消去され通知されます。
MXN exchange rate：DrEnvio はメキシコ・ペソで見積もりを行います。デフォルト通貨が MXN でない場合にのみ必要です。1 MXN のデフォルト通貨での価値を入力します（例：0.05）。未設定の場合、リアルタイム料金は使われません。0 より大きい値である必要があります。ストアの通貨が MXN の場合は空欄にしてください。
リアルタイム料金がない場合の料金
API キーがない場合、または DrEnvio から Estafeta の料金が返されない場合（API の停止、不明な郵便番号、郵便番号が未入力の場合）に使われます。料金はストアのデフォルト通貨で、税抜きです。
Country prices：1 行に 1 つの配送先国を、CC:PRICE の形式で入力します（例：MX:150）。小数点またはカンマを使い、桁区切りは使わないでください。別の形式の部分は無視され、保存時に通知されます。
Fallback cost：リアルタイム料金も国別料金もない場合の料金。空欄にすると配送方法は非表示になります。0 は送料無料を意味します。
Calculation type：Per order（デフォルト）は料金を 1 回だけ請求します。Per item (price x number of items) はカート内の商品数を掛けます。これは Country prices と Fallback cost に適用されます。DrEnvio のリアルタイム料金は、常に荷物全体の料金です。
条件
Free shipping from：配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額に達すると、この配送方法は送料無料になります。その場合、DrEnvio へのリクエストは行われません。空欄にすると、送料無料は一切適用されません。
Minimum subtotal：同じ小計がこの金額以上の場合にのみ配送方法を表示します。空欄にすると常に表示されます。
Min weight (kg)：配送方法が表示されるためのカートの最低重量。0 は制限なし（デフォルト）を意味します。
Max weight (kg)：カートの最大重量。これを超えると配送方法は非表示になります。デフォルト：30。0 は制限なしを意味します。
Min weight が Max weight より大きい場合、保存時にエラーが表示され、両方の重量は変更されません。商品の重量は、各商品の重量クラスから kg に換算されます。
配送ゾーンを使わない場合の提供範囲
Ignore shipping zones：ジオゾーンを確認せず、下記の国に対して配送方法を提供します。デフォルト：無効。
Countries：このモードでの配送先国。空欄にするとすべての国が対象になります。Ignore shipping zones がオンのときにのみ使用されます。
詳細設定
Debug log：API リクエストと料金の計算を storage/logs/vfd_est_debug.log.php（OpenCart 4 では system/storage/logs/vfd_est_debug.log.php） に書き込みます。このファイルはウェブから読み取れません。API のエラーは、ログがオフでも常に記録されます。API キーと顧客の住所は決して記録されません。作業が終わったらログをオフにしてください。ファイルが 5 MB に達すると、vfd_est_debug.old.log.php に移動され、新しいログが始まります。
Log：デバッグログのサイズと最新のエントリを表示します。Clear log をクリックすると空になります。
Remove data on uninstall：オンにすると、拡張機能のアンインストール時にすべての設定とログが削除されます。オフ（デフォルト）の場合は、再インストールに備えてすべてが保持されます。注文に保存された Estafeta のサービス情報は常に保持されます。
インポート / エクスポート
Export：Download JSON をクリックすると、設定が JSON ファイルとして保存されます。API キーはエクスポートされません。
Import：以前にエクスポートした JSON を貼り付け、Import をクリックすると、設定が復元されます（例：別のストアで）。値は通常の保存と同じように検証されます。保存済みの API キーは維持されます。
チェックアウト時の動作
OpenCart が配送方法を表示するとき、拡張機能に Estafeta の料金を問い合わせます。Geo zone が設定されていて（かつ Ignore shipping zones がオフの場合）、住所がその範囲外であれば、Estafeta は提示されません。Requires Shipping が Yes に設定された商品だけが計算に含まれます。それ以外の商品は重量に加算されず、小計にも含まれません。小計は、クーポン割引後・税抜きのこれらの商品の価格です。ギフト券、ポイント、ストアクレジットは考慮されません。次に拡張機能は条件を確認します：Ignore shipping zones がオンのときの Countries の一覧、カートの重量、最低小計です。送料無料が適用される場合、料金は 0 となり、DrEnvio へのリクエストは送信されません。
それ以外の場合、拡張機能は配送先の国と郵便番号、カートの重量、商品数、MXN での小計を DrEnvio に送信します。発送元の郵便番号を設定していれば、それも送信されます。メキシコの郵便番号は 5 桁である必要があり、顧客がそのような配送先住所を入力するまではリクエストは行われません。DrEnvio はアカウント内のすべての配送業者の見積もりを返します。拡張機能は Estafeta の見積もりのみを使用し、0 円の料金は無視して、最も安いものを選び、デフォルト通貨に換算します。料金はその通貨の小数桁数に丸められ、選択した Tax class の税を加えて、顧客の通貨で表示されます。
各応答は 1 時間キャッシュされます。失敗したリクエストや Estafeta の料金がないルートは 5 分間記憶されるため、API の応答が遅い、または不具合があっても、チェックアウトの更新が毎回遅くなることはありません。API のタイムアウトは 12 秒です。この場合、顧客にはエラーは表示されません。国別料金またはフォールバック料金が使われ、どちらもなければ配送方法が非表示になります。理由はログに記録されます。
顧客に表示されるのは配送方法の名前と料金だけです。拡張機能は料金を計算するだけです。配送伝票の作成、ラベル（guías）の印刷、荷物の追跡は行いません。配送は DrEnvio または Estafeta のアカウントで作成してください。顧客は特定の Estafeta サービスや Estafeta の営業所を選ぶことはできず、為替レートも自動では更新されません。
OpenCart 4 では、顧客はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options ウィンドウで Estafeta を選択します。この配送方法の動作は OpenCart 3 と同じです。
注文
Estafeta を使った注文が行われると、拡張機能は顧客に表示された料金を保存します。DrEnvio への新しいリクエストは行いません。管理画面で後から注文を変更しても、料金は変わりません。OpenCart 4 では、チェックアウトは 1 つの注文を保持し、顧客が再度確定するたびにその注文を更新します。そのため、保存された料金はチェックアウトの最新の料金に置き換えられます。顧客が別の配送方法に切り替えた場合、その注文ではパネルは表示されなくなります。
Sales > Orders の注文ページには、Estafeta パネルが表示されます：
Estafeta service：DrEnvio の見積もりにおける Estafeta のサービスと、その配送日数。リアルタイム料金の場合のみ表示されます。
Price source：Live DrEnvio rate、Country price (no live rate)、Fallback cost (no live rate)、または Free shipping threshold。
Shipping cost：チェックアウト時に計算された配送料（ストアのデフォルト通貨、税抜き）。
ライセンスキー
この拡張機能は、vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Estafeta は、Extensions > Extensions > Shipping > VibeFox Estafeta > Edit ページの一番上、設定の上にあります。キーを License key に貼り付けて Activate をクリックします。その後、ブロックにはキーがマスクされた状態、ステータス（ライセンスの有効期限日やドメインなど）、そして Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）のボタンが表示されます。その下には Product: opencart-shipping-estafeta の行と、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 のアカウントで解放してください。
有効なキーがない場合、チェックアウトで Estafeta の配送方法は顧客に表示されず、料金も計算されません。同じブラウザで管理画面にログインしている管理者ユーザーには、ストア内で (unlicensed — visible to admins only) と表示された状態で配送方法が見えるため、キーを購入する前に拡張機能の設定とテストができます。OpenCart 4 ではこのプレビューは利用できません。ストアは管理画面のログインを認識しないため、有効なキーがない場合は全員に対して配送方法が非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると 7 日間非表示になります。既存の注文には影響しません。
ライセンスの期限が切れても拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスは自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日に 1 回、その後は 1 週間に 1 回です。cron ジョブは必要ありません。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
チェックアウトに Estafeta が表示されない：ライセンスが有効であること、Enable/Disable がオンであることを確認してください。Geo zone、または Ignore shipping zones と Countries を確認してください。拡張機能のページ上部の警告、重量の制限、Minimum subtotal を確認してください。API キーがない場合、または DrEnvio から Estafeta の料金が返されない場合は、配送先の国別料金またはフォールバック料金が必要です。商品の Requires Shipping が Yes に設定されていることを確認してください。
リアルタイム料金が表示されない：Debug log をオンにして、チェックアウトを再読み込みし、拡張機能のページにある Log の欄を確認してください。原因が表示されます：API キーがない、デフォルト通貨が MXN でないストアに為替レートがない、郵便番号がない、または無効、API キーが拒否された（DrEnvio の HTTP 401 または 403。API キーを確認してください）、そのルートに Estafeta の料金がない（ログには DrEnvio が返した配送業者が表示されます）、または MXN 以外の通貨の料金。
料金に IVA は含まれますか？それは DrEnvio アカウントによって異なります。DrEnvio の料金にすでに IVA が含まれている場合は、Tax class を No tax に設定してください。
変更後も料金が古いままに見える：拡張機能のページで Save をクリックしてください。これにより、キャッシュされた DrEnvio の料金が消去されます。
注文ページに Estafeta パネルがない：このパネルは、拡張機能がインストールされ有効になっていた期間に Estafeta で行われた注文にのみ表示されます。
「Warning: You do not have permission to modify VibeFox Estafeta!」と表示される：管理者ユーザーのグループは設定の閲覧のみが許可されている可能性があります。System > Users > User Groups で、そのグループに extension/shipping/vfd_estafeta（OpenCart 3）または extension/vfd_estafeta/shipping/vfd_estafeta（OpenCart 4） の変更権限を付与してください。
開発者向け：DrEnvio の API アドレスは、設定 vfd_est_api_url（テスト用）で置き換えられます。これは設定ページにフィールドとしては表示されません。
アンインストール
Extensions > Extensions に移動し、種類 Shipping を選んで、VibeFox Estafeta の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは、常に削除されます。OpenCart は Enable/Disable、Sort order、Tax class、Geo zone を常にリセットします。キャッシュされた料金は常に削除されます。Remove data on uninstall がオンの場合は、Estafeta の設定とデバッグログも削除されます。オフの場合、その他の設定は保持され、拡張機能を再インストールしたときに再び使われます。注文に保存された Estafeta のサービス情報は、どちらの場合も保持され、注文は配送方法と配送料を保持し続けます。
OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧で VibeFox Estafeta の横にある Uninstall（オレンジ色の − ボタン）をクリックしてから、アップロードしたパッケージを削除するために Delete（赤いゴミ箱のボタン）をクリックします。
Estafeta と DrEnvio は、それぞれの所有者の商標です。この拡張機能は Estafeta または DrEnvio とは提携しておらず、両社の承認や推奨を受けていません。