VibeFox DHL Packstation for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 で動作確認済み）または 4.0.2 以降（4.1.0.3 で動作確認済み）。受取拠点の選択画面は、OpenCart の標準のチェックアウトで動作します。

PHP: 8.0 以降。

DHL API キー: 拠点の一覧は、無料の DHL Location Finder API から取得されます。DHL Developer Portal（developer.dhl.com）に登録し、アプリを作成して「Location Finder - Unified」API を追加し、アプリの API キーをコピーしてください。この API に DHL との法人契約は必要ありません。キーがないと、チェックアウトでこの配送方法は非表示になります。DHL アプリのリクエスト上限にご注意ください。郵便番号や都市の検索を新たに行うたびに、API リクエストが 1 回発生します。

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

インストール

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

OpenCart 3

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

2. Extensions > Extensions に移動し、拡張機能のタイプとして Shipping を選択します。VibeFox DHL Packstation を見つけ、Install（緑色の + ボタン）をクリックします。

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

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

5. DHL API キーを貼り付け、Save をクリックしてから、Test API key をクリックします。拠点の種類を選択し、国ごとの料金を入力します（Configuration を参照）。Enable/Disable をオンにして、Save をクリックします。

OpenCart 4

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

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

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

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

インストール後は、Enable/Disable をオンにして保存するまで、この配送方法はオフのままです。既定の料金表には、ドイツとオーストリアの料金と、その他の国の料金が含まれています。アンインストール後に拡張機能を再インストールした場合は、残しておいた設定が再び使用されます。

設定

すべての設定は拡張機能のページにあります: Extensions > Extensions > Shipping > VibeFox DHL Packstation > Edit。セクションは左側に並んでいます。Save ボタンを 1 つ押すと、ページを再読み込みせずにページ全体を保存します。保存のたびに受取拠点のキャッシュが消去されます。フィールドにエラーがある場合（名前が無効または 64 文字を超える、半径や結果数が整数ではない、数値が無効または負、Min weight (kg) が Max weight (kg) より大きい、並び順が整数ではない、税区分や地域ゾーンが不明）、何も保存されず、エラーが表示されます。この拡張機能の変更権限を持つ管理者ユーザーだけが設定を保存できます。

ページ上部の警告は、DHL API キーが空のとき、拠点の種類が 1 つも有効になっていないとき（どちらの場合も、チェックアウトでこの配送方法は表示されません）、国ごとの料金の入力が CC:PRICE 形式になっていないとき（これらの入力は無視されます）、System > Localisation > Weight Classes に単位 kg の重量クラスがないときに表示されます（その場合、商品の重量は、クラスの単位名に従って読み取られます：kg、g、lb、oz。不明な単位は kg として扱われます）。

一般

設定はすべての地域ゾーンに適用されます。

Enable/Disable: チェックアウトで DHL Packstation を有効にします。既定値: off。

Name: 購入者に表示される配送方法の名前。既定値: DHL Packstation。必須、最大 64 文字。ただし次の文字は使用できません: < > ; = # { }。

Tax Class: 配送料の税区分、または --- None ---（既定）。OpenCart は、この税を下記の料金に加算します。--- None --- の場合、料金は確定価格です。

Sort Order: 配送方法の中での DHL Packstation の表示順。整数。

DHL Location Finder API

DHL API key: developer.dhl.com でのアプリの「API Key」。これがないと、チェックアウトでこの配送方法は非表示になります。保存後、フィールドは空のままになり、Saved - leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。

Remove the saved API key: キーが保存されているときに表示されます。チェックボックスをオンにして保存すると、保存されたキーが削除されます。

Connection test: Test API key ボタンは、保存されたキーを使って 53113 Bonn 付近の拠点を検索し、拠点のキャッシュを消去します。先に設定を保存してください。見つかった拠点の数（Connected: … DHL locations found near 53113 Bonn.）、DHL がキーを拒否したこと（401/403）、または API が正しく応答しなかったこと（詳細はデバッグログ）が表示されます。

受取拠点

チェックアウトでは、購入者の配送先郵便番号の近くの拠点が表示され、別の郵便番号や都市を検索できます。

