VibeFox PostNL for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 で動作確認済み）または 4.0.2 以降（4.1.0.3 で動作確認済み）。

PHP: 8.0 以降。

PostNL API キー（受け取りポイントのみ）: 受け取りポイントは PostNL Checkout API から読み込まれます。PostNL のビジネス顧客は、Mijn PostNL の My account > API beheren で API キーを確認できます。PostNL のサンドボックスには、別のサンドボックス用キーが必要です。自宅への配送オプションにはキーは不要です。

VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。

インストール

このダウンロードは、両方の OpenCart バージョン用のパッケージが入った zip ファイル 1 つです。コンピュータで解凍してください。README.txt、OpenCart 3 用パッケージ vfd_postnl-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ vfd_postnl.ocmod.zip が含まれています。お使いの OpenCart のバージョンのパッケージのみをインストールしてください。ライセンスキーは両方のバージョンで同じです。

OpenCart 3

1. 管理画面で Extensions > Installer を開き、Upload をクリックして、ファイル vfd_postnl-oc3-(version).ocmod.zip を選択します。本拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。Installer の代わりに、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。

2. Extensions > Extensions を開き、拡張機能の種類で Shipping を選択します。VibeFox PostNL を見つけて、Install（緑色の + ボタン）をクリックします。

3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。

4. Edit ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを入力し、Activate をクリックします（「ライセンスキー」を参照）。

5. PostNL pickup point および/または PostNL home address をオンにし、料金を入力します。受け取りポイントの場合は、PostNL の API key と Ship from (postcode) も入力してください（「設定」を参照）。Save をクリックします。

OpenCart 4

1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_postnl.ocmod.zip を選択します。ファイル名を変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から読み取るため、名前を変更したパッケージは動作しません。

2. パッケージは同じページのインストール済み拡張機能の一覧に表示されます。その横の Install（緑色の + ボタン）をクリックします。

3. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選択します。VibeFox PostNL を見つけ、Install（緑色の + ボタン）をクリックしてから、Edit（鉛筆のボタン）をクリックします。

4. ライセンスキーと設定は、OpenCart 3 の手順 4 と 5 と同じように入力します。設定ページとその項目は両方のバージョンで同じです。

インストール直後は、どちらかをオンにして保存するまで、両方のオプションが無効のままです。アンインストール後に拡張機能を再インストールすると、保持されていた PostNL の設定が再び使われます。

設定

すべての設定は拡張機能のページにあります: Extensions > Extensions > Shipping > VibeFox PostNL > Edit。セクションは左側に並んでいます。下部の Save ボタン 1 つで、ページを再読み込みせずにページ全体を保存できます。この拡張機能の変更権限を持つ管理者ユーザーだけが設定を保存できます。

値が正しくない場合は何も保存されず、ページに理由が表示されます。たとえば、オプション名が空である、64 文字を超える、または < > ; = # { } を含む、並び順が整数ではない、最小重量が最大重量を上回っている、税区分またはジオゾーンが無効である、などです。軽微な問題は注記付きで保存されます。無効な数値や負の数値は、その欄が空になり、無効な発送元郵便番号は空の状態で保存され、料金表の無効な料金は無視されます。

設定の上には、警告が表示されます。受け取りポイントの API キーや発送元郵便番号がない、サンドボックスがオンになっている、料金が設定されていない、直近の失敗した PostNL リクエストとその日付およびエラー、ストアに重量クラス「kg」がない、といった警告です。

一般

配送の種類ごとに、チェックアウトで独立したオプションになります。このページの設定は両方に適用されます。

PostNL pickup point: 受け取りポイントのオプションをオンまたはオフにします。購入者はチェックアウトで PostNL のポイントを選ぶ必要があります。オランダとベルギーの住所に対してのみ、かつ API キーがある場合にのみ提供されます。既定値: オフ。

Pickup point option name: チェックアウトで購入者に表示される名称。既定値: PostNL pickup point。必須、64 文字以内、< > ; = # { } を含まないこと。

PostNL home address: 自宅への配送オプションをオンまたはオフにします。ポイントは選択されません。料金が設定されているすべての国で機能します。既定値: オフ。

Home delivery option name: チェックアウトで購入者に表示される名称。既定値: PostNL。受け取りポイントの名称と同じルールが適用されます。

