VibeFox Envioclick for OpenCart — ヘルプ
要件
OpenCart: 3.0.x（3.0.5.0 で検証済み）または 4.0.2 以降（4.1.0.3 で検証済み）。
PHP: 8.0 以降。
Envioclick アカウント（リアルタイムの料金のみ）: メキシコまたはコロンビアの、API アクセスが有効な Envioclick アカウント。API キーは Envioclick アカウントの Mi cuenta（右上）> Información del API にあります。固定料金のみを使用する場合は、Envioclick アカウントは不要です。
User-Agent（メキシコのみ）: Envioclick メキシコでは、すべての API リクエストに User-Agent の値が必要です。Envioclick サポート（soporte.tecnico@envioclick.com）に問い合わせて取得してください。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。コンピューターで解凍してください。README.txt、OpenCart 3 用パッケージ vfd_envioclick-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ vfd_envioclick.ocmod.zip が含まれています。お使いの OpenCart バージョンのパッケージのみをインストールしてください。ライセンスキーは両バージョンで同じです。
OpenCart 3
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_envioclick-oc3-(version).ocmod.zip を選択します。本拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。インストーラーを使う代わりに、このパッケージの upload フォルダーの内容をストアのルートフォルダーにコピーすることもできます。
2. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選びます。VibeFox Envioclick を見つけて Install（緑色の + ボタン）をクリックします。
3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。
4. Edit ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。
5. API キーを入力し、API の国を選択し、User-Agent（メキシコ）、発送元の郵便番号または DANE コード、発送元住所を入力します。ストアの既定通貨が MXN または COP でない場合は、換算レートを入力します。必要に応じて、国別の固定料金と代替料金を追加します。Enable Envioclick をオンにして Save をクリックします。
OpenCart 4
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_envioclick.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変更したパッケージは動作しません。
2. パッケージは、同じページのインストール済み拡張機能の一覧に表示されます。その横の Install（緑色の + ボタン）をクリックします。
3. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選びます。VibeFox Envioclick を見つけて、Install（緑色の + ボタン）をクリックし、次に Edit（鉛筆のボタン）をクリックします。
4. OpenCart 3 の手順 4 および 5 と同じように、ライセンスキーと設定を入力します。設定ページとそのフィールドは、両バージョンで同じです。
インストール直後は、Enable Envioclick をオンにして保存するまで、この方法は無効のままです。アンインストール後に拡張機能を再インストールすると、保持されていた Envioclick の設定が再び使用されます。
設定
すべての設定は拡張機能のページにあります: Extensions > Extensions > Shipping > VibeFox Envioclick > Edit。セクションは左側に一覧表示されます。ページ下部にある Save ボタン 1 つで、ページを再読み込みせずにページ全体を保存します。保存のたびに、キャッシュされた Envioclick の見積もりも消去されます。数値フィールドでは、小数点としてピリオドとカンマのどちらも使用できます。設定の保存ができるのは、この拡張機能の変更権限を持つ管理者ユーザーだけです。
General セクションには、保存された設定ではリアルタイムの料金が機能しない場合に警告が表示されます。MXN または COP 以外のストア通貨に換算レートがない、メキシコの User-Agent がない、発送元の郵便番号または DANE コードがない、コロンビアの発送元住所がない、などです。ストアの重量または長さの単位が認識されない場合も警告されます。その場合は、System > Localisation > Weight Classes で単位 kg の重量クラスを、または System > Localisation > Length Classes で単位 cm の長さクラスを追加してください。保存時、拡張機能は次の点を確認します。Method title が 1 〜 64 文字であること、数値フィールドが負でない数値であること、Currency conversion rate が 0 より大きいこと、Minimum weight (kg) が Maximum weight (kg) を超えないこと、発送元コードがメキシコでは 5 桁、コロンビアでは 8 桁（または 5 桁の市町村コード）であること、Price per country の各行に有効な国と料金があること、Sort order が整数であること。いずれかの確認に失敗すると、何も保存されず、ページにエラーが一覧表示されます。
全般
購入者には、最安または最速の配送業者による Envioclick の料金が 1 つ表示されます。方法を Availability のジオゾーンまたは国に限定できます。
Enable Envioclick: チェックアウトで Envioclick を表示するか非表示にします。既定値: オフ。
Method title: カートとチェックアウトで購入者に表示される配送方法の名前。64 文字以内。既定値: Envioclick Shipping。必須。
Carrier in the title: リアルタイムの料金について、Envioclick の配送業者と推定配送日数をタイトルに追加します（例: "Envioclick Shipping (Estafeta Express, 1 day)"）。OpenCart はこのタイトルを注文と一緒に保存するため、注文メールや注文ページにも表示されます。配送業者は、いずれの場合も注文に保存されます。既定値: オン。
Sort order: チェックアウトの配送方法の中での Envioclick の表示順。整数。
Envioclick API（リアルタイムの料金）
任意です。API キーがない場合は、固定料金のみが使用されます。このセクションには、メキシコとコロンビアの Envioclick API ドキュメントへのリンクがあります。リアルタイムの料金は、API の国の宛先についてのみ要求されます。他の国への配送には固定料金が使用されます。
API key: Mi cuenta > Información del API にある Envioclick の API キー。"Authorization" ヘッダーで送信され、購入者に表示されたり、ログに書き込まれたりすることはありません。保存後、このフィールドは空のままになり、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。
Remove the saved API key: オンにして保存すると、保存されているキーが削除されます。その後は固定料金のみが使用されます。API key に入力されたキーは、保存されているキーを置き換えます。このスイッチは、保存後に自動的にオフになります。
API country: Envioclick アカウントの国。
User-Agent (Mexico): Envioclick サポートから発行された値（soporte.tecnico@envioclick.com）。例: EcUserAgent-2/123456。メキシコでは必須です。これがない場合、メキシコのリアルタイムの料金は要求されません。コロンビアでは任意です。
Carrier choice: Cheapest（既定値）または Fastest (then cheapest)。Envioclick は複数の配送業者から見積もりを返し、購入者は 1 つの料金を受け取ります。
Branch pickup rates: 購入者が配送業者の営業所で荷物を受け取る「Ocurre」料金も考慮します。オフの場合は、自宅配送の料金のみが使用されます。代金引換（COD）サービスは使用されません。既定値: オフ。
Currency conversion rate: Envioclick は MXN（メキシコ）または COP（コロンビア）で見積もります。ストアの既定通貨が異なる場合は、ストア通貨での 1 MXN または 1 COP の値を入力します（例: 0.05）。申告された荷物の価値も同じ方法で換算されます。ストア通貨が MXN または COP の場合は、空欄のままにしてください。換算レートがないと、別の通貨ではリアルタイムの料金は使用されません。
発送元
リアルタイムの料金に使用されます。OpenCart にはストアの郵便番号、都市、番地の情報がないため、ここで入力してください。
Origin postcode / DANE code: メキシコ: 5 桁の郵便番号。コロンビア: 市町村の 8 桁の DANE コード（例: ボゴタは 11001000）。5 桁の市町村コード（11001）は 000 を追加して補完されます。
Origin address: 集荷先住所の番地と番号。コロンビアでは必須、メキシコでは任意です。
固定料金
リアルタイムの料金がない場合に使用されます。API キーがない、配送先が API の国の外にある、API エラーが発生した、またはその区間に配送業者がない、といった場合です。
Price per country: ストアの既定通貨（税別）による、国と料金のリスト。Add country をクリックすると行が追加され、× ボタンをクリックすると行が削除されます。独自の行がないすべての国に適用される料金には、* All other countries を選択します。
Fallback cost: リアルタイムの料金がなく、表のどの行にも一致しない場合に使用されます。この場合に方法を非表示にするには、空欄のままにしてください。
Fixed price applies: Per order（既定値）は料金を 1 回だけ請求します。Per item (price × quantity) は、カート内の商品数を掛けて計算します。Envioclick のリアルタイムの料金は、常に出荷単位で計算されます。
条件
Minimum weight (kg): このカート重量未満の場合は、方法を非表示にします。0 は制限なし（既定値）を意味します。
Maximum weight (kg): このカート重量を超える場合は、方法を非表示にします。既定値: 25。0 は制限なしを意味します。
Minimum order amount: 配送が必要な商品の小計（クーポン適用後、税金適用前）がこの金額以上の場合にのみ、方法を表示します。空欄のままにすると、常に表示されます。
Free shipping from: 配送が必要な商品の小計（クーポン適用後、税金適用前）がこの金額に達すると、送料は無料になります。その場合、API へのリクエストは行われません。送料無料を提供しない場合は、空欄のままにしてください。
Tax class: 配送料の税クラス、または No tax（既定値）。Envioclick の見積もりには、配送業者の税金がすでに含まれています。そのため、配送料に税金が二重にかからないように No tax を選択してください。
提供条件
通常、この方法は選択したジオゾーン内の住所、またはすべての住所に提供されます。
Geo zone: このジオゾーン内の住所にのみ Envioclick を提供します。All zones（既定値）は制限なしを意味します。ジオゾーンは System > Localisation > Geo Zones で管理されます。Ignore shipping zones がオンのときは確認されません。
Ignore shipping zones: ジオゾーンを確認せず、下記の国のリストで判定します。既定値: オフ。
Countries: このモードの配送先の国。空欄のままにすると、すべての国が許可されます。Ignore shipping zones がオンの場合にのみ使用されます。
詳細設定
Debug log: 料金の計算と API エラーを storage/logs/vfd_evc_debug.log.php（OpenCart 4 では system/storage/logs/vfd_evc_debug.log.php）に書き込みます。このファイルは Web から読み取ることはできません。API キーと購入者の住所はログに記録されません。ログがオフの間は、API エラーを含め何も書き込まれません。作業が終わったらオフにしてください。ファイルが 5 MB に達すると、vfd_evc_debug.old.log.php に移動され、新しいログが開始されます。
Log: デバッグログのサイズと最新のエントリが表示されます。Clear log をクリックすると、ログが空になります。
Remove data on uninstall: オンの場合、拡張機能をアンインストールすると、Envioclick の設定、キャッシュされた見積もり、ログが削除されます。オフ（既定値）の場合、再インストールに備えてこれらは保持されます。注文済みの注文の Envioclick データは、常に保持されます。
インポート / エクスポート
Export: Download JSON をクリックすると、設定が JSON ファイルとして保存されます。API キーはエクスポートされません。
Import: 以前にエクスポートした JSON を貼り付けて Import をクリックすると、設定が復元されます（別のストアでの利用など）。値は通常の保存と同じように検証されます。保存済みの API キーは保持されます。
チェックアウトでの動作
OpenCart が配送方法を表示すると、拡張機能に Envioclick の料金を問い合わせます。Geo zone が設定されていて（かつ Ignore shipping zones がオフの）、住所がその外にある場合は、Envioclick は提供されません。Requires Shipping が Yes に設定されている商品のみが対象になります。その他の商品は重量に加算されず、注文金額にも含まれません。次に拡張機能は条件を確認します。Ignore shipping zones の国、カートの重量、最低注文金額です。注文金額は、配送が必要な商品の料金で、クーポン割引適用後、税金適用前の金額です。ギフト券、ポイント、ストアクレジットは考慮されません。送料無料が適用される場合、料金は 0 になり、Envioclick へのリクエストは送られません。
API キーが設定されていて、配送先が API の国にある場合、拡張機能は Envioclick に見積もりを要求します。メキシコでは、購入者が 5 桁の郵便番号を入力すると、リクエストが行われます。コロンビアでは、郵便番号欄の 8 桁の DANE コードから、または県（OpenCart の住所の地域）と都市から市町村が認識されると、リクエストが行われます。コロンビア全国で一意の都市名は、県がなくても認識されます。アクセント記号や大文字と小文字は区別されません。拡張機能は、代引きではない最安または最速の見積もりを選び、ストアの既定通貨に換算します。料金はその通貨の小数桁に丸められ、購入者の通貨で表示されます。税金は、選択した Tax class に従って含まれます。
荷物は常に 1 つの箱として扱われます。合計重量は商品の重量クラスから kg に換算され、箱のサイズは商品の寸法から cm に換算された値から求められます。寸法のない商品は 10 × 10 × 10 cm として扱われます。重量のないカートは 0.5 kg として送信されます。申告された価値は注文金額です。
同じ区間と同じ荷物の見積もりは、1 時間キャッシュされます。失敗したリクエストは 10 分間キャッシュされるため、利用できない API によってチェックアウトの更新のたびに遅くなることはありません。Envioclick がエラーを返した場合、またはその区間に配送業者がない場合、購入者にエラーは表示されません。固定料金または代替料金が使用されるか、方法が非表示になります。ログがオンの場合、その理由はデバッグログに書き込まれます。
この拡張機能は料金の計算のみを行います。送り状やラベルの作成、集荷の依頼、発送の追跡やキャンセルは行いません。配送業者の選択肢ではなく 1 つの料金を提示し、代金引換サービスや複数荷物の見積もりは使用しません。リアルタイムの見積もりは国内配送のみに対応しています。
OpenCart 4 では、チェックアウトで Envioclick を選ぶ際、チェックアウトページの配送方法のブロックで Choose をクリックし、Shipping method options ウィンドウで Envioclick を選択します。この方法は OpenCart 3 と同じように動作します。
注文
Envioclick で注文が行われると、チェックアウトで計算された料金が注文と一緒に保存され、その後変更されることはありません。Sales > Orders の注文ページには、Envioclick shipping パネルが表示されます。このパネルには、Envioclick carrier、Estimated delivery、Envioclick rate ID（リアルタイムの料金の場合）、Price source（Envioclick live rate、Fixed price per country、Fallback cost、Free shipping threshold のいずれか）、Calculated price (excl. tax) が含まれます。このパネルは、方法がオフになった後も表示されます。
OpenCart 4 では、チェックアウトで 1 つの注文を保持し、顧客が再び確定するたびにその注文を更新します。保存された料金は、チェックアウトの最新の料金に置き換えられます。顧客が別の配送方法に切り替えると、その注文についてこのパネルは表示されなくなります。管理画面での注文の変更は、保存された料金を変更しません。
Carrier in the title がオンの場合、配送業者は注文の配送方法名の一部になります。オフの場合、拡張機能が有効な間、新規注文メールと購入者のアカウントの注文ページに、リアルタイムの料金の配送業者を示す Shipping carrier: の行が追加されます。送り状は Envioclick アカウントで作成してください。固定料金で行われた注文には、Envioclick の配送業者はありません。
ライセンスキー
本拡張機能は、vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Envioclick は、Extensions > Extensions > Shipping > VibeFox Envioclick > Edit ページの設定の上にある最初のブロックです。キーを License key に貼り付け、Activate をクリックします。その後、ブロックにはキーがマスク表示された状態、ステータス（ライセンスの有効期限日や、ご利用のドメインなど）、および Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）のボタンが表示されます。その下には、Product: opencart-shipping-envioclick の行と、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 のアカウントで枠を解放してください。
有効なキーがない場合、チェックアウトで顧客に Envioclick は表示されず、料金も計算されません。同じブラウザーで管理画面にログインしている管理者ユーザーには、(unlicensed — visible to admins only) と表示された状態で、ストアにこの方法が引き続き表示されます。そのため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 では、このプレビューは利用できません。ストアは管理画面のログインを認識しないため、有効なキーがない場合、この方法は全員に対して非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると、7 日間非表示になります。既存の注文は影響を受けません。
ライセンスの期限が切れた場合も、拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスが自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは必要ありません。拡張機能をアンインストールすると、ライセンスキーとライセンスのステータスは常に削除されます。
トラブルシューティング
チェックアウトに Envioclick が表示されない: ライセンスが有効であること、Enable Envioclick がオンであることを確認してください。Geo zone（または Ignore shipping zones と Countries）、重量の制限、Minimum order amount を確認してください。リアルタイムの料金がない場合、この方法には、その国の固定料金、* All other countries の行、または Fallback cost が必要です。商品の Requires Shipping が Yes に設定されていることも確認してください。
リアルタイムの料金が表示されない: General セクションの警告を読み、次に Debug log をオンにして、チェックアウトを再読み込みし、拡張機能のページの Log フィールドを確認してください。よくある原因: 換算レートがない（ストア通貨が MXN や COP ではない）、User-Agent がない（メキシコ）、発送元の郵便番号または DANE コードがない、購入者の郵便番号（メキシコ）または都市（コロンビア）がまだ入力されていない、配送先が API の国の外にある、またはその区間に配送業者がない。
なぜ換算レートが必要なのですか？ Envioclick はメキシコペソまたはコロンビアペソでのみ料金を返します。拡張機能がペソの金額を別の通貨として表示することはありません。
コロンビア: 都市が認識されない: 購入者が住所の地域として県を選択し、市町村名を正しく入力しているか確認してください。郵便番号として入力された 8 桁の DANE コードでも機能します。
配送料に税金が二重にかかる: Envioclick の見積もりには、配送業者の税金がすでに含まれています。Tax class を No tax に設定してください。
変更後に料金が古いように見える: 拡張機能のページで Save をクリックしてください。キャッシュされた見積もりが消去されます。
ページに "Warning: You do not have permission to modify VibeFox Envioclick!" と表示される: 管理者ユーザーのグループには、設定の閲覧権限しかない可能性があります。System > Users > User Groups で、そのグループに extension/shipping/vfd_envioclick（OpenCart 3）または extension/vfd_envioclick/shipping/vfd_envioclick（OpenCart 4）の変更権限を付与してください。
開発者向け: Envioclick の見積もり API のアドレスは、設定 vfd_evc_api_url（テスト用）で置き換えられます。設定ページにはこの項目の入力欄はありません。
アンインストール
Extensions > Extensions に移動し、種類 Shipping を選んで、VibeFox Envioclick の横にある Uninstall（赤い − ボタン）をクリックします。OpenCart は常に Enable Envioclick、Sort order、Tax class、Geo zone をリセットします。キャッシュされた見積もりは、常に削除されます。Remove data on uninstall がオンの場合は、Envioclick の設定とデバッグログも削除されます。オフの場合、その他の設定は保持され、拡張機能を再インストールしたときに再び使用されます。注文済みの注文の Envioclick データは、どちらの場合も保持され、注文は配送方法と料金を保持します。
OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧で VibeFox Envioclick の横にある Uninstall（オレンジ色の − ボタン）をクリックし、次にアップロードしたパッケージを削除するため Delete（赤いごみ箱のボタン）をクリックします。
Envioclick は、それぞれの所有者の商標です。本拡張機能は Envioclick と提携しておらず、Envioclick の承認も受けていません。