VibeFox NZ Post for PrestaShop — ヘルプ
動作要件
PrestaShop：8.0 から 9.x。
PHP：8.0 以降。モジュールは古い PHP バージョンではインストールできません。
NZ Post API アクセス（リアルタイム料金のみ必要）：リアルタイム料金は NZ Post ShippingOptions API を使用します。NZ Post のウェブサイトにある Developer Resource Centre で API アクセスを申請してください。NZ Post は、まずテスト環境（UAT）用の Client ID と Client Secret を発行し、その後、同社の本番稼働チェックリストを経て本番環境用を発行します。ニュージーランド国内の料金には、さらに NZ Post の法人口座が必要です。必要な情報は、アカウント番号と、その auth code または site code です。固定料金のみを使う場合は、API アクセスは不要です。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインでのみ使えます。
インストール
1. 管理画面で Modules > Module Manager に進み、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックします。後で行う場合は、モジュール一覧から VibeFox NZ Post を探し、Configure をクリックします。
3. Configure ページ上部のライセンスブロックで、License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。
4. リアルタイム料金を使う場合は、NZ Post API (live rates) セクションに入力します。固定料金も任意で入力できます。固定料金は、リアルタイム料金がない場合と予備として使われます（「設定」を参照）。Save をクリックします。
インストール時、モジュールは配送日数のテキスト NZ Post parcel delivery を付けて NZ Post 配送業者を作成します。この配送業者はすべてのゾーンとすべての顧客グループに割り当てられます。ゾーン、顧客グループ、配送日数、ロゴ、サイズ制限は Shipping > Carriers で変更できます。料金はそこで設定しないでください。料金は常にモジュールから取得されます。
設定
すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox NZ Post > Configure。設定は配送業者のすべてのゾーンに適用されます。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。保存するたびに、キャッシュされた NZ Post の料金とアクセストークンも消去されます。
保存された値ではリアルタイム料金が機能しない場合、設定の上に警告が表示されます。Client ID と Client Secret のどちらか一方のみが入力されている場合、NZD 換算レートがない場合、国内料金のデータが不完全な場合などです。ストアの重量または寸法の単位をモジュールが認識できない場合にも警告が表示されます（その場合、重量は kg、寸法は cm として扱われます）。単位は International > Localization（Local units）で設定してください。数値フィールドには 0 または正の数を入力する必要があります。そうでない場合、ページにエラーが表示され、何も保存されません。
General
Enable NZ Post：配送業者を有効または無効にします。これは Shipping > Carriers の配送業者のステータスと同じスイッチです。
Method title：カートとチェックアウトに表示される配送業者名です。既定値：NZ Post。必須、最大 64 文字。
Tax：配送業者の税ルール、または No tax（送料には税金をかけません）です。ストアが送料に GST を加算する場合は、下の API prices を Excluding GST に設定し、GST が二重に課税されないようにします。
NZ Post API (live rates)（固定料金のみを使う場合は Client ID を空欄のままにします）
Environment：Production (api.nzpost.co.nz)（既定）または Testing / UAT (api.uat.nzpost.co.nz)。Client ID が発行された環境を使用してください。
Client ID：NZ Post API アプリケーションの OAuth2 client ID です。これを消去すると、保存されている Client Secret も消去されます。
Client Secret：OAuth2 client secret です。アクセストークンと交換され、有効期限までキャッシュされます。保存後、フィールドは空になり、Saved — leave empty to keep it と表示されます。変更する場合にのみ新しい値を入力してください。
Account number：NZ Post の法人（請求）口座番号です。ニュージーランド国内の料金には必須です。国際料金では任意で、入力すると NZ Post が契約料金を返します。これを消去すると、保存されている auth code も消去されます。
Auth code：国内料金用のアカウント認証コードです。site code を入力する場合は不要です。Client Secret と同様に、保存後は再表示されません。
Site code：auth code の代わりに使えるもので、NZ Post の集荷拠点コードです。
Ship-from suburb：荷物を発送する住所の郊外地域（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）がある場合は、GST が二重に課税されないよう Excluding GST を選択してください。
NZD → (shop currency) rate：NZ Post の料金は NZD 建てです。ストアの既定通貨が NZD でない場合は、NZD 1 単位が貴店の通貨でいくらに相当するかを入力します。例：0.55。入力しない場合、リアルタイム料金は使われません。同じレートは、国際リクエストで送信される注文金額の換算にも使われます。レートは 0 より大きい必要があります。ストア通貨が NZD の場合は、空欄のままにします。
Parcel for live rates
カートは 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。
Fixed prices（リアルタイム料金が設定されていない場合、または 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 つの国につき 1 行のみ残ります。
Fallback cost：API からも国別の表からも料金が得られない場合に使われます。空欄にすると、その場合は配送業者を非表示にします。
Fixed price per：Order は料金を 1 回だけ請求します。Item (price × quantity) は、カート内の商品数を掛けた金額を請求します。これは固定料金と予備の送料にのみ適用されます。リアルタイム料金は常に荷物全体に対して計算されます。
Conditions
Min cart weight (kg)：カートの重量がこの値より軽い場合、配送業者を非表示にします。0 は制限なしを意味します。
Max cart weight (kg)：カートの重量がこの値より重い場合、配送業者を非表示にします。既定値：25（NZ Post の宅配荷物は最大 25 kg）。空欄も 25 として扱われます。0 は制限なしを意味します。Ignore shipping zones が有効な場合、空欄は配送業者自身のゾーン以外では制限なしを意味します。Min cart weight が Max cart weight より大きい場合、ページにエラーが表示され、何も保存されません。配送業者が表示されることがなくなるためです。
Minimum order amount：カートの小計（配送が必要な商品、割引後、税前）がこの金額に達した場合にのみ、配送業者を表示します。空欄の場合は常に表示します。
Free shipping from：NZ Post の配送が無料になるカートの小計（割引後、税前）です。その場合、NZ Post へのリクエストは送信されません。空欄にすると、送料無料は提供されません。
これらの条件では、重量がない商品はカートの重量に 0 として含まれます。
Availability without shipping zones
通常、配送業者は Shipping > Carriers で割り当てられたゾーンに表示されます。
Ignore shipping zones：どのゾーンが一致するかにかかわらず、下に示す国の NZ Post を提供します。保存すると、配送業者はすべてのゾーン（後から作成されたゾーンを含む）に追加されます。このオプションをオフにすると、追加されたゾーンは再び削除されます。
Countries：このモードでの配送先の国です。空欄の場合、ストアで有効なすべての国が使われます。このフィールドは Ignore shipping zones が有効な場合にのみ使われます。
Advanced
Debug log：料金計算の記録を、モジュールのフォルダ内の logs/vfd_nzpt_debug.log.php に書き込みます。このファイルは Web から開くことはできません。API のエラーは、デバッグログがオフでも常に記録されます。認証情報、トークン、顧客の住所は記録されません。作業が終わったらログをオフにしてください。
Log：ログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログを空にできます。
Remove data on uninstall：有効にすると、モジュールをアンインストールしたときに、設定、配送業者、キャッシュされた料金、保存された注文の詳細、ログが削除されます。オフの場合、再インストールに備えてすべて保持されます。
チェックアウト時の動作
配送のステップで、PrestaShop はモジュールに NZ Post の料金を問い合わせます。対象となるのは物理商品のみです。バーチャル商品は重量に加算されず、注文金額にも含まれません。モジュールはまず条件を確認します：許可された国（Ignore shipping zones 使用時）、カートの重量、最低注文金額。送料無料が適用される場合、料金は 0 になり、NZ Post へのリクエストは送信されません。それ以外の場合は料金を探します。まず NZ Post のリアルタイム料金、次に国別の表、最後に予備の送料です。料金がない場合は、配送業者が非表示になります。
リアルタイム料金が設定されている場合、モジュールは Client ID と Client Secret を使ってアクセストークンを取得し、NZ Post に料金を問い合わせます。ニュージーランドの住所の場合、貴店のアカウント情報、発送元住所、顧客の郊外地域・市・郵便番号、荷物の重量とサイズを送信します。PrestaShop には郊外地域のフィールドがありません。モジュールは Address line 2 に郊外地域名（数字を含まないもの）が入っている場合はそれを使い、そうでなければ市を使います。国内料金は、顧客が市と 4 桁の郵便番号を入力した後にのみ問い合わせられます。その他の国の場合は、配送先の国、荷物の重量とサイズ、NZD 建ての注文金額を送信します。
割増料金や必須オプションを含め、料金が設定されている中で最も安い、許可されたサービスが使われます。料金は NZD から貴店の既定通貨に換算され、顧客のカート通貨で表示されます。各応答は 1 時間キャッシュされます。失敗したリクエストは 10 分間キャッシュされるため、チェックアウトが更新のたびに NZ Post を待つことはありません。API のタイムアウトは 10 秒です。期限切れのアクセストークンは自動的に更新されます。
NZ Post が料金を返さない場合（API が未設定、エラー、住所の不備、サービスが利用不可、NZD レートがない）、顧客にエラーは表示されません。国別の表の料金が使われ、次に予備の送料が使われます。固定料金がない場合は、配送業者が非表示になります。理由はログに記録されます。
配送業者に注文が入った後で Shipping > Carriers で配送業者を編集すると、PrestaShop はそれを新しいバージョンの配送業者として保存します。モジュールは新しいバージョンに自動的に従います。
モジュールが行うのは料金の計算だけです。送り状の作成、集荷の予約、マニフェストの作成、荷物の追跡、住所の検証は行わず、購入者が受取場所、私書箱（PO Box）、宅配ロッカー（parcel locker）を選ぶこともできません。カートは 1 つの荷物として料金が計算され、購入者はサービスの一覧ではなく、NZ Post の料金を 1 つ見ます。
注文
NZ Post の配送業者で注文が行われると、モジュールは配送料金の根拠を保存します。管理画面の注文ページには NZ Post ブロックが表示され、NZ Post service（リアルタイム料金で計算された NZ Post サービス）と Price source が示されます。Price source の値は Live rate (NZ Post ShippingOptions API)、Fixed price、Free shipping のいずれかです。このブロックには、料金や設定が後で変わっても、注文時点の値が表示されます。
ライセンスキー
モジュールは、vibefox.net で入手した VibeFox ライセンスキーで動作します。License — VibeFox NZ Post ライセンスブロックは、Modules > Module Manager > VibeFox NZ Post > Configure の一番上、設定の上にあるブロックです。キーを License key に入力し、Activate をクリックしてください。その後、ブロックにはキーがマスクされて表示され、ステータス（例: ライセンスの有効期限の日付とドメイン）と、ステータスを再確認する Check now、別のキーを入力する Change key、このショップからキーを削除する Remove key のボタンが表示されます。その下には Product: presta-shipping-nz-post の行と、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 のアカウントで枠を解放してください。
有効なキーがない場合、チェックアウトで顧客に NZ Post の配送業者は表示されず、料金も計算されません。PrestaShop のフロントエンドは、管理画面にログインしていることを認識しないため、配送業者はあなたにも表示されません。キーを購入する前にモジュールを設定することはできますが、チェックアウトでのテストはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。
ライセンスの期限が切れてもモジュールは動作を続けますが、アップデートとサポートには更新が必要です。管理画面で作業している間にステータスは自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日 1 回、その後は週に 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
チェックアウトに NZ Post が表示されない：ライセンスが有効であること、Enable NZ Post がオンになっていることを確認してください。Shipping > Carriers で、配送業者が顧客の国のゾーンと顧客のグループをカバーしていることを確認してください（または Ignore shipping zones がオンで、その国が許可されていること）。重量制限と Minimum order amount も確認してください。NZ Post が料金を返さない場合、配送業者は国別料金または Fallback cost がある場合にのみ表示されます。商品ページで、特定の配送業者に商品を制限している場合もあります。
リアルタイム料金が表示されない：モジュールのページ上部の警告を確認してください。次に Debug log をオンにし、チェックアウトを再読み込みして、Log フィールドを確認します。API のエラーは常にそこに表示されます。ログには原因が示されます：Client ID または Client Secret の欠落、トークンの拒否、アカウントまたは発送元データの欠落、顧客の市または郵便番号が未入力、NZD レートがない、料金のあるサービスがない、などです。問題を修正するまでは固定料金が使われます。
トークンのリクエストが失敗する：Client ID、Client Secret、Environment を確認してください。UAT の認証情報は本番環境では使えず、その逆も同様です。
国内料金がなく、国際料金は機能する：ニュージーランド国内の料金には、Account number、Auth code または Site code、4 桁の郵便番号を含む発送元住所の全体が必要です。顧客は市と 4 桁の郵便番号を入力する必要があります。開発者は、actionVfdNzptDeliverySuburb フックを使って、配送先住所に送信される郊外地域を変更できます。
ストアが NZD を使っていない：NZD → (shop currency) rate を入力してください。固定料金は常にストアの既定通貨で設定されます。
送料に GST が二重に課税される：NZ Post の国内料金には 15% の GST が含まれます。配送業者に Tax の税ルールがある場合は、API prices を Excluding GST に設定してください。
変更後に料金が古いように見える：モジュールのページで Save をクリックしてください。キャッシュされた NZ Post の料金とトークンが消去されます。
ページに NZ Post の配送業者が見つからないと表示される：配送業者は Shipping > Carriers で削除されています。Modules > Module Manager でモジュールをリセットすると、再作成されます。
アンインストール
Modules > Module Manager に進み、VibeFox NZ Post の横にあるメニューを開いて、Uninstall を選択します。ライセンスキーとライセンスステータスは常に削除されます。キャッシュされた料金とトークンは常に削除されます。Remove data on uninstall がオンの場合、配送業者は削除され（注文は履歴を保持します）、設定、保存された注文の詳細、ログも削除されます。オフの場合、配送業者は無効になるだけで、すべての設定は保持されます。モジュールを再インストールするか Reset を実行すると、保存されていた配送業者は以前のステータス（オンまたはオフ）に戻ります。
NZ Post は、それぞれの所有者の商標です。本モジュールは NZ Post と提携しておらず、NZ Post による推奨も受けていません。