Sort order: チェックアウトの配送方法の中での PostNL の表示順。整数で入力します。

Tax class: 両方のオプションの税区分。税区分を指定すると、OpenCart が料金に税金を加算します。No tax は、料金が確定額であることを意味します。

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 をクリックすると、保存されたキーが削除されます。その後、受け取りポイントのオプションは提供されなくなります。

Sandbox: PostNL のサンドボックス（api-sandbox.postnl.nl）とサンドボックス用の API キーを使用します。この場合、購入者にはテスト用の受け取りポイントが表示されます。本番運用中のストアではオフのままにしてください。

Ship from (country): 荷物を PostNL に引き渡す国です。オランダまたはベルギーを選びます。PostNL は集荷日の算出に発送元住所を使用します。インストール時は、ストアの国がオランダまたはベルギーであればその国に、それ以外の場合はオランダに設定されます。

Ship from (postcode): 発送元の郵便番号です。例: オランダの 1234AB、ベルギーの 1000。受け取りポイントには必須です。OpenCart にはストアの郵便番号がないため、ストアの住所からは取得されません。無効な郵便番号は、警告付きで空の状態で保存されます。

API キー、サンドボックスの設定、発送元住所を変更すると、キャッシュされた受け取りポイントのリストと直近の API エラーが削除されます。

料金（ストアの既定通貨、税抜き）

料金は両方のオプションに適用されます。PostNL には公開された料金 API がないため、本拡張機能はリアルタイムの料金を取得しません。別の通貨で支払う購入者には、OpenCart がストアの為替レートで料金を換算して表示します。

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」のどちらも使えます。料金のない行は保存時に削除されます。同じ国が 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): 重いカートではオプションを隠します。PostNL の荷物は Benelux で最大 30 kg です。0 は制限なしを意味します。空欄にすると 30 kg が適用されます。Ignore shipping zones がオンの場合は制限なしになります。

すべての金額と重量は、小数点としてカンマを受け付けます。

利用可能条件

Geo zone: PostNL を、このジオゾーン内の住所に対してのみ提供します。All zones（既定）は制限なしを意味します。Ignore shipping zones がオンの場合、ジオゾーンは確認されません。ジオゾーンは System > Localisation > Geo Zones で管理します。

Ignore shipping zones: オンの場合、ジオゾーンは確認されず、下で選択した国に対して PostNL が提供されます（リストが空の場合はすべての国）。オフの場合、ジオゾーンだけが有効になります。

Countries: このモードで対象とする仕向け国です。空欄にするとすべての国を許可します。この欄は Ignore shipping zones がオンの場合にのみ使われます。受け取りポイントのオプションは引き続きオランダとベルギーに対してのみ提供されます。

詳細設定

Debug log: デバッグメッセージを storage/logs/vfd_ptnl_debug.log.php に書き込みます（OpenCart 4 では system/storage/logs/vfd_ptnl_debug.log.php）。このファイルは Web からは読み取れません。API エラーと、有効な受け取りポイントのない注文は、常に記録されます。API キーや購入者のデータは書き込まれません。作業が終わったら、ログをオフにしてください。ファイルが 5 MB に達すると、新しいログが開始されます。

Log: デバッグログのサイズと最新の記録を表示します。Clear log をクリックすると、ログを消去できます。

Remove data on uninstall: オンの場合、拡張機能をアンインストールすると、PostNL の設定とログが削除されます。キャッシュされたポイントのリストは常に削除されます。注文に保存された受け取りポイントは、常に保持されます。

インポート / エクスポート

Export: Download JSON をクリックすると、設定を JSON ファイルとして保存できます。API キーはエクスポートされません。

Import: 以前にエクスポートした JSON を貼り付けて Import をクリックすると、設定が復元されます。たとえば別のストアに移す場合に使えます。値は通常の保存と同じように確認されます。保存済みの API キーは保持されます。

チェックアウトでの動作