Location types: 購入者が選択できる DHL の拠点: Packstation (parcel locker)、Post Office (Postfiliale)、DHL Parcel Shop (Paketshop)。既定では 3 つすべてが有効です。1 つも選択されていない場合、この配送方法は非表示になります。Packstation の場合、購入者は DHL Postnummer を入力する必要があります。

Search radius (meters): 検索した郵便番号や都市の周囲の半径。既定値: 5000。整数。100 未満または 25000 m（DHL の上限）を超える値は、その上限に設定されます。

Max results: 検索ごとに表示される拠点の最大数。既定値: 20。整数。DHL は最大 50 まで許可しており、それより大きい値は 50 に減らされます。

Shipping address: 選択された拠点を注文の配送先住所として使用します。既定で有効です。住所の 1 行目は、たとえば「Packstation 105」（郵便局または Parcel Shop の場合は「Postfiliale 502」）になり、2 行目には「Postnummer」と番号、そして拠点の郵便番号、都市、国が入ります。これにより、注文から印刷されたラベルが正しい場所に届きます。氏名、会社名、電話番号は購入者の住所から取得されます。地域（都道府県）は空になります。購入者のアドレス帳は変更されません。

料金（セクションのタイトルにはストアの既定の通貨が表示されます）

Country prices: 届け先の国ごとの料金。ストアの既定の通貨、税抜き、CC:PRICE 形式で、カンマまたは改行で区切ります。既定値: DE:4.99, AT:5.99。小数点のカンマ（DE:4,99）も使用できます。

Other countries: Country prices にない届け先の国の料金。既定値: 5.99。その国の配送方法を非表示にするには、空欄のままにします。

Calculation: Per order（既定）は料金を 1 回だけ請求します。Per item (price x quantity) は、カート内の商品数を掛けます。

Free shipping from: 配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額に達すると、この配送が無料になります。常に有料にする場合は空欄のままにします。

利用可否

Min weight (kg): カートの最小重量。商品の重量は、その重量クラスから換算されます。0 は制限なし（既定）を意味します。

Max weight (kg): カートの重量がこの値を超えると、この配送方法は非表示になります。既定値: 31.5（Packstation は最大 31.5 kg の荷物を受け付けるため）。0 は制限なしを意味します。

Minimum subtotal: 配送が必要な商品の小計（クーポン適用後、税抜き）がこの値以上の場合にのみ、この配送方法を表示します。常に表示する場合は空欄のままにします。

Geo Zone: この地域ゾーンにのみ、この配送方法を提供します。All Zones（既定）は制限なしを意味します。地域ゾーンは System > Localisation > Geo Zones で管理します。Ignore shipping zones を使用する場合は使われません。

Ignore shipping zones: オンにすると、住所の地域ゾーンに関係なく、下記の国に対してこの配送方法を提供します（リストが空の場合はすべての国）。

Countries (ignore zones): このモードの届け先の国。Ignore shipping zones と組み合わせた場合にのみ使用されます。

詳細設定

Debug log: API リクエストとチェックアウトの手順を storage/logs/vfd_dhlp_debug.log.php（OpenCart 4 では system/storage/logs/vfd_dhlp_debug.log.php）に書き込みます。このファイルは Web から読み取ることはできません。この設定がオフでも、API のエラーは常に記録されます。API キー、Postnummer、お客様の住所は書き込まれることはありません。ファイルが 5 MB に達すると、vfd_dhlp_debug.old.log.php に移動され、新しいログが開始されます。

Log: デバッグログのサイズと最新のエントリを表示します。Clear log をクリックすると空になります。

Remove data on uninstall: オンにすると、拡張機能のアンインストール時に、設定、キャッシュされた検索結果、ログ、未完了のチェックアウトの拠点が削除されます。選択された拠点は注文に残ります。オフ（既定）の場合は、再インストールに備えてすべて保持されます。

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

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

Import: 以前にエクスポートした JSON を貼り付け、Import をクリックして設定を復元します（別のストアでの復元などに使用できます）。値は通常の保存と同様に確認されます。保存された API キーは保持されます。

チェックアウトでの動作

