VibeFox Melhor Envio for WooCommerce — ヘルプ
要件
WordPress: 5.8 以降。
WooCommerce: 7.0 以降。インストールされて有効になっている必要があります。WooCommerce がない場合、プラグインは有効化されません。
PHP: 8.0 以降。
Melhor Envio アカウント（リアルタイム見積もりの場合のみ）：リアルタイム見積もりにはアクセストークンが必要です。Melhor Envio アカウントで、トークンのアクセス許可ページ（Integrações > Permissões de acesso、melhorenvio.com.br/painel/gerenciar/tokens）を開き、「shipping-calculate」権限を持つトークンを生成してください。テストには、Melhor Envio のサンドボックスでトークンを生成します（sandbox.melhorenvio.com.br/painel/gerenciar/tokens）。本番用とサンドボックス用のトークンは別物です。トークンには有効期限があります。「接続」ボタンはなく、トークンを設定に貼り付けます。トークンがない場合、この配送方法はフォールバック料金を使用します。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
1. WordPress で Plugins > Add New > Upload Plugin を開き、プラグインの ZIP ファイルを選択して Install Now をクリックします。FTP で vfd_melhor_envio フォルダを /wp-content/plugins/ にアップロードすることもできます。
2. Activate をクリックします。
3. 設定を開きます：WooCommerce > Settings > Shipping > VibeFox Melhor Envio。または、プラグインのページでプラグイン名の下にある Settings をクリックします。
4. ページ上部のライセンスブロックに VibeFox ライセンスキーを入力し、Activate をクリックします。
5. アクセストークン、連絡先メールアドレス、発送元の郵便番号（CEP）を貼り付けます。ストアの通貨が BRL でない場合は BRL exchange rate を設定します。必要に応じて、フォールバック料金表（例：ブラジル向け）またはフォールバック送料を入力します。
6. WooCommerce > Settings > Shipping > Shipping zones でブラジル向けのゾーンを追加し、そのゾーンに VibeFox Melhor Envio を追加します。または Ignore shipping zones を有効にして国を選択します。
設定
すべての設定は 1 つのページにあります：WooCommerce > Settings > Shipping > VibeFox Melhor Envio。設定はすべての配送ゾーンに適用されます。ゾーンにこの方法を追加すると、ゾーンのウィンドウには 1 つの項目しかありません：
Title (zone)：チェックアウトでのこのオプションの名前です。空欄にすると、全体の Name が使用されます。
ページ上部の警告は、設定の不備を示します。8 桁ではない発送元の郵便番号（CEP）、連絡先メールアドレスの未入力、BRL 為替レートの未設定、Melhor Envio API の直近のエラー（日付付き）、またはトークンもフォールバック料金もない状態です。設定を保存するたびに、キャッシュされた見積もりは消去されます。
一般
Enable/Disable：Melhor Envio の配送をすべてのゾーンでまとめて有効または無効にします。
Name：チェックアウトで購入者に表示される配送方法の名前です。既定値：Melhor Envio。
Tax status：Taxable は配送料に WooCommerce の税金を加算します。None は加算しません。
Melhor Envio API
Access token：下で選択した環境のトークンです。ログには決して記録されません。
Sandbox：テストに Melhor Envio のサンドボックス（sandbox.melhorenvio.com.br）を使用します。サンドボックス用のトークンと組み合わせて使用してください。既定値：オフ。
Contact e-mail：すべてのリクエストとともに Melhor Envio へ送信される技術的な連絡先メールアドレスです。Melhor Envio はすべての連携でこれを必要とします。
Origin CEP：荷物を発送する元の郵便番号（CEP、8 桁）です。例：01310-100。有効な発送元の 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。これを設定しないと、リアルタイム見積もりは使用されません。申告価額も同じレートで BRL に換算されます。
Default product weight (kg)：重量が設定されていない商品に使用されます。見積もりと重量制限の両方に適用されます。既定値：0.3。
Default product size (cm)：サイズが設定されていない商品に使用される、縦 x 横 x 高さです。既定値：16x11x5。
Fallback prices（ストアの通貨で）
フォールバック料金は、トークンがない場合、配送先の郵便番号（CEP）がない場合、または API が見積もりを返さない場合（エラー、タイムアウト、対象外）に使用されます。
Fallback price table：国別およびカートの重量別の料金です。+ Add country をクリックして行を追加し、×印をクリックして削除します。自分の行がないすべての国には * Any country を選択します。各行には Price と重量の列があります：1 kg まで XS、1-2 kg S、2-3 kg M、3-5 kg L、5 kg を超えると XL です。空欄または 0 の列は Price を使用します。「9.99」と「9,99」のどちらも使用できます。数値ではない値は保存後に報告され、無視されます。
Fallback cost：料金表にも料金がない場合に使用されます。この場合に配送方法を非表示にするには、空欄にします。
Fallback calculation：Per order はフォールバック料金を 1 回だけ請求します。Per item (each item priced by its own weight x quantity) は、各商品の重量（重量がない場合は既定の重量）に対応するフォールバック料金を探し、数量を掛けます。これはフォールバック料金にのみ適用されます。Melhor Envio の見積もりにはすでにすべての商品が含まれています。
Availability
Min weight (kg)：カートの重量がこれより軽い場合、この配送方法を非表示にします。0 は制限なしを意味します。
Max weight (kg)：カートの重量がこれより重い場合、この配送方法を非表示にします。既定値：30。0 は制限なしを意味します。
Minimum subtotal：カートの小計（割引後、税込み前）がこの金額以上の場合のみ、この配送方法を表示します。常に表示する場合は空欄にします。
Free shipping from：送料が無料になるカートの小計です。サービスごとに 1 つのオプションを表示している場合、無料になるのは最も安いサービスだけです。速いサービスは料金がそのままです。無効にする場合は空欄にします。
Excluded shipping classes：カートに、これらの WooCommerce 配送クラスのいずれかに属する商品が含まれている場合、この配送方法を非表示にします。
Ignore shipping zones：配送ゾーンに追加していなくても、下記の国向けにこの配送方法を提供します。
Countries：このモードの配送先の国です。すべての国を対象にする場合は空欄にします。このフィールドは Ignore shipping zones がオンの場合にのみ使用されます。
詳細設定
Debug log：API リクエストと料金計算を WooCommerce > Status > Logs（ソース vfd-melhor-envio）に記録します。このオプションがオフでも、エラーは常に記録されます。トークンと購入者の住所は決して記録されません。
Remove data on uninstall：オンにすると、プラグインを削除したときに、プラグインのすべての設定とゾーンの配送方法が削除されます。プラグインを無効化しても設定は削除されません。
チェックアウト時の動作
購入者が配送先の住所を入力すると、WooCommerce がプラグインに料金を問い合わせます。プラグインはまず条件を確認します：カートの重量、最低小計、除外する配送クラスです。
ブラジルの 8 桁の郵便番号（CEP）を持つ配送先の場合、プラグインは発送元と配送先の CEP、そして発送可能な各商品の重量、サイズ、数量、申告価額を Melhor Envio に送信します。サービスリストを設定している場合は、それも含めます。見積もりはストアの通貨に換算され、料金順に並べられます。購入者には、最も安いサービス、またはサービスごとのオプションが表示されます。配送日数の目安も、有効であれば表示されます。送料無料が適用される場合、最も安いサービスの料金は 0 です。
各見積もりは、荷物、CEP、環境ごとに 1 時間キャッシュされるため、同じカートで新たなリクエストが発生することはありません。失敗した呼び出しは 5 分間記憶されるため、API の障害があっても、チェックアウトの更新のたびに遅くなることはありません。API のタイムアウトは 12 秒です。
トークンがない場合、住所がブラジル以外にある場合、または有効な郵便番号（CEP）がまだない場合、BRL 為替レートがない場合、あるいは Melhor Envio がエラーを返す、またはそのルートに該当するサービスがない場合は、フォールバック料金が使用されます。国の行（または * の行）、なければフォールバック送料です。送料無料が適用される場合は、料金がなくても無料で表示されます。料金がまったくない場合は、この配送方法は非表示になります。購入者に API エラーが表示されることはありません。
この方法は、クラシックチェックアウト、およびカートとチェックアウトのブロックで動作します。WooCommerce の高性能注文保存機能（HPOS）に対応しています。
プラグインが行うのは料金の計算だけです。ラベルの購入や作成、Melhor Envio のカートへの発送登録、荷物の追跡、集荷の手配、請求書（NF-e）データの送信は行いません。Jadlog、Azul、LATAM の営業所（受け渡し拠点）の選択や、「手渡し」や「受領証」の追加サービスは提供していません。発送は Melhor Envio の管理画面で行ってください。Melhor Envio はブラジル国内にのみ配送します。その他の国にはフォールバック料金のみが適用されます。
注文
リアルタイム見積もりで注文が行われると、見積もられたサービスと配送日数の目安が注文の配送明細に保存されます。これらは注文画面と注文メールに Melhor Envio service および Delivery estimate として表示されるため、Melhor Envio でどのサービスを購入すべきかがわかります。既存の注文は、配送明細をそのまま保持します。
ライセンスキー
このプラグインは、vibefox.net で購入した VibeFox ライセンスキーで動作します。ライセンスブロックは WooCommerce > Settings > Shipping > VibeFox Melhor Envio のページ上部にあります。キーを License key に貼り付けて、Activate をクリックします。ブロックには、ライセンスの有効期限日やお使いのドメインなど、ステータスが表示されます。Check now でステータスを再確認し、Change key で別のキーを入力し、Remove key でこのサイトからキーを削除します。Manage licenses and domains in your account のリンクから、vibefox.net のアカウントを開けます。
1 つのキーは 1 つのドメインで使用できます。サイトからキーを削除しても、ドメインの枠は解放されません。枠は vibefox.net のアカウントで解放してください。
有効なキーがない場合、チェックアウトで購入者に Melhor Envio は表示されません。ログインしているストアの管理者には、(unlicensed — visible to admins only) と表示された状態で引き続き表示されるため、キーを購入する前にプラグインを設定してテストできます。プラグインのページと WooCommerce のページにリマインダーが表示されます。既存の注文には影響しません。
ライセンスの有効期限が切れてもプラグインは動作し続けますが、アップデートとサポートには更新が必要です。ステータスはバックグラウンドで自動的に再確認されます。
トラブルシューティング
チェックアウトに Melhor Envio が表示されない：ライセンスが有効であること、Enable/Disable がオンであること、そしてこの方法が購入者の国のゾーンに追加されていることを確認してください（または Ignore shipping zones がオンで、その国が許可されていること）。設定ページ上部の警告、重量制限、Minimum subtotal、Excluded shipping classes を確認します。トークンまたは見積もりがない場合、この方法にはフォールバック料金が必要です：Fallback price table の行、または Fallback cost です。
フォールバック料金のみが表示される：Debug log をオンにし、チェックアウトを再読み込みして、WooCommerce > Status > Logs（ソース vfd-melhor-envio）を開いてください。よくある原因：トークンがない、発送元の郵便番号（CEP）が 8 桁ではない、BRL 以外のストア通貨に BRL exchange rate がない、配送先の郵便番号（CEP）がまだない、またはどのサービスもそのルートをカバーしていない。
ログまたは警告に HTTP 401 または 403 が表示される：Melhor Envio がアクセストークンを拒否しました。トークンが誤っている、期限切れまたは取り消されている、あるいは別の環境のものです。新しいトークンを生成し、Sandbox の設定がそれと一致しているか確認してください。
購入者に表示される料金：1 つのオプションの場合は、Melhor Envio が返す最も安いサービスです。サービスごとに 1 つのオプションの場合は、そのルートに対応するすべてのサービスです。Per item はフォールバック料金にのみ適用されます。
変更後に見積もりが古く見える：設定ページを保存してください。キャッシュされた見積もりが消去されます。
ライセンスブロックにエラーが表示される：ブロックに表示されたメッセージに従ってください。例えば、そのキーが別のドメインで既に使用されている場合は、vibefox.net のアカウントで枠を解放し、Check now をクリックします。サイトのアドレスが変更された場合は、Check now をクリックして、新しいドメインでキーを有効にします。ライセンスサーバーに接続できない場合、プラグインは最後に確認したステータスで動作を続けます。
アンインストール
プラグインを無効化しても、すべての設定は保持されます。消去されるのは見積もりのキャッシュだけです。完全に削除するには、無効化してから Plugins ページで削除してください。このプラグインのライセンスキーとライセンスステータス、およびキャッシュされた見積もりは、常に削除されます。設定とゾーンの配送方法は、Remove data on uninstall がオンだった場合にのみ削除されます。それ以外の場合は、後で再インストールするために残ります。既存の注文は、配送明細をそのまま保持します。
Melhor Envio は、その所有者の商標です。本プラグインは Melhor Envio と提携しておらず、Melhor Envio による承認も受けていません。