VibeFox Melhor Envio for OpenCart — ヘルプ
要件
OpenCart: 3.0.x（3.0.5.0 で検証済み）または 4.0.2 以降（4.1.0.3 で検証済み）。
PHP: 8.0 以降。
Melhor Envio アカウント（リアルタイム見積もりの場合のみ）: リアルタイム見積もりにはアクセストークンが必要です。Melhor Envio アカウントでトークンのページ（melhorenvio.com.br/painel/gerenciar/tokens）を開き、「shipping-calculate」権限を持つトークンを生成してください。テストの場合は、Melhor Envio のサンドボックス（sandbox.melhorenvio.com.br）でトークンを生成します。本番用とサンドボックス用のトークンは別物です。「接続」ボタンはありません。トークンを拡張機能の設定に貼り付けます。トークンがない場合、この配送方法は予備の料金を使用します。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
このダウンロードは、両方の OpenCart バージョン用のパッケージが入った zip ファイル 1 つです。コンピュータで解凍してください。README.txt、OpenCart 3 用パッケージ vfd_melhor_envio-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ vfd_melhor_envio.ocmod.zip が含まれています。お使いの OpenCart のバージョンのパッケージのみをインストールしてください。ライセンスキーは両方のバージョンで同じです。
OpenCart 3
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_melhor_envio-oc3-(version).ocmod.zip を選択します。本拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。Installer を使う代わりに、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。
2. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選択します。VibeFox Melhor Envio を見つけて Install（緑色の + ボタン）をクリックします。
3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。
4. Edit ページ上部のライセンスブロックで、VibeFox ライセンスキーを License key に貼り付け、Activate をクリックします（ライセンスキーを参照）。
5. アクセストークン、連絡先メールアドレス、発送元の CEP を貼り付けます。ストアの既定通貨が BRL でない場合は、BRL exchange rate を設定します。必要に応じて、予備の料金表（例: ブラジル向け）または予備の費用を入力します。Enable Melhor Envio shipping をオンにして Save をクリックします。
OpenCart 4
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_melhor_envio.ocmod.zip を選択します。ファイル名を変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から読み取るため、名前を変更したパッケージは動作しません。
2. パッケージは同じページのインストール済み拡張機能の一覧に表示されます。その横の Install（緑色の + ボタン）をクリックします。
3. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選択します。VibeFox Melhor Envio を見つけ、Install（緑色の + ボタン）をクリックしてから、Edit（鉛筆のボタン）をクリックします。
4. ライセンスキーと設定は、OpenCart 3 の手順 4 と 5 と同じように入力します。設定ページとその項目は両方のバージョンで同じです。
インストール後は、Enable Melhor Envio shipping をオンにして保存するまで、この配送方法はオフのままです。アンインストール後に再インストールした場合は、保持されていた設定が再び使用されます。
設定
すべての設定は拡張機能のページにあります：Extensions > Extensions > Shipping > VibeFox Melhor Envio > Edit。セクションは左側に並んでいます。Save ボタンを押すと、ページ全体を再読み込みせずに保存できます。保存するたびに、キャッシュされた Melhor Envio の見積もりと最後の API エラーも消去されます。本拡張機能の変更権限を持つ管理者ユーザーのみが設定を保存できます。
ページ上部（および保存のたび）の警告には、設定が不完全な箇所が表示されます。発送元の CEP が空または 8 桁でない、連絡先メールアドレスがない、BRL の為替レートがない、トークンも予備の料金もない（その場合、この配送方法は表示されません）、トークン保存時の最後の Melhor Envio API エラーとその日付、または重量クラスの単位「kg」や長さクラスの単位「cm」がないストア（その場合は単位の名前で換算され、不明な単位は kg または cm として扱われます）。Name が空、長すぎる、または < > ; = # { } のいずれかの文字を含む場合、数値フィールドに 0 以上の数値以外が入力されている場合、Min weight が Max weight より大きい場合、Default product size が「縦 x 横 x 高さ」の形式でない場合は、ページにエラーが表示され、何も保存されません。
一般
設定はすべてのジオゾーンに適用されます。Availability でこの方法を特定のジオゾーンに限定できます。料金は常に本拡張機能から取得されます。
Enable Melhor Envio shipping: チェックアウトで Melhor Envio を表示または非表示にします。既定値: off。
Name: カートとチェックアウトで購入者に表示される配送方法の名前。既定値: Melhor Envio。必須、最大 64 文字。
Sort order: チェックアウトの配送方法の中での Melhor Envio の順序。整数。
Melhor Envio API
Access token: 下で選択した環境のトークン。Bearer トークンとして Melhor Envio に送信されます。保存後、この欄は空になり、A token is saved — leave empty to keep it. と表示されます。変更する場合にのみ新しいトークンを入力してください。保存済みのトークンを削除するには、Remove the saved token にチェックを入れて保存します。トークンがログに書き込まれることはありません。
Sandbox: テストには Melhor Envio のサンドボックス（sandbox.melhorenvio.com.br）を使用します。その場合はサンドボックス用のトークンを使ってください。既定値: off。
Contact e-mail: 技術的な連絡先のメールアドレス。すべてのリクエストの User-Agent ヘッダーで Melhor Envio に送信されます（例: tech@example.com）。Melhor Envio はすべての連携でこの情報を必要とします。無効なアドレスは保存されず、その旨の通知が表示されます。
Origin CEP: 荷物を発送する場所の CEP（8 桁）。例: 01310-100。OpenCart にはストアの郵便番号がないため、リアルタイム見積もりにはこの項目が必要です。8 桁でない CEP は、通知付きで保存されますが、見積もりは要求されません。
Services: 見積もりの対象とする Melhor Envio のサービス ID（任意、カンマ区切り）。例: 1 = Correios PAC、2 = Correios SEDEX、17 = Correios Mini Envios、3 = Jadlog .Package、4 = Jadlog .Com。空欄にすると、アカウントのすべてのサービスの見積もりを取得します。
Quotes at checkout: 見積もりの表示方法。
Delivery time: 名前の横に Melhor Envio の配送目安を表示します（例: 「(3-5 business days)」）。既定値: on。
Declared value: 見積もりで商品の価額（保険）を申告します。オフの場合、申告価額なしで見積もられます。料金は安くなりますが、荷物は保険の対象になりません。既定値: on。
BRL exchange rate: Melhor Envio はブラジルレアルで見積もります。ストアの既定通貨が BRL でない場合にのみ必要です。既定通貨で 1 BRL の価格を入力します（例: 0.17）。設定しない場合、リアルタイム見積もりは使用されません。値は 0 より大きい必要があります。申告価額も同じレートで BRL に換算されます。既定通貨が BRL の場合、この欄には Melhor Envio の料金がそのまま使われることが表示されます。
Default product weight (kg): 重量のない商品に使用されます。見積もりと重量制限の両方で使われます。0 より大きい必要があります。既定値: 0.3。
Default product size (cm): 縦 x 横 x 高さ。寸法のない商品に使用されます。既定値: 16x11x5。
予備の料金（ストアの既定通貨で）
予備の料金は、トークンがない場合、配送先の CEP がない場合、または API が見積もりを返さない場合（エラー、タイムアウト、対象外）に使用されます。
Fallback price table: 国とカートの重量ごとの料金（税抜き）。Add country をクリックすると行が追加され（新しい行は「ブラジル」から始まります）、削除ボタンで行を削除できます。独自の行がない国には * Any country を選択します。各行には 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」のどちらも使用できます。数値でない値は保存後に通知され、無視されます。料金が 1 つもない行は削除されます。
Fallback cost: 表にも料金がない場合に使用されます。その場合にこの配送方法を非表示にするには、空欄のままにします。
Fallback calculation: Per order（既定値）は予備の料金を 1 回だけ請求します。Per item (each item priced by its own weight x quantity) は、各商品の重量（重量がない場合は既定の重量）に対応する予備の料金を検索し、数量を掛けます。これは予備の料金にのみ適用されます。Melhor Envio の見積もりにはすべての商品が既に含まれています。
利用可否
Min weight (kg): カートの重量がこれより軽い場合は、この方法を非表示にします。0 は制限なし（既定値）を意味します。
Max weight (kg): カートの重量がこれより重い場合は、この方法を非表示にします。既定値: 30。0 は制限なしを意味します。空欄の場合は 30 kg、または Ignore shipping zones がオンのときは制限なしになります。
Minimum subtotal: カートの小計（配送が必要な商品、クーポン適用後、税抜き）がこの金額以上の場合にのみ、この方法を表示します。空欄にすると常に表示されます。
Free shipping from: この金額以上のカート小計で配送料が無料になります。サービスごとに 1 つのオプションを使う場合、無料になるのは最安のサービスのみです。より速いサービスは料金がそのままです。空欄にすると無効になります。
Tax class: 配送料に加算される税クラス、または No tax（既定値）。Melhor Envio の料金は配送業者の最終料金です。OpenCart でこれに税金を加えたくない場合は No tax を選択してください。
Geo zone: このジオゾーン内の住所に対してのみ Melhor Envio を提供します。All zones（既定値）は制限なしを意味します。ジオゾーンは System > Localisation > Geo Zones で管理します。Ignore shipping zones がオンの場合、ジオゾーンは確認されません。
配送ゾーンを使わない場合の利用可否
通常、この方法は Availability で選択したジオゾーン内で提供されます（何も選択されていない場合はすべてのゾーン）。
Ignore shipping zones: 選択したジオゾーンに関係なく、下に記載した国に対してこの方法を提供します。このモードではジオゾーンは確認されません。
Countries: このモードでの配送先の国。すべての国を対象にする場合は空欄にします。この項目は Ignore shipping zones がオンの場合にのみ使用されます。
詳細設定
Debug log: API のリクエストと料金計算を storage/logs/vfd_menv_debug.log.php（OpenCart 4 では system/storage/logs/vfd_menv_debug.log.php）に書き込みます。このファイルはウェブから読み取ることはできません。この設定がオフでも、API エラーは常に記録されます。トークンは決して記録されず、購入者の CEP は先頭 5 桁に省略されます。ファイルが 5 MB に達すると、vfd_menv_debug.old.log.php に移動され、新しいログが開始されます。
Log: デバッグログのサイズと最新のエントリを表示します。Clear log をクリックすると空になります。
Remove data on uninstall: オンの場合、拡張機能をアンインストールすると、すべての拡張機能の設定とログが削除されます。オフ（既定値）の場合、再インストール用に保持されます。見積もりのキャッシュは常に削除されます。注文とともに保存されたサービスは注文履歴の一部であるため、保持されます。
インポート / エクスポート
Export: Download JSON をクリックすると、設定が JSON ファイルとして保存されます。アクセストークンはエクスポートされません。
Import: 以前にエクスポートした JSON を貼り付けて Import をクリックすると、設定が復元されます。たとえば別のストアで使用できます。値は通常の保存時と同様に検証されます。保存済みのアクセストークンは保持されます。
チェックアウトでの動作
OpenCart は配送方法を表示する際、拡張機能に Melhor Envio の料金を問い合わせます。Geo zone が設定されていて住所がその範囲外の場合、Melhor Envio は提供されません。Ignore shipping zones を使用すると、ジオゾーンは確認されません。この場合、Melhor Envio は国が Countries に含まれている場合（または Countries が空の場合）にのみ提供されます。Requires Shipping が Yes に設定されている商品のみが対象です。その他の商品は重量を加算せず、小計にも含まれません。その後、拡張機能はカートの重量と最低小計を確認します。
8 桁の CEP を持つブラジルの配送先住所の場合、拡張機能は発送元と配送先の CEP、および配送可能な各商品の重量、寸法、数量、申告価額を Melhor Envio に送信します。サービスリストを設定している場合は、そのリストも送信されます。商品の Model は商品 ID として送信されます。エラーのあるサービスや料金のないサービスはスキップされます。見積もりは既定通貨に換算され、その小数桁数に丸められ、料金順に並べられ、選択された Tax class の税金を含めて購入者の通貨で表示されます。送料無料が適用される場合、最安のサービスは 0 になります。
One option - the cheapest service の場合、購入者には 1 つのオプションが表示されます（例: Melhor Envio (6-7 business days)）。One option per service の場合、サービスごとに 1 つのオプションが表示されます（例: Melhor Envio: Correios SEDEX (1-2 business days)）。配送目安は Delivery time がオンのときにのみ追加されます。
各見積もりは 1 時間キャッシュされるため、同じカートで新たなリクエストが発生することはありません。失敗した呼び出しは 5 分間記憶されるため、API の障害によってチェックアウトの更新のたびに遅くなることはありません。API のタイムアウトは 12 秒です。
トークンがない場合、住所がブラジル以外の場合、または有効な CEP がまだない場合、BRL の為替レートがない場合、または Melhor Envio がエラーを返すか、そのルートにサービスがない場合は、予備の料金が使用されます。国の行（国に行がない場合は * の行）、なければ予備の費用です。このようなオプションは、Name に設定された名前のみで呼ばれます。送料無料が適用される場合、料金がなくても無料として表示されます。料金が全くない場合、この方法は非表示になります。購入者が API エラーを見ることはありません。理由はログに記録されます。
OpenCart 4 では、購入者はチェックアウトの配送方法ブロックで Choose をクリックし、Shipping method options のウィンドウで Melhor Envio のオプションを選択します。オプションと料金は OpenCart 3 と同じです。
本拡張機能は料金の計算のみを行います。送り状（ラベル）の購入や作成、Melhor Envio のカートへの配送の追加、荷物の追跡、集荷の手配、請求書（NF-e）データの送信は行いません。配送業者の営業所（持ち込み場所）の選択機能もありません。発送は Melhor Envio の管理画面で行ってください。Melhor Envio はブラジル国内のみに配送します。その他の国には予備の料金のみが適用されます。
注文
OpenCart は、選択したオプションの名前を注文の配送方法として保存するため、サービスと配送目安は注文確認メール、購入者のアカウント、および Sales > Orders に表示されます。
リアルタイム見積もりで注文が行われた場合、本拡張機能は、購入者が配送の手順で見た Melhor Envio のサービスを、新たなリクエストなしで保存します。Sales > Orders の管理画面の注文ページには、Melhor Envio ブロックが表示されます。これには Melhor Envio service、Service ID、Delivery estimate が含まれ、Melhor Envio でどのサービスを購入すべきかがわかります。購入者はアカウントの注文ページで Melhor Envio service と Delivery estimate を確認できます。予備の料金で行われた注文にはサービスはありません。既存の注文は影響を受けません。
OpenCart 4 では、Melhor Envio ブロックは History の上に表示されます。OpenCart 4 は、チェックアウトごとに注文を 1 つ保持し、購入者が再度確定するたびにその注文を更新します。保存されたサービスもそれに合わせて更新され、購入者が別の配送方法に切り替えた場合、または注文が予備の料金になった場合は削除されます。
ライセンスキー
本拡張機能は、vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Melhor Envio は、Extensions > Extensions > Shipping > VibeFox Melhor Envio > Edit ページで設定の上にある最初のブロックです。キーを License key に貼り付けて Activate をクリックします。その後、ブロックにはキーがマスクされた状態で表示され、ステータス（ライセンスの有効期限日やドメインなど）と、ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key のボタンが表示されます。その下には Product: opencart-shipping-melhor-envio の行と、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 のアカウントで枠を解放してください。
有効なキーがない場合、Melhor Envio はチェックアウトで購入者に表示されず、料金も計算されません。同じブラウザで管理画面にログインしている管理者ユーザーには、ストアでこの配送方法が (unlicensed — visible to admins only) と表示された状態で引き続き見えるため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 ではこのプレビューは利用できません。ストアは管理画面のログインを認識しないため、有効なキーがない場合は全員にこの方法が非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると 7 日間非表示になります。既存の注文は影響を受けません。
ライセンスの期限が切れても、拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスが自動的に再確認されます。キーの入力後最初の 14 日間は 1 日に 1 回、その後は 1 週間に 1 回です。cron ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスのステータスは常に削除されます。
トラブルシューティング
チェックアウトに Melhor Envio が表示されない: ライセンスが有効であること、Enable Melhor Envio shipping がオンであることを確認してください。Geo zone を確認するか、Ignore shipping zones をオンにして Countries を確認してください。拡張機能のページ上部の警告、重量制限、Minimum subtotal を確認してください。トークンや見積もりがない場合、この方法には予備の料金が必要です。Fallback price table の行、または Fallback cost を設定してください。商品の Requires Shipping が Yes に設定されていることも確認してください。
予備の料金だけが表示される: Debug log をオンにし、チェックアウトを再読み込みして、拡張機能のページの Log フィールドを確認してください。よくある理由: トークンがない、発送元の CEP が 8 桁でない、既定通貨が BRL 以外なのに BRL exchange rate がない、配送先の CEP がまだない、またはそのルートをカバーするサービスがない。
ログまたは警告に HTTP 401 または 403 が表示される: Melhor Envio がアクセストークンを拒否しました。トークンが間違っているか、期限切れか、取り消されているか、別の環境のものです。新しいトークンを生成し、Sandbox の設定がそれと一致しているか確認してください。
Melhor Envio の料金に税金が加算される: Tax class を No tax に設定してください。
変更後に見積もりが古いように見える: 拡張機能のページで Save をクリックしてください。キャッシュされた見積もりが消去されます。
ページに "Warning: You do not have permission to modify VibeFox Melhor Envio!" と表示される: 管理者のユーザーグループは設定の閲覧のみ可能です。System > Users > User Groups で、そのグループに extension/shipping/vfd_melhor_envio（OpenCart 3）または extension/vfd_melhor_envio/shipping/vfd_melhor_envio（OpenCart 4）の変更権限を付与してください。
開発者向け: Melhor Envio の見積もり API のアドレスは、設定 vfd_menv_api_url（テスト用）で置き換えることができます。この設定には設定ページに入力欄はありません。
アンインストール
Extensions > Extensions に移動し、種類 Shipping を選んで、VibeFox Melhor Envio の横にある Uninstall（赤い − ボタン）をクリックします。本拡張機能のライセンスキーとライセンスのステータスは常に削除されます。OpenCart は Enable Melhor Envio shipping、Sort order、Tax class、Geo zone を常にリセットします。見積もりのキャッシュは常に削除されます。Remove data on uninstall がオンの場合は、その他の設定とデバッグログも削除されます。オフの場合、それらは保持され、拡張機能を再インストールしたときに再び使用されます。注文とともに保存されたサービスは常に保持され、既存の注文は配送方法と料金を保持します。
OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧で VibeFox Melhor Envio の横にある Uninstall（オレンジ色の − ボタン）をクリックしてから、アップロードしたパッケージを削除するために Delete（赤いゴミ箱ボタン）をクリックしてください。
Melhor Envio は各所有者の商標です。本拡張機能は Melhor Envio との提携や承認を受けたものではありません。