VibeFox Mercado Envios for OpenCart — ヘルプ
要件
OpenCart: 3.0.x（3.0.5.0 で検証済み）または 4.0.2 以降（4.1.0.3 で検証済み）。
PHP: 8.0 以降。
Mercado Pago アカウント（リアルタイム料金の場合のみ）: リアルタイム料金は、アルゼンチン、ブラジル、またはメキシコにある Mercado Pago アカウントの Mercado Envios 計算ツールから取得されます。このアカウントで Mercado Envios が有効になっている必要があります。荷物は、そのアカウントに設定された発送元住所から見積もられます。本番用アクセストークン（APP_USR- で始まります）が必要です。Mercado Pago Developers でアプリケーションと本番用の認証情報を開いてください。ログインボタンはありません。トークンを拡張機能の設定に貼り付けます。国ごとの料金だけを使用する場合、Mercado Pago アカウントは必要ありません。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
このダウンロードは、両方の OpenCart バージョン用のパッケージが入った zip ファイル 1 つです。コンピュータで解凍してください。README.txt、OpenCart 3 用パッケージ vfd_mercado_envios-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ vfd_mercado_envios.ocmod.zip が含まれています。お使いの OpenCart のバージョンのパッケージのみをインストールしてください。ライセンスキーは両方のバージョンで同じです。
OpenCart 3
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_mercado_envios-oc3-(version).ocmod.zip を選択します。この拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。Installer を使う代わりに、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。
2. Extensions > Extensions に移動し、拡張機能の種類として Shipping を選択します。VibeFox Mercado Envios を見つけて、Install（緑色の + ボタン）をクリックします。
3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。
4. Edit ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。
5. リアルタイム料金を使用する場合は、アクセストークンを貼り付け、Mercado Envios の国を選択します。ストアの基準通貨が ARS、BRL、MXN のいずれでもない場合は、為替レートも入力します。必要に応じて Country prices と Fallback cost（リアルタイム料金がない場合に使用）を入力します。Enable Mercado Envios shipping をオンにして、Save をクリックします。
OpenCart 4
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_mercado_envios.ocmod.zip を選択します。ファイル名を変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から読み取るため、名前を変更したパッケージは動作しません。
2. パッケージは同じページのインストール済み拡張機能の一覧に表示されます。その横の Install（緑色の + ボタン）をクリックします。
3. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選択します。VibeFox Mercado Envios を見つけ、Install（緑色の + ボタン）をクリックしてから、Edit（鉛筆のボタン）をクリックします。
4. ライセンスキーと設定は、OpenCart 3 の手順 4 と 5 と同じように入力します。設定ページとその項目は両方のバージョンで同じです。
インストール後は、Enable Mercado Envios shipping をオンにして保存するまで、この配送方法はオフのままです。拡張機能をアンインストールしてから再インストールした場合、保持されていた設定が再び使用されます。
設定
すべての設定は拡張機能のページにあります：Extensions > Extensions > Shipping > VibeFox Mercado Envios > Edit。セクションは左側に一覧表示されます。Save ボタンを 1 回押すと、ページを再読み込みせずにページ全体が保存されます。保存するたびに、キャッシュされた Mercado Envios の料金と最後の API エラーも消去されます。この拡張機能の変更権限を持つ管理者ユーザーのみが設定を保存できます。
General セクションの警告（および保存のたび）には、設定の問題が表示されます。為替レートがない、アクセストークンと料金がどちらもない（その場合、この配送方法は表示されません）、最後の Mercado Envios API エラーとその日付、拡張機能が認識しないストアの重量または長さの単位（その場合、kg または cm として扱われます）などです。Name が空または 64 文字を超える場合、Exchange rate が正の数ではない場合、他の数値フィールドが 0 以上の数値ではない場合、または Min weight が Max weight より大きい場合は、ページにエラーが表示され、何も保存されません。
一般
顧客には 1 つの Mercado Envios 料金だけが表示されます。Availability で、配送方法をジオゾーンまたは国に限定できます。これらの設定はすべてのゾーンに適用されます。
Enable Mercado Envios shipping: チェックアウトで Mercado Envios を表示または非表示にします。初期値：オフ。
Name: カートとチェックアウトで顧客に表示される配送方法の名前。初期値：Mercado Envios。必須、最大 64 文字。
Tax class: 送料の税クラス、または No tax（初期値）。Mercado Envios は最終価格を提示します。No tax は提示どおりに表示します。税クラスを選ぶと、配送税が上乗せされます。
Sort order: チェックアウトの配送方法の中で Mercado Envios を表示する順序。整数です。
Mercado Envios API（リアルタイム料金）（トークンがない場合は、以下の料金のみが使用されます）
Access token: Mercado Pago の本番用アクセストークン（APP_USR-...）。api.mercadopago.com にのみ送信され、ログに記録されることはありません。保存後、フィールドは空のままとなり、Saved — leave empty to keep it. と表示されます。変更する場合のみ新しい値を入力してください。
Remove the saved access token: オンにして保存すると、保存されたトークンが削除されます。その後は、以下の料金のみが使用されます。上に入力したトークンは、代わりに保存済みのトークンを置き換えます。
Mercado Envios country: Mercado Pago アカウントの国：Argentina (ARS)（初期値）、Brazil (BRL)、または Mexico (MXN)。リアルタイム料金は、この国の宛先に対してのみ要求され、その国の通貨で提示されます。
Exchange rate: ストアの基準通貨が Mercado Envios の通貨と異なる場合にのみ必要です：1 ARS、BRL、MXN のストア基準通貨での価格（例: 0.001）。設定しないと、リアルタイム料金は使用されません。正の数でなければなりません。小数点区切りとしてピリオドとカンマの両方を使用できます。
リアルタイム料金がない場合の料金
これらの料金は、アクセストークンがない場合、宛先が Mercado Envios の国の外にある場合、API が料金を返さない場合（失敗したリクエストは 5 分後に再試行されます）に使用されます。ストアの基準通貨で、税抜きで表示されます。
Country prices: 宛先の国と料金の表。Add country をクリックすると行が追加され、削除ボタンで行を削除できます。独自の行がないすべての国には * All other countries を選択します。Price はその国の料金です。XS（1 kg まで）、S（1-2 kg）、M（2-3 kg）、L（3-5 kg）、XL（5 kg 超）の列は、そのカートの重量の場合に代わりに使用されます。空または 0 の列は Price を使用します。Price が 0 の場合は、その国への送料無料を意味します。9.99 と 9,99 はどちらも受け付けられます。数字ではない値は保存後に通知され、消去されます。どの料金もない行は、保存時に削除されます。
Fallback cost: API も Country prices も料金を提供しない場合に使用されます。その場合に配送方法を非表示にするには、空欄のままにします。
Calculation type: Per order（初期値）は、料金を 1 回だけ請求します。Per item (each item priced by its own weight x quantity) は、各商品の重量に対応する料金を Country prices（または Fallback cost）から探し、数量を掛けます。1 つの商品に料金が設定されない場合、この配送方法は非表示になります。Mercado Envios のリアルタイム料金は、常に荷物全体に対するものです。
利用可能条件
Min weight (kg): この配送方法が表示されるためのカートの最小重量。0 は制限なし（初期値）を意味します。
Max weight (kg): カートがこれより重い場合は、配送方法を非表示にします。初期値：25。空欄は 25 kg、0 は制限なしを意味します。
Minimum subtotal: 配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額以上の場合にのみ、配送方法を表示します。常に表示する場合は空欄にします。
Geo zone: このジオゾーン内の住所に対してのみ Mercado Envios を提供します。All zones（初期値）は制限なしを意味します。Ignore shipping zones がオンの場合、ジオゾーンはチェックされません。ジオゾーンは System > Localisation > Geo Zones で管理されます。
Ignore shipping zones: 選択されたジオゾーンに関係なく、下に記載された国でこの配送方法を提供します。
Countries: このモードの宛先の国。ストアで有効なすべての国の場合は空欄にします。このフィールドは Ignore shipping zones がオンの場合にのみ使用されます。
送料無料
Free shipping from: 配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額に達すると、この配送方法は無料になります。その場合、API リクエストは行われません。無効にする場合は空欄にします。
詳細設定
Debug log: API リクエストと料金計算を storage/logs/vfd_mrcv_debug.log.php（OpenCart 4 では system/storage/logs/vfd_mrcv_debug.log.php）に書き込みます。このファイルは Web から読み取ることはできません。このオプションがオフでも、エラーは常に記録されます。アクセストークンと顧客の住所は記録されません。ファイルが 5 MB に達すると、vfd_mrcv_debug.old.log.php に移動され、新しいログが開始されます。
Log: デバッグログのサイズと最新のエントリを表示します。Clear log をクリックすると消去されます。
Remove data on uninstall: オンの場合、拡張機能をアンインストールすると、設定とログが削除されます。オフ（初期値）の場合は、再インストール用に保持されます。キャッシュされた料金は常に削除されます。注文済みの Mercado Envios のデータは、注文履歴として常に保持されます。
インポート / エクスポート
Export: Download JSON をクリックすると、設定が JSON ファイルとして保存されます。アクセストークンはエクスポートされません。
Import: 以前にエクスポートした JSON を貼り付け、Import をクリックすると、設定が復元されます（例: 別のストアで）。値は通常の保存と同じように検証されます。保存済みのアクセストークンは保持されます。
チェックアウトでの動作
OpenCart が配送方法を表示するとき、拡張機能に Mercado Envios の料金を問い合わせます。Geo zone が設定されていて、住所がその外にある場合、Mercado Envios は提供されません（Ignore shipping zones がオンの場合を除きます。その場合は Countries が判断します）。Requires Shipping が Yes に設定された商品のみが対象です。それ以外の商品は重量を加えず、小計にも含まれません。次に、拡張機能はカートの重量と最低小計を確認します。小計は、配送が必要な商品の価格で、クーポン割引適用後、税抜きです。ギフト券、ポイント、ストアクレジットは考慮されません。送料無料が適用される場合、料金は 0 になり、Mercado Envios へのリクエストは送信されません。
Mercado Envios の国内で、有効な郵便番号がある宛先（アルゼンチンは 4 桁。C1425ABC などの CPA も可。ブラジルは 8 桁、メキシコは 5 桁）の場合、拡張機能はカートを 1 つの荷物として扱います。商品の最大の幅と長さ、すべての商品の高さの合計、グラム単位の合計重量です。商品の重量と寸法は、OpenCart の重量と長さのクラスから変換されます。各辺と重量は、その国の Mercado Envios の最小値まで引き上げられるため、寸法や重量がない商品でも料金が取得できます。カートの金額は、Mercado Envios の通貨で商品価格として送信されます。Mercado Envios が返した最も安いオプションは、ストアの基準通貨に換算され、小数点以下の桁数に丸められ、選択された Tax class の税金を加えた上で、顧客の通貨で表示されます。
各見積もりは最大 1 時間キャッシュされます（OpenCart のキャッシュ期間を超えません）。そのため、同じカートでは新しいリクエストは発生しません。失敗した見積もりは 5 分間繰り返されません。Mercado Pago に接続できない、トークンを拒否する、リクエストを制限する、または別の通貨で応答する場合、すべてのリアルタイム見積もりは 5 分間一時停止されます。これにより、チェックアウトが更新のたびに API を待つことはありません。API のタイムアウトは 10 秒です。
トークンがない場合、宛先が Mercado Envios の国の外にある場合、郵便番号が欠落しているか無効な場合、為替レートがない場合、荷物がその国の Mercado Envios の上限（アルゼンチンでは 25 kg、ブラジルでは 15 kg、メキシコでは 30 kg）より重い場合、または Mercado Envios がその住所に対してエラーまたはオプションなしを返す場合は、リアルタイム料金のない料金が代わりに使用されます。その国の行（または * の行）が使用され、なければフォールバック料金が使用されます。料金がない場合、配送方法は非表示になります。顧客に API エラーが表示されることはありません。
OpenCart 4 では、購入者はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options のウィンドウで Mercado Envios を選択します。この方法の動作は OpenCart 3 と同じです。
この拡張機能は料金のみを計算します。配送の作成、ラベルの印刷、荷物の追跡は行いません。配送は、お使いの Mercado Libre または Mercado Pago アカウントで作成してください。すべてのオプションから選択するのではなく、最も安い Mercado Envios のオプションである 1 つの料金を表示し、受け取り場所（代理店）の選択機能はありません。
注文
Mercado Envios のリアルタイム料金で注文が行われると、拡張機能はサービス名、日数で表した推定配達時間、リアルタイム料金を保存します。Sales > Orders では、注文ページに Mercado Envios のブロックが表示され、Mercado Envios service、Estimated delivery、Live rate (excl. tax) が含まれます。このブロックは、後で配送方法が無効になっても表示されます。登録済みの顧客は、アカウントの注文ページで配送方法の下に Mercado Envios service と Estimated delivery を確認でき、同じ行が新規注文メールにも追加されます。テーブル料金またはフォールバック料金で行われた注文にはサービス情報がありません。既存の注文は、その後の料金変更の影響を受けません。
OpenCart 4 では、Mercado Envios ブロックは History の上に表示されます。OpenCart 4 は、チェックアウトごとに注文を 1 つ保持し、購入者が再度確定するたびにその注文を更新します。保存されたサービスもそれに合わせて更新され、購入者が別の配送方法に切り替えた場合、または注文がテーブル料金またはフォールバック料金になった場合は削除されます。
ライセンスキー
この拡張機能は、vibefox.net の VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Mercado Envios は、Extensions > Extensions > Shipping > VibeFox Mercado Envios > Edit ページで設定より上にある最初のブロックです。License key にキーを入力し、Activate をクリックしてください。その後ブロックには、キーがマスクされた状態、ステータス（ライセンスの有効期限日や使用中のドメインなど）、および次のボタンが表示されます：Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）。その下に Product: opencart-shipping-mercado-envios の行と、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 アカウントで枠を解放してください。
有効なキーがない場合、Mercado Envios はチェックアウトで購入者に表示されず、料金も計算されません。同じブラウザで管理画面にログインしている管理者ユーザーには、ストアでこの配送方法が (unlicensed — visible to admins only) と表示された状態で引き続き見えるため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 ではこのプレビューは利用できません。ストアは管理画面のログインを認識しないため、有効なキーがない場合は全員にこの方法が非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると 7 日間非表示になります。既存の注文は影響を受けません。
ライセンスの期限が切れても、拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスが自動的に再確認されます。キーの入力後最初の 14 日間は 1 日に 1 回、その後は 1 週間に 1 回です。cron ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスのステータスは常に削除されます。
トラブルシューティング
Mercado Envios がチェックアウトに表示されない: ライセンスが有効であること、Enable Mercado Envios shipping がオンであることを確認してください。Geo zone を確認するか、Ignore shipping zones をオンにして Countries を確認してください。拡張機能のページの警告、重量制限、Minimum subtotal を確認してください。この配送方法には料金が必要です：Mercado Envios の国の住所に対して有効なアクセストークン、または Country prices もしくは Fallback cost。商品の Requires Shipping が Yes に設定されていることを確認してください。
リアルタイム料金が表示されない: Debug log をオンにし、チェックアウトを再読み込みして、拡張機能のページの Log フィールドを確認してください。よくある理由：トークンがない、宛先が Mercado Envios の国の外にある、郵便番号が欠落または無効、Exchange rate がない、荷物が重量制限を超えている、または住所に対する Mercado Envios のオプションがない。
警告に HTTP 401 または 403 が表示される: アクセストークンが無効か、期限切れです。Mercado Pago Developers から本番用の Access Token を再度コピーしてください。
Mercado Envios が別の通貨で応答した: アカウントの国が Mercado Envios country と一致しません。Mercado Pago アカウントの国を選択してください。
料金の通貨: Country prices、Fallback cost、および上限値は、ストアの基準通貨で指定されます。リアルタイム料金は、Mercado Pago アカウントの通貨で返され、ストアが別の基準通貨を使用している場合は Exchange rate で換算されます。
変更後に料金が古いように見える: 拡張機能のページで Save をクリックしてください。キャッシュされた料金が消去されます。
ページに "Warning: You do not have permission to modify VibeFox Mercado Envios!" と表示される: 管理者のユーザーグループは、設定を表示のみできる可能性があります。System > Users > User Groups で、そのグループに extension/shipping/vfd_mercado_envios（OpenCart 3）または extension/vfd_mercado_envios/shipping/vfd_mercado_envios（OpenCart 4）の変更権限を付与してください。
開発者向け: Mercado Envios API のアドレスは、設定 vfd_mrcv_api_url（テスト用）で置き換えられます。設定ページにはこの項目はありません。
アンインストール
Extensions > Extensions に移動し、種類 Shipping を選んで、VibeFox Mercado Envios の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは常に削除されます。OpenCart は常に Enable Mercado Envios shipping、Sort order、Tax class、Geo zone をリセットします。キャッシュされた料金と最後の API エラーは常に削除されます。Remove data on uninstall がオンの場合、その他の設定とデバッグログも削除されます。オフの場合は保持され、拡張機能を再インストールしたときに再び使用されます。注文済みの Mercado Envios のデータは常に保持され、既存の注文は配送方法と料金を保持します。
OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧で VibeFox Mercado Envios の横にある Uninstall（オレンジ色の − ボタン）をクリックしてから、アップロードしたパッケージを削除するために Delete（赤いゴミ箱ボタン）をクリックしてください。
Mercado Envios と Mercado Pago は、それぞれの所有者の商標です。この拡張機能は、Mercado Envios または Mercado Pago と提携しておらず、これらによる推奨も受けていません。