VibeFox Melhor Envio for PrestaShop — ヘルプ
要件
PrestaShop: 8.0 から 9.x。
PHP: 8.0 以降。モジュールは古い PHP バージョンへのインストールを拒否します。
Melhor Envio アカウント（リアルタイム見積もりのみ）：リアルタイム見積もりにはアクセストークンが必要です。Melhor Envio アカウントでトークンのページ（melhorenvio.com.br/painel/gerenciar/tokens）を開き、「shipping-calculate」権限を付けてトークンを生成してください。テストの場合は、Melhor Envio のサンドボックス（sandbox.melhorenvio.com.br/painel/gerenciar/tokens）でトークンを生成します。本番用とサンドボックス用のトークンは別物です。「接続」ボタンはありません。トークンをモジュールの設定に貼り付けます。トークンがない場合、配送業者はフォールバック料金を使用します。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインでのみ有効です。
インストール
1. 管理画面で Modules > Module Manager に進み、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックします。後でモジュール一覧から VibeFox Melhor Envio を見つけて、Configure をクリックすることもできます。
3. Configure ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを貼り付け、Activate をクリックします（ライセンスキーを参照）。
4. アクセストークン、連絡先メールアドレス、発送元の CEP を貼り付けます。ショップの既定通貨が BRL でない場合は、BRL exchange rate を設定します。必要に応じて、フォールバック料金表（例：ブラジル向け）またはフォールバック送料を入力します。Save をクリックします。
インストール時に、モジュールは配送日数のテキスト Delivery by the carriers of your Melhor Envio account を持つ Melhor Envio 配送業者を作成します。配送業者はすべてのゾーンとすべての顧客グループに割り当てられます。ゾーン、顧客グループ、配送日数、ロゴ、サイズ制限は Shipping > Carriers で変更できます。料金はそこでは設定しないでください。料金は常にモジュールから取得されます。
設定
すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Melhor Envio > Configure。設定は配送業者のすべてのゾーンに適用されます。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。保存するたびに、キャッシュされた Melhor Envio の見積もりと直近の API エラーも消去されます。
ページ上部の警告は、設定の不備を示します：発送元 CEP が空である、または 8 桁ではない、連絡先メールアドレスがない、BRL 為替レートがない、日付付きの直近の Melhor Envio API エラーがある、トークンがない、フォールバック料金がない（この場合、配送業者は決して表示されません）、またはショップの重量・寸法単位がモジュールで認識できない（この場合、kg または cm として扱われます）。数値欄に 0 以上の数値以外が入力されている場合、Min weight が Max weight より大きい場合、または Default product size が縦 x 横 x 高さの形式になっていない場合、ページにエラーが表示され、何も保存されません。
General
Enable Melhor Envio shipping: 配送業者のオン・オフを切り替えます。Shipping > Carriers の配送業者のステータスと同じスイッチです。
Name: チェックアウトで購入者に表示される配送業者の名称です。既定値：Melhor Envio。必須、最大 64 文字。
Tax: 配送業者の税ルール、または No tax です。Melhor Envio の料金は配送業者の最終料金です。PrestaShop がこれらの料金に税を加算しないようにする場合は、No tax を選択します。
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）を使用します。サンドボックス用のトークンと併用してください。既定値：オフ。
Contact e-mail: 技術的な連絡先メールアドレスです。すべてのリクエストの User-Agent ヘッダーで Melhor Envio に送信されます。Melhor Envio はすべての連携でこれを必要とします。無効なアドレスは保存されず、その旨の通知が表示されます。
Origin CEP: 荷物を発送する元の CEP（8 桁）です。例：01310-100。00000-000 の形式で保存されます。有効な発送元 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」）。既定値：オン。
Declared value: 見積もりで商品の価値（保険）を申告します。オフの場合、申告金額なしで見積もりが行われます。料金は安くなりますが、荷物は保険対象になりません。既定値：オン。
BRL exchange rate: Melhor Envio はブラジル・レアル（BRL）で見積もります。ショップの既定通貨が BRL でない場合にのみ必要です。1 BRL の既定通貨での価格を入力します（例：0.17）。設定しない場合、リアルタイム見積もりは使用されません。値は 0 より大きくなければなりません。申告金額も同じレートで BRL に換算されます。既定通貨が BRL の場合、この欄には Store currency is BRL と表示されます。
Default product weight: 重量が設定されていない商品に使用されます（単位は kg）。見積もりと重量制限の両方に使われます。0 より大きくなければなりません。既定値：0.3。
Default product size: 寸法が設定されていない商品に使用されます（縦 x 横 x 高さ、単位は cm）。既定値：16x11x5。
フォールバック料金（ショップの既定通貨）
フォールバック料金は、トークンがない、配送先の CEP がない、または API が見積もりを返さない（エラー、タイムアウト、対象外の地域）場合に使用されます。
Fallback price table: 国別およびカートの重量別の料金です。Add country をクリックして行を追加し、ゴミ箱のアイコンをクリックして行を削除します。独自の行がない国には、国として * Default を選択します。各行には Price と重量の列があります：XS は 1 kg まで、S は 1-2 kg、M は 2-3 kg、L は 3-5 kg、XL は 5 kg を超える場合です。空欄または 0 の列では Price が使用されます。「9.99」と「9,99」のどちらも受け付けられます。数値ではない値は、保存後に報告され、無視されます。
Fallback cost: 表にも料金がない場合に使用されます。その場合に配送業者を非表示にするには、空欄のままにします。
Fallback calculation: Per order は、フォールバック料金を 1 回だけ請求します。Per item (each item priced by its own weight x quantity) は、各商品の重量（重量がない場合は既定の重量）に対応するフォールバック料金を検索し、数量を掛けます。1 つの商品に料金がない場合、配送業者は非表示になります。これはフォールバック料金にのみ適用されます。Melhor Envio の見積もりには、すでにすべての商品が含まれています。
利用条件
Min weight: カートの重量がこれより軽い場合、配送業者を非表示にします（単位は kg）。0 は制限なしを意味します。
Max weight: カートの重量がこれより重い場合、配送業者を非表示にします（単位は kg）。既定値：30。0 は制限なしを意味します。空欄の場合、配送業者のゾーンでは 30 kg となり、それ以外のゾーン（Ignore shipping zones の国のうち、これらのゾーンの外にあるもの）でのみ制限なしとなります。
Minimum subtotal: カートの小計（配送が必要な商品、割引後、税抜き）がこの金額以上の場合にのみ、配送業者を表示します。空欄にすると、常に表示されます。
Free shipping from: この金額以上のカート小計で送料が無料になります。サービスごとに 1 つのオプションを使用している場合、無料になるのは最も安いサービスのみです。より速いサービスは元の料金のままです。空欄にすると無効になります。
Ignore shipping zones: 配送業者がそのゾーンに割り当てられていなくても、下に指定した国で配送業者を提供します。オンの間、配送業者は無効なゾーンや後から作成されたゾーンを含むすべてのゾーンに関連付けられます。オフにすると、配送業者は自身のゾーンを取り戻します。
Countries: そのモードの配送先の国です。空欄にするとすべての国が対象になります。この欄は Ignore shipping zones がオンの場合にのみ使用されます。
詳細設定
Debug log: API のリクエストと料金計算を、モジュールのフォルダ内の logs/vfd_menv_debug.log.php に書き込みます。このファイルは Web からは開けません。このオプションがオフでも、エラーは常に記録されます。トークンがログに記録されることはなく、購入者の CEP は先頭 5 桁に短縮されます。
Log: デバッグログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログが空になります。
Remove data on uninstall: オンの場合、モジュールをアンインストールすると、すべてのモジュール設定、配送業者、ログが削除されます。オフの場合、再インストールのためにすべてが保持されます。見積もりのキャッシュは常に削除されます。注文とともに保存されたサービスは注文履歴であり、保持されます。
チェックアウト時の動作
配送ステップで、PrestaShop はモジュールに Melhor Envio の料金を問い合わせます。配送が必要な商品のみが対象です。仮想商品は重量に加算されず、小計にも含まれません。モジュールはまず条件を確認します：Ignore shipping zones の国、カートの重量、最低小計です。
8 桁の CEP を持つブラジルの配送先住所の場合、モジュールは発送元と配送先の CEP、および配送可能な各商品の重量、サイズ、数量、申告金額を Melhor Envio に送信します。サービスの一覧を設定している場合は、その一覧も送信されます。見積もりは既定通貨に換算され、料金順に並べられ、その後、購入者のカートの通貨で表示されます。送料無料が適用される場合、最も安いサービスの料金は 0 になります。
One option - the cheapest service の場合、配送業者は最も安いサービスの料金を表示します。Delivery time がオンの場合は、配送業者の下に Delivery estimate: の行が表示されます。One option per service の場合、購入者には配送業者の下に Choose a delivery service: が表示され、サービスごとのラジオボタン、料金、配送日数の目安が表示されます。選択内容はすぐに保存され、配送業者の料金とカートの概要が更新されます。そのサービスが住所に対してもう提供されていない場合、購入者には This service is not available for your address any more. Please choose another one. が表示され、前回の選択が戻されます。
各見積もりは、荷物、CEP、トークン、環境ごとに 1 時間キャッシュされるため、同じカートで新たなリクエストが発生することはありません。失敗した呼び出しは 5 分間記憶されるため、API の障害によって、チェックアウトの更新のたびに遅くなることはありません。API のタイムアウトは 12 秒です。
トークンがない、住所が日本国外である、または有効な CEP がまだない、BRL 為替レートがない、あるいは Melhor Envio がエラーを返す、またはそのルートにサービスがない場合は、フォールバック料金が使用されます：その国の行（または * の行）、なければフォールバック送料です。送料無料が適用される場合は、料金がなくても配送業者は無料で表示されます。料金がまったくない場合、配送業者は非表示になります。購入者が API エラーを見ることはありません。
注文がある配送業者を Shipping > Carriers で編集すると、PrestaShop はそれを新しいバージョンの配送業者として保存します。モジュールは新しいバージョンに自動的に従います。
モジュールは料金の計算のみを行います。ラベルの購入や作成、Melhor Envio のカートへの発送登録、荷物の追跡、集荷の手配、請求書（NF-e）データの送信は行いません。Jadlog、Azul、LATAM の営業所（持ち込み拠点）の選択や、「手渡し」「受領証」の追加サービスも提供しません。発送は Melhor Envio の管理パネルで行ってください。Melhor Envio はブラジル国内のみに配送します。その他の国にはフォールバック料金のみが適用されます。
注文
リアルタイムの見積もりで注文が行われると、モジュールは Melhor Envio のサービスとその配送日数の目安を注文とともに保存します。管理画面の注文ページには Melhor Envio ブロックが表示され、Melhor Envio service（サービス ID 付き）と Delivery estimate が表示されるため、Melhor Envio でどのサービスを購入すればよいかがわかります。購入者は、アカウントの注文ページで同じ情報を確認できます。注文確認メールでは、配送業者名の後に追加されます。フォールバック料金で注文された場合、サービスは保存されません。既存の注文には影響ありません。
ライセンスキー
このモジュールは vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Melhor Envio は、Modules > Module Manager > VibeFox Melhor Envio > Configure の最初のブロックで、設定の上にあります。キーを License key に貼り付け、Activate をクリックします。その後、ブロックにはマスクされたキー、ステータス（たとえばライセンスの有効期限日とドメイン）、そして Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このショップからキーを削除）のボタンが表示されます。その下には Product: presta-shipping-melhor-envio の行と、vibefox.net のアカウントを開く Manage licenses and domains in your account のリンクがあります。モジュールの Configure 権限を持つ従業員のみがキーを変更できます。ブロックのテキストは管理画面の言語に従います（英語とロシア語が含まれています）。
キーが受け入れられない場合、ブロックは理由を表示します。例：Key not found、This key belongs to another product、Domain limit reached、または日付付きの License expired on。ショップのアドレスを変更した後、またはアカウントでドメイン枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、モジュールは最後に確認できたステータスで動作を続けます。
1 つのキーは 1 つのドメインでのみ有効です。マルチストア構成でも、メインショップのドメインを指します。ショップからキーを削除しても、ドメイン枠は解放されません。vibefox.net のアカウントで枠を解放してください。
有効なキーがない場合、Melhor Envio の配送業者はチェックアウトで購入者に表示されず、料金も計算されません。PrestaShop のストアフロントは、管理画面にログインしていることを認識しないため、配送業者はあなたにも表示されません。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響ありません。
ライセンスが期限切れになっても、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。管理画面で作業している間、ステータスは自動的に再確認されます。キー入力後の最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
チェックアウトに Melhor Envio が表示されない：ライセンスが有効であり、Enable Melhor Envio shipping がオンになっていることを確認してください。Shipping > Carriers で、配送業者が購入者の国のゾーンと顧客グループをカバーしているかを確認するか、Ignore shipping zones をオンにして Countries を確認してください。モジュールのページ上部の警告、重量制限、Minimum subtotal も確認してください。トークンや見積もりがない場合、配送業者にはフォールバック料金が必要です：Fallback price table の行、または Fallback cost。商品ページで、特定の配送業者に制限されている場合もあります。
フォールバック料金のみが表示される：Debug log をオンにし、チェックアウトを再読み込みして、モジュールのページの Log 欄を確認してください。よくある原因：トークンがない、発送元 CEP が 8 桁ではない、既定通貨が BRL 以外なのに BRL exchange rate がない、配送先 CEP がまだない、またはどのサービスもそのルートをカバーしていない。
ログまたは警告に HTTP 401 または 403：Melhor Envio がアクセストークンを拒否しました。トークンが誤っている、期限切れ、または取り消されている、あるいは別の環境のものです。新しいトークンを生成し、Sandbox の設定がトークンと一致しているか確認してください。
購入者に「The service could not be saved. Please try again.」と表示される：ネットワークエラーなどにより、選択内容がショップに届きませんでした。購入者はサービスを選び直すことができます。購入者が Continue をクリックした時点で選択されていたサービスも保存されます。
Melhor Envio の料金に税が加算される：Tax を No tax に設定してください。
変更後に見積もりが古いように見える：モジュールのページで Save をクリックしてください。キャッシュされた見積もりが消去されます。
Melhor Envio の配送業者が見つからないと表示される：その配送業者は Shipping > Carriers で削除されています。Modules > Module Manager でモジュールをリセットすると、再作成されます。
アンインストール
Modules > Module Manager に進み、VibeFox Melhor Envio の横のメニューを開いて Uninstall を選択します。ライセンスキーとライセンスステータスは常に削除されます。見積もりのキャッシュは常に削除されます。Remove data on uninstall がオンの場合、配送業者は削除されます（注文は履歴を保持します）。配送業者自身のゾーンは復元され、設定、未完了のカートのサービス選択、ログは削除されます。オフの場合、配送業者は無効になるだけで、すべての設定は保持されます。モジュールを再インストールすると、配送業者は以前のステータスに戻ります。注文とともに保存されたサービスは、常に保持されます。
Melhor Envio は、それぞれの所有者の商標です。本モジュールは Melhor Envio と提携しておらず、Melhor Envio による推奨も受けていません。