OpenCart が配送方法を表示するとき、拡張機能に DHL Packstation の料金を問い合わせます。Geo Zone が設定されていて（かつ Ignore shipping zones がオフの場合）、住所がその外にあれば、この配送方法は提供されません。Requires Shipping が Yes に設定されている商品だけが対象になります。それ以外の商品は重量に加算されず、小計にも含まれません。拡張機能は、API キーと少なくとも 1 つの拠点の種類が設定されていること、許可された国（Ignore shipping zones の場合）、カートの重量、最小小計を確認します。その後、届け先の国の料金（または他の国の料金）を取得し、小計が十分に高ければ送料無料を適用します。小計は、配送が必要な商品の価格で、クーポン割引後、税抜きの金額です。料金は拠点に依存せず、料金の計算のために DHL へリクエストが送信されることはありません。料金はストアの既定の通貨で計算され、選択した Tax Class の税とともに、購入者の通貨で表示されます。

この拡張機能は、DHL の荷物の作成、ラベルの印刷、荷物の追跡は行いません。DHL の法人向けカスタマーポータルまたはラベルツールを使用してください。Shipping address を有効にすると、注文にはすでに Packstation の住所と Postnummer が含まれています。この拡張機能は DHL のリアルタイム料金を計算せず、地図も表示しません。Packstation の番号を手動で入力する機能はありません。

受取拠点

購入者が配送方法の手順で DHL Packstation を選択すると、方法の下に選択画面が表示されます。配送先の郵便番号と都市の近くにある DHL の拠点が読み込まれます。購入者は別の郵便番号や都市を入力し、Search をクリックできます。拠点は種類（Packstation、Post Office、Parcel Shop）ごとにまとめられ、距離順に並びます。何も見つからない場合、購入者には No DHL locations found near "…". Try another postcode or city. と表示されます。

Packstation の場合、購入者は DHL Postnummer を入力する必要があります。これは、DHL アプリまたは DHL アカウントにある 6〜12 桁の DHL お客様番号です。それ以外の拠点では任意です。選択すると、すぐに保存されます。Continue をクリックすると、サーバーがもう一度確認します。拠点は、配送先の国の DHL 検索結果の中に含まれている必要があります。拠点が選択されていない場合、購入者には Please choose a DHL Packstation or post office for delivery. と表示され、先に進めません。Packstation で Postnummer が未入力の場合は Please enter your DHL Postnummer - it is required for delivery to a Packstation. が、無効な場合は The DHL Postnummer must consist of 6 to 12 digits. が表示されます。

検索結果は 12 時間キャッシュされます。空の検索結果や失敗した検索は 10 分間キャッシュされるため、チェックアウトは更新のたびに DHL を待つことがありません。OpenCart の既定のファイルキャッシュでは、エントリは最長でもストアのキャッシュ有効期間（既定では 1 時間）まで保持されるため、一覧は 1 時間ごとに更新されます。API のタイムアウトは 12 秒です。DHL API に接続できない場合、購入者には DHL locations cannot be loaded right now. Please try again later or choose another shipping method. と表示されます。購入者がすでに選択していた拠点は、引き続き受け付けられます。

OpenCart 4 では、購入者はチェックアウトページの配送方法ブロックで Choose をクリックし、ウィンドウ Shipping method options で DHL Packstation を選択します。選択画面はそのウィンドウ内、方法の下に表示され、上記と同じように動作します。ウィンドウの Continue ボタンは、有効な拠点がない場合、または Packstation で Postnummer が入力されていない場合は先に進まず、同じメッセージが表示されます。

注文が確定すると、拠点（ID、種類、番号、名前、住所）と Postnummer が注文とともに保存されます。拠点は、注文の配送方法に DHL pickup location: と DHL Postnummer: として追加されるため、OpenCart が配送方法を表示するすべての場所に表示されます。購入者の注文ページ、注文メール、請求書です。Shipping address が有効な場合、注文の配送先住所は拠点の住所に置き換えられます。

OpenCart 4 は、チェックアウト用の注文を 1 つだけ保持し、購入者が再度確定するたびにその注文を更新します。拠点、配送方法のテキスト、注文の住所も一緒に更新されます。

注文

Sales > Orders で注文を開きます。注文履歴の上にある DHL pickup location パネルに、拠点、その種類と ID、そして Postnummer が表示されます。これは拡張機能をオフにした後も表示されます。拠点のない注文には No DHL location was selected for this order. と表示されます。