OpenCart が配送方法を表示するとき、拡張機能に PostNL の各オプションの料金を問い合わせます。Ignore shipping zones がオンの場合、ジオゾーンに関係なく、許可された国に対してのみ PostNL が提供されます。それ以外で Geo zone が設定されている場合は、住所がそのゾーン内にある必要があります。Requires Shipping が Yes の商品だけが計算に含まれます。ほかの商品は重量に加算されず、小計にも含まれません。拡張機能は、カートの重量と最小小計を確認します。次に、国と重量クラスに対応する料金を料金表から、または他の国向けの料金を取得します。料金がない場合、そのオプションは非表示になります。カートの小計が Free shipping from に達すると、料金は 0 になります。料金は、購入者の通貨で、選択された Tax class の税込みで表示されます。

受け取りポイントのオプションは、オランダとベルギーの住所に対してのみ、かつ API キーがある場合にのみ提供されます。配送先住所に完全な郵便番号がある場合、拡張機能は PostNL Checkout API に最寄りの受け取りポイント 3 か所を問い合わせます。購入者の郵便番号、番地と番号、市区町村と国、そして貴店の発送元住所を送信します。自宅への配送オプションでは何も送信されません。PostNL に接続できない場合、またはその住所にポイントがない場合は、受け取りポイントのオプションが非表示になり、自宅への配送は引き続き利用できます。API のタイムアウトは 12 秒です。

ポイントのリストは、住所ごとに 6 時間キャッシュされ、「ポイントなし」の応答は 1 時間キャッシュされます。失敗したリクエストは 10 分間キャッシュされるため、障害があってもチェックアウトの更新のたびに遅くなることはありません。キャッシュは拡張機能独自のデータベーステーブルに保存されます。直近のエラーは、次に成功するリクエストまで拡張機能のページに表示されます。

本拡張機能は PostNL のリアルタイム料金を取得せず、配送ラベル、バーコード、追跡、返品、事前通知の作成も行いません。配達日、夜間配達、午前配達のオプションはありません。保存された受け取りポイントを使って、Mijn PostNL またはほかの PostNL のツールで発送を作成してください。

OpenCart 4 では、購入者はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options のウィンドウで PostNL のオプションを選択します。料金は OpenCart 3 と同じです。

受け取りポイント

配送先住所がオランダまたはベルギーにある場合、受け取りポイントのオプションの下に、最寄りの 3 か所を示す PostNL pickup point のリストが表示されます。表示内容は、会社名、住所、距離で、最も近いものが先頭です。ページは PostNL の応答を待つことはありません。リストがまだキャッシュにない場合は、オプションを選択した時点で読み込まれます。完全な郵便番号が入力されるまで、購入者には "Enter your postcode (for example 1234 AB) to see PostNL pickup points."（ベルギーの場合は 4 桁）と表示されます。選んだポイントは、すぐにチェックアウト用に保存されます。

ポイントは必須です。購入者が配送方法の手順で Continue をクリックすると、サーバーは配送先住所向けの PostNL のリストに対してポイントを確認します。ポイントを選んでいない場合、購入者には "Please choose a PostNL pickup point." と表示されます。ポイントがリストにない場合は "The chosen PostNL pickup point is not available for this address. Please choose it again." と表示されます。PostNL に接続できない場合は "PostNL pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method." と表示されます。別の住所向けに選ばれたポイントは、注文には決して使われません。注文とともに保存される名称と住所は、ブラウザではなく PostNL から取得されます。

注文ページ、メール、請求書: ポイントは注文の配送方法に追加されます。たとえば "PostNL pickup point: 名称, 住所"（受け取りポイントのオプション名、その後にポイント）のようになります（128 文字まで。OpenCart 4 では 255 文字まで）。OpenCart が配送方法を表示する場所、つまり購入者の注文履歴、注文メール、請求書、Sales > Orders に表示されます。

管理画面の注文ページ: Sales > Orders の注文ページには、履歴の上に PostNL pickup point のパネルが表示され、ポイント、Location code、Partner ID が示されます。これは、保存されたポイントがある注文に対してのみ表示され、拡張機能を無効にした後も同様です。

OpenCart 4 では、ポイントのリストは Shipping method options のウィンドウの PostNL pickup point オプションの下に表示され、ウィンドウを開くたびに読み込み直されます。ワンページのチェックアウトでは住所が変わることがあるためです。ウィンドウの Continue ボタンは、有効なポイントがないと先に進めず、同じメッセージが表示されます。OpenCart 4 は、チェックアウトごとに注文を 1 つ保持し、購入者が再度確定するたびにその注文を更新します。注文のポイントも一緒に更新されます。

