VibeFox PostNL for PrestaShop — ヘルプ
要件
PrestaShop: 8.0 から 9.x、Classic または Hummingbird テーマ（またはそれらをベースとしたテーマ）。
PHP: 8.0 以降。モジュールは古い PHP バージョンではインストールを拒否します。
PostNL API キー（ピックアップポイントのみ）: ピックアップポイントは PostNL Checkout API から読み込まれます。PostNL のビジネス顧客は、Mijn PostNL の My account > API beheren で API キーを確認できます。PostNL サンドボックスには別途サンドボックス用のキーが必要です。自宅への配送の配送業者にはキーは不要です。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
1. 管理画面で Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックします。後で行う場合は、モジュール一覧から VibeFox PostNL を探し、Configure をクリックします。
3. Configure ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを入力し、Activate をクリックします（「ライセンスキー」を参照）。
4. 料金を入力します。ピックアップポイントの場合は、PostNL の API key と Ship from (postcode) も入力します（設定を参照）。Save をクリックします。
インストール時にモジュールは 2 つの配送業者を作成します。PostNL pickup point は配送時間テキスト Delivery to a PostNL pickup point を、PostNL は PostNL delivery to the home address を持ちます。どちらもオランダとベルギーのゾーン、およびすべての顧客グループに紐付けられます。ゾーンの追加や、顧客グループ、配送時間、ロゴ、サイズ制限の変更は Shipping > Carriers で行えます。そこで料金は設定しないでください。料金は常にモジュールから取得されます。
設定
すべての設定はモジュールのページにあります: Modules > Module Manager > VibeFox PostNL > Configure。各セクションには独自の Save ボタンがあり、ページ全体を保存します。WooCommerce では、1 つの方法を配送タイプごとに 1 回ずつ、計 2 回ゾーンに追加します。PrestaShop では、配送タイプごとに独自の名前、ステータス、ゾーンを持つ配送業者になります。
設定の上には警告が表示されます。ピックアップポイントの API キーまたは発送元郵便番号が未入力、サンドボックスが有効、料金が未設定、最後に失敗した PostNL リクエスト（日付とエラー付き）、モジュールが認識しないショップの重量単位、削除された配送業者などです。
一般
PostNL pickup point: ピックアップポイント配送業者のオン／オフを切り替えます。購入者はチェックアウトで PostNL ポイントを選ぶ必要があります。オランダとベルギーの住所に対してのみ、API キーがある場合にのみ提供されます。これは Shipping > Carriers の配送業者ステータスと同じスイッチです。
Pickup point carrier name: チェックアウトで購入者に表示される名前です。既定値: PostNL pickup point。必須です。
PostNL home address: 自宅への配送の配送業者のオン／オフを切り替えます。ポイントは選択されません。料金が設定されたすべての国で利用できます。配送業者のステータスと同じスイッチです。
Home delivery carrier name: チェックアウトで購入者に表示される名前です。既定値: PostNL。必須です。
Tax status: 両方の配送業者の税ルールです。Taxable のルールでは、そのルールの配送税が料金に上乗せされます。None の場合、料金は確定価格です。
PostNL API（ピックアップポイント）（自宅への配送には不要）
API key: Mijn PostNL（My account > API beheren）で取得した PostNL API キーです。"apikey" ヘッダーで PostNL に送信され、購入者に表示されたり、ログに書き込まれたりすることはありません。保存後、この欄は空のまま Saved - leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。
Remove the saved API key: チェックを入れて Save をクリックすると、保存された API キーが削除されます。その後、ピックアップポイント配送業者は提供されなくなります。
Sandbox: PostNL サンドボックス（api-sandbox.postnl.nl）とサンドボックス用 API キーを使用します。この場合、購入者にはテスト用のピックアップポイントが表示されます。本番ショップではオフのままにしてください。
Ship from (country): 荷物を PostNL に引き渡す国です。Netherlands または Belgium。既定値: Netherlands。PostNL は集荷日の算出に発送元住所を使用します。
Ship from (postcode): 発送元の郵便番号です。例: オランダなら 1234AB、ベルギーなら 1000。ショップが同じ国にある場合は、空欄のままにすると Shop Parameters > Contact > Stores のショップ郵便番号が使われます。無効な郵便番号は警告付きで空欄として保存されます。API キー、サンドボックス設定、または発送元住所を変更すると、キャッシュされたピックアップポイントの一覧と最後の API エラーは消去されます。
料金（ショップの既定通貨、税抜き）
料金は両方の配送業者に適用されます。PostNL には公開されたレート API がないため、本モジュールはリアルタイムの料金を取得しません。別の通貨で支払う購入者の場合、PrestaShop がショップの為替レートで料金を換算します。
Price per country: 配送先の国ごとに 1 行です。+ Add country をクリックすると行が追加され、ゴミ箱アイコンで削除できます。自身の行を持たないすべての国をカバーする行には * All other countries を選びます。各行には Price と、カート重量による任意の重量クラスがあります。XS は 1 kg まで、S は 2 kg まで、M は 3 kg まで、L は 5 kg まで、XL は 5 kg を超える場合です。重量クラスの料金は Price より優先されます。空欄にすると Price が使われます。Price が 0 の場合は送料無料を意味します。"6.95"、"6,95"、および "1.234,50" や "1,234.50" のような桁区切り付きの金額も使用できます。空の行と無効な国コードは保存時に削除されます。同じ国が 2 回現れた場合は、最初の行が残ります。無効な料金は警告付きで無視されます。
Calculation: Per order は料金を 1 回だけ請求します。Per item (price x quantity) は、配送が必要な商品数を掛けた金額になります。
Price for other countries: 料金表に、その国の行も * の行もない場合に使われます。空欄にすると、その国では配送業者が非表示になります。
条件
Free shipping from: 送料無料になるカート小計です（配送が必要な商品、税抜き、割引後）。料金が見つかった場合にのみ適用されます。空欄にすると、送料無料は提供されません。
Minimum subtotal: カート小計がこの金額以上の場合にのみ配送業者を表示します。空欄にすると常に表示されます。
Minimum weight (kg): カートの重量がこれより軽い場合に配送業者を非表示にします。商品の重量はショップの重量単位から換算されます。空欄にすると上限はありません。
Maximum weight (kg): より重いカートの場合に配送業者を非表示にします。既定値: 30（PostNL の荷物はベネルクスで最大 30 kg）。0 は上限なしを意味します。空欄にすると、配送業者のゾーンでは 30 kg が適用され、上限なしは Ignore zones で到達できる国にのみ適用されます。最小重量が最大重量を超える場合はエラーで拒否されます。配送業者が決して表示されなくなるためです。
すべての金額と重量は、桁区切りを含めて小数点のカンマを受け付けます。無効な数値や負の数値は警告付きで無視され、欄は空欄として保存されます。
配送ゾーンなしでの利用可否
通常、配送業者は Shipping > Carriers で紐付けられた配送ゾーンで提供されます。
Ignore zones: PostNL のゾーンに含まれていない以下の国でも PostNL を提供します。その場合、配送業者は有効なすべてのゾーンに紐付けられます。後から作成したゾーンも含まれます。再度オフにすると、配送業者は以前のゾーンに戻ります。
Countries: このモードでの配送先の国です。空欄にするとすべての国を許可します。この欄は Ignore zones がオンの場合にのみ使用されます。これらの国では両方の配送業者を提供できます。ただし、ピックアップポイント配送業者はオランダとベルギーにのみ提供されます。
詳細設定
Debug log: モジュールフォルダ内の logs/vfd_ptnl_debug.log.php にデバッグメッセージを書き込みます。このファイルは Web からは開けません。API エラーは常に記録されます。API キーや購入者のデータは書き込まれません。作業が終わったらログをオフにしてください。
Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると空になります。
Remove data on uninstall: オンの場合、モジュールをアンインストールすると PostNL の設定と配送業者が削除されます。オフの場合、アンインストールでは配送業者をオフにするだけです。注文に保存されたピックアップポイントは常に保持されます。
チェックアウト時の動作
配送のステップで PrestaShop は、各 PostNL 配送業者の料金をモジュールに問い合わせます。対象は実物の商品のみです。バーチャル商品は重量を加えず、小計にも含まれません。モジュールはカート重量と最低小計という条件を確認します。次に、国と重量クラスに応じて料金表から料金を取得するか、その他の国の料金を使用します。料金がなければ配送業者は非表示になります。カート小計が Free shipping from に達した場合、料金は 0 です。
ピックアップポイント配送業者は、オランダとベルギーの住所に対してのみ、API キーがある場合にのみ提供されます。配送先住所に有効な郵便番号がある場合、モジュールは PostNL Checkout API に、最寄りの 3 つのピックアップポイントを問い合わせます。購入者の郵便番号、番地、番地番号、市区町村、国と、発送元住所を送信します。自宅への配送の配送業者には何も送信されません。PostNL に接続できない場合、または住所に対するポイントがない場合、ピックアップポイント配送業者は非表示になり、自宅への配送は引き続き利用できます。API のタイムアウトは 12 秒です。
ポイントの一覧は郵便番号ごとに 6 時間、「ポイントなし」の応答は 1 時間キャッシュされます。失敗したリクエストは 10 分間キャッシュされるため、障害のたびにチェックアウトの更新が遅くなることはありません。最後のエラーはモジュールのページに表示されます。
注文が入った後に Shipping > Carriers で配送業者を編集すると、PrestaShop はそれを新しい配送業者のバージョンとして保存します。モジュールは新しいバージョンに自動的に従います。
モジュールは PostNL のリアルタイム料金を取得せず、配送ラベル、バーコード、track and trace、返品、事前通知を作成しません。配達日、夜間配達、午前配達のオプションもありません。保存されたピックアップポイントを使って、Mijn PostNL または他の PostNL ツールで発送を作成してください。
ピックアップポイント
購入者がピックアップポイント配送業者を選択すると、その下に最寄りの 3 つのポイントを示す PostNL pickup point のリストが表示されます。表示内容は、会社名、住所、距離です。ページは PostNL を待つことはありません。リストがまだキャッシュされていない場合は、配送業者を選択した時点で読み込まれます。完全な郵便番号を入力する前、購入者には「PostNL ピックアップポイントを確認するには、郵便番号（例: 1234 AB）を入力してください。」と表示されます（ベルギーの場合は 4 桁）。選択したポイントはカートに保存され、チェックアウトが更新されても保持されます。
ポイントの選択は必須です。選択しないと購入者は先に進めず、「PostNL ピックアップポイントを選択してください。」と表示されます。購入者が Continue をクリックすると、サーバーは配送先住所について PostNL のリストと照合します。リストにない場合、購入者には「選択された PostNL ピックアップポイントは、この住所では利用できません。もう一度選択してください。」と表示されます。PostNL に接続できない場合は、「現在 PostNL ピックアップポイントを読み込めません。数分後にもう一度お試しいただくか、別の配送方法をお選びください。」と表示されます。別の住所向けに選択されたポイントが注文に使われることはありません。注文とともに保存される名前と住所は、ブラウザではなく PostNL から取得されます。
管理画面の注文ページ: 名前と住所、Location code、Partner ID を含む PostNL pickup point ブロックです。
注文確認ページと注文詳細ページ: 名前と住所を含む PostNL pickup point です。
注文メール: 注文確認メールでは、配送業者名にポイントの名前と住所が追加されます。ショップの新規注文メール（Mail alerts モジュール）にはロケーションコードも表示されます。
ライセンスキー
本モジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox PostNL は、Modules > Module Manager > VibeFox PostNL > Configure ページで設定より上にある最初のブロックです。キーを License key に入力し、Activate をクリックします。その後、ブロックにはキーがマスクされた状態で表示され、ステータス（ライセンスの有効期限日とドメインなど）と、ボタン Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このショップからキーを削除）が表示されます。その下に Product: presta-shipping-postnl の行と、Manage licenses and domains in your account のリンクがあり、vibefox.net のアカウントが開きます。キーを変更できるのは、このモジュールの Configure 権限を持つスタッフだけです。ブロックのテキストは管理画面の言語に従います（英語とロシア語を含みます）。
キーが受け付けられない場合、ブロックにその理由が表示されます。例：Key not found、This key belongs to another product、Domain limit reached、または日付付きの License expired on。ショップのアドレスを変更した後、またはアカウントでドメインの枠を解放した後に、Check now をクリックします。ライセンスサーバーに接続できない場合、モジュールは最後に確認できたステータスで動作を続けます。
1 つのキーは 1 つのドメインで使用できます。メインショップのドメインで、マルチストア構成でも同様です。ショップからキーを削除しても、ドメインの枠は解放されません。枠は vibefox.net のアカウントで解放してください。
有効なキーがない場合、PostNL の配送業者はチェックアウトで購入者に表示されず、配送料も計算されません。PrestaShop のストアフロントは、バックオフィスにログインしていることを認識しないため、配送業者はあなたにも表示されません。キーを購入する前にモジュールを設定することはできますが、チェックアウトでのテストはできません。Modules > Module Manager の Alerts タブに通知が表示されます。既存の注文には影響しません。
ライセンスの期限が切れても、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。バックオフィスで作業している間、ステータスは自動的に再確認されます。キー入力後の最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールをアンインストールすると、ライセンスキーとライセンスステータスは常に削除されます。Reset はデータを削除しないため、キーとステータスは保持されます。
トラブルシューティング
チェックアウトに PostNL が表示されない: ライセンスが有効で、配送業者のスイッチがオンになっているか確認してください。Shipping > Carriers で、配送業者が購入者の国のゾーンと購入者の顧客グループをカバーしているか確認します（または Ignore zones がオンで、その国が許可されているか）。その国の料金、重量制限、Minimum subtotal が設定されているか確認してください。商品ページで、商品が特定の配送業者に制限されている場合もあります。
ピックアップポイント配送業者が表示されない: オランダとベルギーの住所に対してのみ、API キー、発送元郵便番号、料金がある場合にのみ表示され、さらに PostNL が購入者の郵便番号についてポイントを返した場合にのみ表示されます。モジュールページ上部の警告と Log 欄を確認してください。エラーは常に記録されます。詳細は Debug log をオンにして確認してください。
"PostNL pickup points cannot be loaded right now": PostNL に接続できない、API キーが拒否された、または発送元郵便番号がないことを示します。モジュールページには最後のエラーが表示されます。サンドボックスのキーは Sandbox がオンの場合にのみ有効で、本番のキーはオフの場合にのみ有効です。
購入者にテスト用のピックアップポイントが表示される: Sandbox をオフにしてください。
商品の重量が正しくないように見える: モジュールページにショップの重量単位が不明だという警告が表示される場合は、International > Localization の Local units で標準の単位（kg、g、lb、oz のいずれか）を設定してください。それまでは、商品の重量は kg として読み込まれます。
ページに PostNL 配送業者が見つからないと表示される: 配送業者が Shipping > Carriers で削除されています。Modules > Module Manager でモジュールをリセットすると、再作成されます。リセットしても、設定と配送業者のステータスは保持されます。
アンインストール
Modules > Module Manager に移動し、VibeFox PostNL の横のメニューを開いて Uninstall を選びます。ライセンスキーとライセンスステータスは常に削除されます。キャッシュされたピックアップポイントの一覧と最後の API エラーは、常に削除されます。Remove data on uninstall がオンの場合は、配送業者が削除され（注文の履歴は残ります）、設定とログも削除されます。オフの場合は、配送業者をオフにするだけで、すべての設定は保持されます。モジュールを再インストールすると、配送業者は以前のステータスに戻ります。既存の注文は配送の行と保存されたピックアップポイントを保持します。
PostNL は各所有者の商標です。本モジュールは PostNL と提携しておらず、PostNL の承認も受けていません。