VibeFox NZ Post for OpenCart — ヘルプ
要件
OpenCart: 3.0.x（3.0.5.0 で動作確認）または 4.0.2 以降（4.1.0.3 で動作確認）。
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 つのドメインで使用できます。
インストール
このダウンロードは、両方の OpenCart バージョン用のパッケージが入った zip ファイル 1 つです。コンピュータで解凍してください。README.txt、OpenCart 3 用パッケージ vfd_nz_post-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ vfd_nz_post.ocmod.zip が含まれています。お使いの OpenCart のバージョンのパッケージのみをインストールしてください。ライセンスキーは両方のバージョンで同じです。
OpenCart 3
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_nz_post-oc3-(version).ocmod.zip を選択します。この拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。インストーラーの代わりに、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。
2. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選びます。VibeFox NZ Post を見つけて、Install（緑色の + ボタン）をクリックします。
3. Edit（鉛筆のボタン）をクリックして設定画面を開きます。
4. Edit ページ上部のライセンスブロックにある License key 欄に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。
5. リアルタイム料金を使う場合は、NZ Post API (live rates) のセクションに入力します。固定料金を任意で入力することもできます。固定料金は、リアルタイム料金がない場合と予備として使われます（設定を参照）。Enable NZ Post をオンにして、Save をクリックします。
OpenCart 4
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_nz_post.ocmod.zip を選択します。ファイル名を変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から読み取るため、名前を変更したパッケージは動作しません。
2. パッケージは同じページのインストール済み拡張機能の一覧に表示されます。その横の Install（緑色の + ボタン）をクリックします。
3. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選択します。VibeFox NZ Post を見つけ、Install（緑色の + ボタン）をクリックしてから、Edit（鉛筆のボタン）をクリックします。
4. ライセンスキーと設定は、OpenCart 3 の手順 4 と 5 と同じように入力します。設定ページとその項目は両方のバージョンで同じです。
インストール直後は、Enable NZ Post をオンにして保存するまで、この配送方法はオフのままです。アンインストール後に拡張機能を再インストールした場合は、保存されていた NZ Post の設定が再び使用されます。
設定
すべての設定は拡張機能のページにあります。Extensions > Extensions > Shipping > VibeFox NZ Post > Edit です。セクションは左側に一覧表示されます。下部にある 1 つの Save ボタンで、ページを再読み込みせずにページ全体を保存します。保存するたびに、キャッシュされた NZ Post の料金とアクセストークンも消去されます。この拡張機能の変更権限を持つ管理者ユーザーだけが設定を保存できます。
Method title が空である場合、64 文字を超える場合、または < > ; = # { } を含む場合、数値フィールドに文字や負の数が入っている場合、ニュージーランドドルのレートが 0 の場合、Min cart weight (kg) が Max cart weight (kg) より大きい場合、Sort order が整数でない場合には、何も保存されずエラーが表示されます。保存された値ではリアルタイム料金が機能しない場合、設定の上部に警告が表示されます。Client ID と Client Secret のどちらか一方しか入力されていない場合、NZD への換算レートがない場合、国内料金のデータが不完全な場合です。ストアに単位が kg の重量クラス、または単位が cm の長さクラスがない場合にも警告が表示されます。その場合、重量と寸法は、それぞれのクラスの単位名（kg、g、lb、oz、cm、mm、m、in）に従って換算され、それ以外の単位は kg と cm として扱われます。
一般
設定はすべてのジオゾーンに適用されます。Availability で、配送方法をジオゾーンまたは国に限定できます。
Enable NZ Post: チェックアウト時に配送方法をオンまたはオフにします。既定値: オフ。
Method title: カートとチェックアウトでお客様に表示される配送方法の名前です。既定値: NZ Post。必須、最大 64 文字。
Tax class: 送料の税率クラス、または No tax（既定値。送料には税金がかかりません）です。ストアが送料に GST を加算する場合は、下の API prices を Excluding GST に設定して、GST の二重課税を防いでください。
Sort order: チェックアウト時の配送方法の中での NZ Post の表示順です。整数で入力します。
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 も消去されます。
Client Secret: OAuth2 のクライアントシークレットです。アクセストークンと交換され、有効期限が切れるまでキャッシュされます。保存後、この欄は空欄のまま Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。
Account number: NZ Post の法人（請求）口座番号です。ニュージーランド国内の料金には必須です。国際料金では任意です。入力すると、NZ Post が契約料金を返します。これを消去すると、保存されている auth code も消去されます。
Auth code: 国内料金に使う口座の auth code です。site code を入力する場合は不要です。Client Secret と同様に、保存後は再表示されません。
Site code: auth code の代わりに使えるもので、NZ Post の集荷拠点コード（pickup site code）です。
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 が含まれています。国際郵便は税率ゼロです。配送方法に税率クラス（General）がある場合は、GST の二重課税を防ぐために Excluding GST を選択してください。
NZD → （ストアの通貨）レート: NZ Post の料金は NZD 建てです。ストアの既定通貨が NZD でない場合は、1 NZD がストアの通貨でいくらに当たるかを入力してください（例: 0.55）。この値がないと、リアルタイム料金は使われません。同じレートで、国際リクエストに含まれる注文金額も換算されます。レートは 0 より大きい値である必要があります。ストアの通貨が NZD の場合は空欄のままにします。
リアルタイム料金の計算に使う荷物
カートは 1 個の荷物として NZ Post に送られます。商品の重量と寸法は、重量クラスと長さクラスから kg と cm に変換されます（国際リクエストでは mm）。荷物の長さと幅は商品の中で最大のものが使われ、高さはすべての商品の体積が収まるまで増えていきます。以下の値は、重量や寸法のない商品に使われます。
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 まで）。空欄も 25 として扱われます。0 は上限なしを意味します。Ignore shipping zones がオンのときは、空欄は Geo zone の外の住所に対して上限なしを意味します。
Minimum order amount: 配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額に達した場合にのみ、配送方法を表示します。常に表示する場合は空欄のままにします。
Free shipping from: 小計（クーポン適用後、税抜き）がこの金額以上の場合、NZ Post の配送料が無料になります。その場合、NZ Post へのリクエストは送信されません。送料無料を設けない場合は空欄のままにします。
これらの条件に使うカートの重量は、重量のない商品を 0 として数えます。
提供範囲
通常は、下で選択したジオゾーンで配送方法が提供されます。ジオゾーンが選択されていない場合は、どこでも提供されます。
Geo zone: この地理的ゾーン内の住所にのみ NZ Post を提供します。All zones（既定値）は制限なしを意味します。ジオゾーンは System > Localisation > Geo Zones で管理します。
Ignore shipping zones: 下に記載された国については、ジオゾーンの外でも NZ Post を提供します。オンにすると、この国だけが配送方法を受け取ります。ジオゾーンの内側でも同様です。既定値: オフ。
Countries: このモードで対象とする配送先の国です。空欄にすると、ストアで有効になっているすべての国が使われます。このフィールドは、Ignore shipping zones がオンのときにのみ使われます。
詳細設定
Debug log: 料金の計算内容を storage/logs/vfd_nzpt_debug.log.php（OpenCart 4 では system/storage/logs/vfd_nzpt_debug.log.php）に書き込みます。このファイルはウェブから読み取ることはできません。デバッグログがオフでも、API のエラーは常に記録されます。認証情報、トークン、口座番号、お客様の住所は記録されません。確認が終わったらオフにしてください。ファイルが 5 MB に達すると、vfd_nzpt_debug.old.log.php に移動され、新しいログが始まります。
Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると内容を消去します。
Remove data on uninstall: オンの場合、拡張機能をアンインストールすると、設定とログが削除されます。オフ（既定値）の場合は、再インストール用に保持されます。キャッシュされた料金は常に削除されます。注文の NZ Post の詳細は常に保持されます。
インポート / エクスポート
Export: Download JSON をクリックすると、設定を JSON ファイルとして保存できます。Client Secret と auth code はエクスポートされません。
Import: 以前にエクスポートした JSON を貼り付けて Import をクリックすると、設定を復元します（別のストアでの利用など）。値は通常の保存と同じように検証されます。保存された Client Secret と auth code は、Client ID と口座番号が入力されている限り保持されます。
チェックアウト時の動作
OpenCart が配送方法を表示するとき、拡張機能に NZ Post の料金を問い合わせます。Geo zone が設定されていて、住所がその範囲外の場合、Ignore shipping zones がオンで、その国が許可されている場合にのみ NZ Post が提供されます。Requires Shipping が Yes に設定されている商品のみが計算に含まれます。それ以外の商品は重量に加算されず、注文金額にも含まれません。その後、拡張機能は条件を確認します。許可された国（Ignore shipping zones と併用）、カートの重量、最低注文金額です。注文金額は、配送が必要な商品の料金（クーポン割引後、税抜き）です。ギフト券、リワードポイント、ストアクレジットは考慮されません。送料無料が適用される場合は料金が 0 となり、NZ Post へのリクエストは送信されません。それ以外の場合は料金を探します。まず NZ Post のリアルタイム料金、次に国別の料金表、最後に予備の料金です。料金がない場合は、配送方法が非表示になります。
リアルタイム料金が設定されていると、拡張機能は Client ID と Client Secret を使ってアクセストークンを取得し、NZ Post に料金を問い合わせます。ニュージーランドの住所の場合は、口座情報、発送元の住所、お客様の地区、市、郵便番号、荷物の重量と寸法を送信します。OpenCart には地区の欄がないため、Address 2 に地区名（数字を含まないもの）が入っている場合はそれを使い、そうでない場合は市を使います。国内料金は、お客様が市と 4 桁の郵便番号を入力した後にのみ問い合わせられます。その他の国の場合は、配送先の国、荷物の重量と寸法、NZD 建ての注文金額を送信します。
料金が設定されている、許可された最安のサービスが使われます。割増料金や必須オプションも含まれます。料金は NZD からストアの既定通貨に換算され、その小数桁に丸められ、選択した Tax class の税金を加えて、お客様の通貨で表示されます。各応答は 1 時間キャッシュされます。失敗したリクエストは 10 分間キャッシュされるため、チェックアウトの更新のたびに NZ Post の応答を待つことはありません。API のタイムアウトは 10 秒です。アクセストークンは有効期限が切れるまで保持され、拒否されたトークンは自動的に更新されます。
NZ Post が料金を返さない場合（API 未設定、エラー、住所が不完全、サービスが利用不可、NZD のレートがない）、お客様にはエラーは表示されません。国別の料金表の料金が使われ、次に予備の料金が使われます。固定料金がない場合は、配送方法が非表示になります。理由はログに記録されます。
OpenCart 4 では、お客様はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options のウィンドウで NZ Post のオプションを選択します。料金は OpenCart 3 と同じです。
この拡張機能は料金の計算のみを行います。送り状（配送ラベル）の作成、マニフェストの生成、集荷の予約、荷物の追跡、住所の検証は行わず、お客様が集配ポイント、私書箱（PO Box）、パーセルロッカーを選ぶこともできません。カートは 1 個の荷物として料金計算され、お客様にはサービスの一覧ではなく、NZ Post の料金 1 つが表示されます。
注文
NZ Post を使った注文が行われると、拡張機能は配送料の計算の元になった情報を保存します。Sales > Orders で注文を開くと、注文ページに NZ Post パネルが表示されます。パネルには NZ Post service（リアルタイム料金で計算された NZ Post のサービスと、そのコード）と、Price source（Live rate (NZ Post ShippingOptions API)、Fixed price、Free shipping のいずれか）が表示されます。料金や設定が後で変わっても、また配送方法がオフになっていても、パネルには注文時の値が表示されます。お客様にはサービス名は表示されません。
OpenCart 4 では、NZ Post パネルは History の上に表示されます。OpenCart 4 は、チェックアウトごとに注文を 1 つ保持し、購入者が再度確定するたびにその注文を更新します。保存されたサービスと料金の出所も一緒に更新されます。購入者がその注文を別の配送方法に切り替えると、注文の NZ Post のデータは削除されます。
ライセンスキー
この拡張機能は、vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox NZ Post は、Extensions > Extensions > Shipping > VibeFox NZ Post > Edit ページで、設定の上にある最初のブロックです。キーを License key に貼り付けて、Activate をクリックしてください。その後、ブロックにはキーがマスクされて表示され、ステータス（ライセンスの有効期限の日付やお使いのドメインなど）と、次のボタンが表示されます：Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）。その下には Product: opencart-shipping-nz-post の行と、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 のアカウントで枠を解放してください。
有効なキーがない場合、NZ Post はチェックアウト時にお客様に表示されず、料金も計算されません。同じブラウザで管理画面にログインしている管理者ユーザーには、ストアでこの配送方法が (unlicensed — visible to admins only) と表示された状態で引き続き見えるため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 ではこのプレビューは利用できません。ストアは管理画面のログインを認識しないため、有効なキーがない場合は全員にこの方法が非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると 7 日間非表示になります。既存の注文は影響を受けません。
ライセンスの期限が切れても、拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスが自動的に再確認されます。キーの入力後最初の 14 日間は 1 日に 1 回、その後は 1 週間に 1 回です。cron ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスのステータスは常に削除されます。
トラブルシューティング
チェックアウトに NZ Post が表示されない: ライセンスが有効であること、Enable NZ Post がオンであることを確認してください。Geo zone（または Ignore shipping zones と Countries）、重量の制限、Minimum order amount を確認してください。NZ Post が料金を返さない場合、配送方法は国別の料金または Fallback cost がある場合にのみ表示されます。商品の Requires Shipping が Yes に設定されていることも確認してください。
リアルタイム料金が表示されない: 拡張機能のページ上部の警告を確認してください。次に Debug log をオンにし、チェックアウトを再読み込みして Log の欄を確認してください。API のエラーは常にここに表示されます。ログには理由が示されます。Client ID または Client Secret の未入力、トークンの拒否、口座または発送データの不足、お客様の市または郵便番号が未入力、NZD のレートがない、料金を計算できるサービスがない、などです。問題を修正している間は、固定料金が使われます。
トークンのリクエストが失敗する: Client ID、Client Secret、Environment を確認してください。UAT の認証情報は本番環境では使えず、逆も同様です。
国内の料金が表示されないが、国際料金は機能する: ニュージーランド国内の料金には、Account number、Auth code または Site code、そして 4 桁の郵便番号を含む完全な発送元の住所が必要です。お客様は市と 4 桁の郵便番号を入力する必要があります。
ストアの通貨がニュージーランドドルではない: NZD のレート（NZD → (ご利用の通貨) rate の欄）を入力してください。固定料金は常にストアの既定通貨で設定されます。
送料に GST が二重に課税される: NZ Post の国内料金には 15% の GST が含まれています。配送方法に Tax class がある場合は、API prices を Excluding GST に設定してください。
変更後に料金が古く見える: 拡張機能のページで Save をクリックしてください。これでキャッシュされた NZ Post の料金とトークンが消去されます。
ページに「Warning: You do not have permission to modify VibeFox NZ Post!」と表示される: 管理者ユーザーのグループには設定の閲覧権限しかない可能性があります。System > Users > User Groups で、そのグループに extension/shipping/vfd_nz_post（OpenCart 3）または extension/vfd_nz_post/shipping/vfd_nz_post（OpenCart 4）の変更権限を付与してください。
開発者向け: ニュージーランドの配送先住所に送信される地区は、OpenCart のイベント vfd_nz_post/delivery_suburb（トリガー catalog/vfd_nz_post/delivery_suburb）で変更できます。NZ Post API のアドレスは設定 vfd_nzpt_api_url（テスト用）で置き換えられます。この設定は設定画面にはフィールドがありません。
アンインストール
Extensions > Extensions に移動し、種類 Shipping を選んで、VibeFox NZ Post の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンス状態は常に削除されます。OpenCart は常に Enable NZ Post、Sort order、Tax class、Geo zone をリセットします。キャッシュされた料金とトークンは常に削除され、注文ページの NZ Post パネルも表示されなくなります。Remove data on uninstall がオンの場合は、NZ Post の設定とデバッグログも削除されます。オフの場合は、その他の設定は保持され、拡張機能を再インストールしたときに再び使用されます。注文に保存された NZ Post の詳細は削除されることはなく、再インストール後に再び表示されます。既存の注文は、配送方法と送料をそのまま保持します。
OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧で VibeFox NZ Post の横にある Uninstall（オレンジ色の − ボタン）をクリックしてから、アップロードしたパッケージを削除するために Delete（赤いゴミ箱ボタン）をクリックしてください。
NZ Post は、それぞれの所有者の商標です。この拡張機能は NZ Post と提携しておらず、NZ Post による推奨も受けていません。