Change をクリックし、郵便番号または都市で検索し、DHL の一覧から別の拠点を選択し、必要に応じて Postnummer を変更して、Save location をクリックします。Postnummer だけを変更することもできます。注文の配送方法のテキストが更新されます。Shipping address が有効な場合は、注文の配送先住所も、購入者の元の住所から改めて更新されます。変更するたびに、注文履歴に DHL pickup location changed to: … のエントリが、現在の注文ステータスとともに追加されます。購入者には通知されません。拠点を変更するには注文の変更権限が必要です。拡張機能の設定へのアクセスは必要ありません。

ライセンスキー

この拡張機能は、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox DHL Packstation は、Extensions > Extensions > Shipping > VibeFox DHL Packstation > Edit ページの最初のブロックで、設定の上にあります。License key にキーを入力して Activate をクリックします。その後、ブロックにはマスクされたキー、ステータス（ライセンスの有効期限日やドメインなど）、次のボタンが表示されます。Check now はステータスを再確認、Change key は別のキーの入力、Remove key はこのストアからのキーの削除です。その下には、Product: opencart-shipping-dhl-packstation の行と、Manage licenses and domains in your account のリンク（vibefox.net のアカウントが開きます）があります。拡張機能の変更権限を持つ管理者ユーザーだけがキーを変更できます。ブロックのテキストは管理画面の言語に従います（英語とロシア語が含まれています）。

キーが受け付けられない場合、ブロックにその理由が表示されます。たとえば Key not found、This key belongs to another product、Domain limit reached、日付付きの License expired on などです。ストアのアドレスを変更した後、またはアカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、拡張機能は最後に確認したステータスで動作し続けます。

1 つのキーは 1 つのドメインで使用できます。ドメインとは、OpenCart の設定にあるストアのアドレスです。ストアからキーを削除しても、ドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。

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

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

トラブルシューティング

チェックアウトに DHL Packstation が表示されない: ライセンスが有効であること、Enable/Disable がオンであることを確認してください。Geo Zone を確認し（または Ignore shipping zones をオンにして Countries (ignore zones) を確認します）、DHL API key が入力されていること、少なくとも 1 つの拠点の種類が選択されていること、届け先の国に料金が設定されていること（または Other countries が設定されていること）、重量と小計のルールによって非表示になっていないことを確認してください。商品の Requires Shipping が Yes に設定されていることも確認してください。

拠点が表示されない: Test API key をクリックしてください。DHL がキーを拒否する場合（401/403）、キーと、アプリに「Location Finder - Unified」API があることを確認してください。Debug log をオンにし、チェックアウトを再読み込みして、拡張機能のページにある Log の欄を確認します。DHL アプリのリクエスト上限に達していないことも確認してください。

住所の近くに拠点がない: Search radius (meters) または Max results を増やすか、購入者に別の郵便番号や都市を検索させてください。DHL のデータで番号がない Packstation は一覧に表示されません。

購入者に "Enter your postcode or city to see DHL locations near you." と表示される: 配送先住所に郵便番号も都市もありません。購入者は検索欄に入力できます。

管理画面の注文ページの Change に "Please choose a DHL location of the search - nothing was changed." と表示される: 郵便番号または都市で検索し、結果から拠点を選択してください。注文にまだ拠点がない場合は、Postnummer を保存する前に拠点を選択する必要があります。

注文ページに DHL pickup location パネルがない: このパネルは、DHL Packstation で発送された注文にのみ表示されます（拡張機能をオフにしても残ります）。

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

アンインストール

Extensions > Extensions に移動し、タイプ Shipping を選択して、VibeFox DHL Packstation の横にある Uninstall（赤い − ボタン）をクリックします。OpenCart は、Enable/Disable、Sort Order、Tax Class、Geo Zone を常にリセットします。拠点のキャッシュと拡張機能のイベントは、常に削除されます。Remove data on uninstall がオンの場合は、設定、ログ、未完了のチェックアウトの拠点も削除されます。オフの場合は、その他の設定が保持され、拡張機能を再インストールすると再び使用されます。選択された拠点は常に注文に残ります。既存の注文は、配送方法、料金、住所を保持します。

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

DHL と Packstation は、それぞれの所有者の商標です。この拡張機能は DHL と提携しておらず、DHL による推奨もされていません。