ライセンスキー

本拡張機能は、vibefox.net で入手した VibeFox ライセンスキーを使用します。ライセンスブロック License — VibeFox PostNL は、Extensions > Extensions > Shipping > VibeFox PostNL > Edit の設定の上にある最初のブロックです。キーを License key に入力し、Activate をクリックしてください。その後、ブロックにはマスクされたキー、ステータス（ライセンスの有効期限日やお使いのドメインなど）が表示され、Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）のボタンが表示されます。その下には Product: opencart-shipping-postnl の行と、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 のアカウントで枠を解放してください。

有効なキーがない場合、PostNL の配送オプションはチェックアウトで購入者に表示されず、料金も計算されません。同じブラウザで管理画面にログインしている管理者ユーザーには、ストアでこれらのオプションが (unlicensed — visible to admins only) と表示された状態で引き続き見えるため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 ではこのプレビューは利用できません。ストアは管理画面のログインを認識しないため、有効なキーがない場合は全員にこのオプションが非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると 7 日間非表示になります。既存の注文は影響を受けません。

ライセンスの期限が切れても、拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスが自動的に再確認されます。キーの入力後最初の 14 日間は 1 日に 1 回、その後は 1 週間に 1 回です。cron ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスのステータスは常に削除されます。

トラブルシューティング

チェックアウトに PostNL が表示されない: ライセンスが有効であること、PostNL pickup point または PostNL home address がオンであることを確認してください。Geo zone（または Ignore shipping zones がオンで、その国が許可されていること）、その国に料金が設定されていること、重量の上限と Minimum subtotal を確認してください。商品の Requires Shipping が Yes になっていることも確認してください。

受け取りポイントのオプションが表示されない: オランダとベルギーの住所に対してのみ、API キー、発送元郵便番号、料金がある場合にのみ、かつ購入者の郵便番号に対して PostNL がポイントを返した場合にのみ表示されます。拡張機能ページ上部の警告と Log 欄を確認してください。エラーは常に記録されます。詳細を見るには Debug log をオンにしてください。

"PostNL pickup points cannot be loaded right now": PostNL に接続できない、API キーが拒否された、または発送元郵便番号がないことを示しています。拡張機能のページには直近のエラーが表示されます。サンドボックスのキーは Sandbox がオンのときだけ、本番のキーはオフのときだけ機能します。

購入者にテスト用の受け取りポイントが表示される: Sandbox をオフにしてください。

商品の重量が正しくないように見える: 拡張機能のページに、ストアに重量クラス「kg」がないという警告が表示される場合は、System > Localisation > Weight Classes を確認してください。商品の重量は、そのクラスの単位名に基づいて換算されます。不明な単位はキログラムとして読み取られます。

ページに "Warning: You do not have permission to modify VibeFox PostNL!" と表示される: 管理者ユーザーグループは設定を表示するだけの権限になっている可能性があります。System > Users > User Groups で、extension/shipping/vfd_postnl（OpenCart 3）または extension/vfd_postnl/shipping/vfd_postnl（OpenCart 4）の変更権限をそのグループに付与してください。

開発者向け: PostNL API のアドレスは、設定 vfd_ptnl_api_url（テスト用）で置き換えることができます。設定ページにはこの項目の入力欄はありません。

アンインストール

Extensions > Extensions を開き、種類 Shipping を選択して、VibeFox PostNL の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスのステータスは常に削除されます。OpenCart は常に拡張機能の状態、Sort order、Tax class、Geo zone をリセットします。キャッシュされた受け取りポイントのリストと直近の API エラーは、常に削除されます。Remove data on uninstall がオンの場合、PostNL の設定、デバッグログ、そして一度も注文にならなかったチェックアウトのポイントも削除されます。オフの場合、ほかの設定は保持され、拡張機能を再インストールすると再び使われます。既存の注文は、配送方法、費用、保存された受け取りポイントを保持します。

OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧で VibeFox PostNL の横にある Uninstall（オレンジ色の − ボタン）をクリックしてから、アップロードしたパッケージを削除するために Delete（赤いゴミ箱ボタン）をクリックしてください。

PostNL は、それぞれの所有者の商標です。本拡張機能は PostNL と提携しておらず、PostNL による承認も受けていません。