VibeFox NZ Post for WooCommerce — ヘルプ
動作要件
WordPress: 5.8 以降。
WooCommerce: 5.0 以降。インストールされて有効になっている必要があります。WooCommerce がなければ、本プラグインは有効化できません。
PHP: 8.0 以降。
NZ Post API へのアクセス（リアルタイム料金のみ必要）：リアルタイム料金は NZ Post ShippingOptions API を使用します。NZ Post の Web サイトにある Developer Resource Centre で API アクセスを申請してください。NZ Post は、まずテスト環境（UAT）用に Client ID と Client Secret を発行し、その後、同社の稼働前チェックリストを完了すると本番環境用の認証情報を発行します。ニュージーランド国内の料金には、さらに NZ Post の法人口座が必要です。口座番号とその auth code（または site code）を用意してください。固定料金のみを使う場合、API アクセスは不要です。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーで 1 つのドメインに対応します。
インストール
1. WordPress で Plugins > Add New > Upload Plugin を開き、プラグインの ZIP ファイルを選択して Install Now をクリックします。FTP で vfd_nz_post フォルダを /wp-content/plugins/ にアップロードすることもできます。
2. Activate をクリックします。
3. 設定を開きます。WooCommerce > Settings > Shipping > VibeFox NZ Post、またはプラグイン一覧ページのプラグイン名の下にある Settings をクリックします。
4. ページ上部のライセンスブロックに VibeFox ライセンスキーを入力し、Activate をクリックします。
5. リアルタイム料金を使う場合は、NZ Post API (live rates) セクションに入力します。固定料金も任意で入力できます。固定料金は、リアルタイム料金を使わない場合や予備として使われます（設定を参照）。
6. WooCommerce > Settings > Shipping > Shipping zones で、VibeFox NZ Post をいずれかの配送ゾーンに追加するか、Ignore shipping zones を有効にして国を選択します。
設定
すべての設定は 1 つのページにあります：WooCommerce > Settings > Shipping > VibeFox NZ Post。これらの設定はすべての配送ゾーンに適用されます。ゾーンにこの配送方法を追加すると、ゾーンのウィンドウには次の項目だけが表示されます：
Title (zone): このゾーンで購入者に表示される名称です。空欄にすると、全体の Method title が使われます。
設定を保存するたびに、キャッシュされた NZ Post の料金とアクセストークンは消去されます。保存された値ではリアルタイム料金が機能しない場合（Client ID と Client Secret のどちらか一方のみ入力されている、NZD の換算レートがない、国内料金の情報が不完全など）は、設定ページの上部に警告が表示されます。
General
Enable/Disable: この配送方法をすべてのゾーンで一度にオンまたはオフにします。
Method title: カートとチェックアウトに表示される配送方法の名称です。ゾーンごとに上書きできます。既定値：NZ Post。
Tax status: Taxable は WooCommerce の税金を送料に加算し、None は加算しません。下の API prices も参照してください。
NZ Post API（リアルタイム料金）（固定料金のみを使う場合は Client ID を空欄にします）
Environment: Production (api.nzpost.co.nz)（既定）または Testing / UAT (api.uat.nzpost.co.nz)。Client ID を発行された環境を選択してください。
Client ID: NZ Post API アプリケーションの OAuth2 クライアント ID です。
Client Secret: OAuth2 のクライアントシークレットです。アクセストークンと交換され、そのトークンは有効期限切れまでキャッシュされます。
Account number: NZ Post の法人（請求）口座番号です。ニュージーランド国内の料金には必須です。国際料金では任意で、入力すると NZ Post が貴社の契約料金を返します。
Auth code: 国内料金に使うアカウントの auth code です。site code を入力する場合は不要です。
Site code: auth code の代わりに使う、NZ Post の集荷拠点コードです。
Ship-from suburb: 荷物の発送元住所の郊外名です（例：Petone）。国内料金に必要です。
Ship-from city: 荷物の発送元の町または市です（例：Lower Hutt）。国内料金に必要です。
Ship-from postcode: 荷物の発送元の 4 桁のニュージーランド郵便番号です（例：5012）。国内料金に必要です。
Services: 任意の NZ Post サービスコードをカンマ区切りで入力します（例：CPOLP, ICOU）。ここに指定したサービスのみ料金が計算されます。空欄にすると、NZ Post がその荷物に対して返す中で最も安いサービスを使います。
API prices: Including GST（既定）または Excluding GST。NZ Post の国内料金には 15% の GST が含まれています。国際郵便はゼロ税率です。Tax status が Taxable の場合は、GST の二重課税を避けるために Excluding GST を選んでください。
NZD → (store currency) rate: NZ Post の料金は NZD 建てです。ストア通貨が NZD でない場合は、1 NZD が貴店の通貨で何単位に相当するかを入力してください（例：0.55）。入力しない場合、リアルタイム料金は使われません。同じレートで、国際リクエストに送信される注文金額も換算されます。ストア通貨が NZD の場合は空欄にしてください。
リアルタイム料金用の荷物
カートは 1 個の荷物として NZ Post に送信されます。商品の重量と寸法は、ストアの単位から kg と cm に換算されます。荷物の長さと幅は、商品のうち最大のものが使われ、高さは全商品の容積が収まるまで増えます。以下の値は、重量や寸法がない商品に使われます。
Default product weight (kg): 重量がない商品ごとに使われます。既定値：0.5。
Default parcel length (cm): カート内のどの商品にも寸法がない場合に使われます。既定値：30。
Default parcel width (cm): カート内のどの商品にも寸法がない場合に使われます。既定値：20。
Default parcel height (cm): カート内のどの商品にも寸法がない場合に使われます。既定値：10。
固定料金（リアルタイム料金が設定されていない場合や、NZ Post が料金を返さない場合に使われます）
料金はストア通貨で入力します。
Country prices: 配送先の国ごとに 1 行です。+ Add country をクリックすると行が追加され、× をクリックすると削除されます。その他すべての国をカバーする行には * Default を選びます。各行には Any weight の料金と、任意の重量区分の列があります：≤ 1 kg、1–2 kg、2–3 kg、3–5 kg、> 5 kg（カートの重量）。重量区分の列に値が入力されている場合はその値が Any weight より優先され、空欄または 0 の場合は Any weight が使われます。Any weight の料金を 0 にすると、その国への送料は無料になります。"9.99" と "9,99" のどちらも使えます。料金が入力されていない行、無効な国コード、負の料金は、保存時に削除されます。国ごとに残るのは 1 行だけです。
Fallback cost: API も国別料金表も料金を返さない場合に使われます。空欄にすると、その場合は配送方法が非表示になります。
Fixed price per: Order は料金を 1 回だけ請求します。Item (price × quantity) は、カート内の商品数を掛けて請求します。これは固定料金と予備の送料にのみ適用されます。リアルタイム料金は常に荷物全体で計算されます。
条件
Min cart weight (kg): カートの重量がこれより軽い場合、配送方法を非表示にします。0 は制限なしを意味します。
Max cart weight (kg): カートの重量がこれより重い場合、配送方法を非表示にします。既定値：25（NZ Post の宅配荷物は最大 25 kg）。0 は制限なしを意味します。
Minimum order amount: カートの小計がこの金額に達した場合のみ配送方法を表示します。空欄にすると常に表示されます。
Excluded shipping classes: カートに、これらの WooCommerce 配送クラスのいずれかに属する商品が含まれている場合、配送方法を非表示にします。
Free shipping from: NZ Post の配送が無料になるカートの小計です。配送方法に料金が設定されている場合にのみ適用されます。国別料金または予備の送料（この場合は NZ Post にリクエストは送られません）、またはリアルタイム料金が対象です。空欄にすると、送料無料は提供されません。
これらの条件に使うカートの重量では、重量のない商品は 0 として計算されます。
配送ゾーンを使わない場合の提供
Ignore shipping zones: 配送方法がどの配送ゾーンにも追加されていなくても、下記の国に対して NZ Post を提供します。
Countries: このモードで対象とする配送先の国です。空欄にすると、貴店が配送可能なすべての国が対象になります。このフィールドは Ignore shipping zones が有効な場合にのみ使われます。
詳細設定
Debug log: 料金の計算内容を WooCommerce > Status > Logs に書き込みます（ソースは "vfd-nz-post"）。API エラーは、デバッグログがオフでも常に記録されます。認証情報、トークン、顧客の住所は記録されません。作業が終わったらログをオフにしてください。
Remove data on uninstall: オンの場合、プラグインを削除すると、その設定、ゾーンの配送方法、キャッシュされた料金が削除されます。プラグインを無効化しても、何も削除されません。
チェックアウト時の動作
購入者が配送先住所を入力すると、WooCommerce がプラグインに料金を問い合わせます。プラグインはまず条件を確認します：配送先の国、カートの重量、最低注文金額、除外する配送クラスです。次に料金を探します：NZ Post のリアルタイム料金、国別料金表、予備の送料の順です。料金が見つからない場合、配送方法は非表示になります。送料無料が適用される場合、購入者は無料で配送方法を確認できます。
リアルタイム料金が設定されていると、プラグインは Client ID と Client Secret を使ってアクセストークンを取得し、NZ Post に料金を問い合わせます。ニュージーランド国内の住所の場合、貴社の口座情報、発送元住所、購入者の郊外・市・郵便番号、荷物の重量とサイズを送信します。WooCommerce には郊外のフィールドがないため、プラグインは Address line 2 に郊外名が入っている場合はそれを使い、そうでなければ町または市を使います。国内料金は、購入者が市と 4 桁の郵便番号を入力した後にのみ要求されます。その他の国の場合は、配送先の国、荷物の重量とサイズ、NZD に換算した注文金額を送信します。
料金が設定されている、許可された最も安いサービスが使われます。割増料金と必須オプションも含まれます。料金は NZD からストア通貨に換算されます。料金が確定したサービスは、NZ Post service として注文と一緒に保存され、注文画面に表示されます。各応答は 1 時間キャッシュされます。失敗したリクエストは 10 分間キャッシュされるため、チェックアウトの更新のたびに NZ Post の応答を待つことはありません。API のタイムアウトは 10 秒です。期限切れのアクセストークンは自動的に更新されます。
NZ Post が料金を返さない場合（API が未設定、エラー、住所の不備、サービスの利用不可、NZD レートがない）、購入者にエラーは表示されません。国別料金表の料金が使われ、次に予備の送料が使われます。固定料金がない場合、配送方法は非表示になります。その理由はログに記録されます。
この配送方法は、クラシックチェックアウトとカート・チェックアウトのブロックで動作します。WooCommerce の高パフォーマンス注文保存（HPOS）に対応しています。
本プラグインは料金の計算のみを行います。送り状の作成、集荷の予約、マニフェストの作成、荷物の追跡、住所の検証は行わず、購入者が受取場所、私書箱（PO Box）、宅配ロッカー（parcel locker）を選ぶこともできません。カートは 1 個の荷物として計算され、購入者はサービスの一覧ではなく、NZ Post の料金を 1 つだけ見ます。
ライセンスキー
本プラグインは、vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロックは WooCommerce > Settings > Shipping > VibeFox NZ Post の上部にあります。キーを License key に貼り付けて、Activate をクリックします。ブロックには、ライセンスが有効な期限日や、貴社のドメインなどのステータスが表示されます。Check now でステータスを再確認し、Change key で別のキーを入力し、Remove key でこのサイトからキーを削除します。Manage licenses and domains in your account のリンクから、vibefox.net のアカウントを開けます。
1 つのキーは 1 つのドメインで使用できます。サイトからキーを削除しても、ドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。
有効なキーがない場合、チェックアウトで購入者に NZ Post は表示されません。ログイン中のストア管理者には、(unlicensed — visible to admins only) と表示された状態で引き続き表示されるため、キーを購入する前にプラグインを設定してテストできます。プラグインの一覧ページと WooCommerce のページには、通知が表示されます。既存の注文には影響しません。
ライセンスの期限が切れても、プラグインは動作を続けます。ただし、アップデートとサポートには更新が必要です。ステータスは、バックグラウンドで自動的に再確認されます。
トラブルシューティング
チェックアウトに NZ Post が表示されない：ライセンスが有効か、Enable/Disable がオンか、購入者の国のゾーンに配送方法が追加されているか（または Ignore shipping zones がオンで、その国が許可されているか）を確認してください。重量の制限、Minimum order amount、Excluded shipping classes も確認してください。NZ Post が料金を返さない場合、配送方法は国別料金または Fallback cost がある場合にのみ表示されます。
リアルタイム料金が表示されない：WooCommerce > Status > Logs を開き、ソースが "vfd-nz-post" のログを確認してください。API のエラーは常にここに記録されます。詳細は Debug log をオンにすると確認できます。ログには原因が表示されます：Client ID または Client Secret がない、トークンが拒否された、アカウントや発送元住所のデータがない、購入者の市または郵便番号がまだない、NZD レートがない、料金が設定されたサービスがない、などです。問題を解決するまでは、固定料金が使われます。
トークンのリクエストが失敗する：Client ID、Client Secret、Environment を確認してください。UAT の認証情報は本番環境では使えず、その逆も同様です。
国内料金がなく、国際料金は機能する：ニュージーランド国内の料金には、Account number、Auth code または Site code、そして 4 桁の郵便番号を含む発送元住所の完全な入力が必要です。購入者は市と 4 桁の郵便番号を入力する必要があります。開発者は、vfd_nzpt_delivery_suburb フィルターを使うと、配送先住所に送信される郊外名を変更できます。
ストアが NZD を使っていない：NZD → (store currency) rate を入力してください。固定料金は常にストア通貨で設定されます。
配送料に GST が二重に課される：NZ Post の国内料金には 15% の GST が含まれています。Tax status が Taxable の場合は、API prices を Excluding GST に設定してください。
変更後も料金が古いまま：設定ページを保存してください。これにより、キャッシュされた NZ Post の料金とトークンが消去されます。
ライセンスブロックにエラーが表示される：ブロックのメッセージに従ってください。たとえば、キーが別のドメインで既に使われている場合は、vibefox.net のアカウントで枠を解放してから Check now をクリックしてください。サイトのアドレスが変わった場合は、Check now をクリックして、新しいドメインでキーを有効にしてください。ライセンスサーバーに接続できない場合、プラグインは最後に確認された状態で動作を続けます。
アンインストール
プラグインを無効化しても、すべてのデータは保持されます。削除するには、Plugins ページで無効化してから削除してください。本プラグインのライセンスキーとライセンスステータスは、常に削除されます。設定、ゾーンの配送方法、キャッシュされた料金、アクセストークンは、Remove data on uninstall がオンだった場合にのみ削除されます。そうでない場合は、後で再インストールするために残ります。既存の注文は、配送の明細を保持します。
NZ Post は、その所有者の商標です。本プラグインは NZ Post と提携しておらず、NZ Post の承認も受けていません。