VibeFox DHL Africa for OpenCart — ヘルプ
要件
OpenCart: 3.0.x（3.0.5.0 で動作確認済み）または 4.0.2 以降（4.1.0.3 で動作確認済み）。
PHP: cURL 拡張機能を有効にした 8.0 以降。DHL XML Services には PHP の SimpleXML 拡張機能も必要です。
DHL Express アカウント（リアルタイム料金の場合のみ）: リアルタイム料金は MyDHL API を使用します。DHL Express のアカウント番号と、MyDHL API の認証情報（API key と API secret）が必要です。DHL Developer Portal（MyDHL API、"Get access"）で申請するか、DHL Express のアカウントマネージャーにご依頼ください。DHL XML Services の認証情報（Site ID とパスワード）をお持ちのアカウントは、代わりにそれを使用できます。代替料金のみを使用する場合、DHL の認証情報は不要です。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。コンピューターで解凍してください。README.txt、OpenCart 3 用のパッケージ vfd_dhl_africa-oc3-(version).ocmod.zip、OpenCart 4 用のパッケージ vfd_dhl_africa.ocmod.zip が含まれています。お使いの OpenCart のバージョンに合うパッケージだけをインストールしてください。ライセンスキーは両方のバージョンで同じです。
OpenCart 3
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_dhl_africa-oc3-(version).ocmod.zip を選択します。この拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。インストーラーの代わりに、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。
2. Extensions > Extensions に移動し、拡張機能のタイプとして Shipping を選択します。VibeFox DHL Africa を見つけ、Install（緑色の + ボタン）をクリックします。
3. Edit（鉛筆のボタン）をクリックして、設定ページを開きます。
4. Edit ページの上部にあるライセンスブロックの License key 欄に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。
5. DHL API を選択し、API key、API secret、DHL アカウント番号を入力します。テスト用の認証情報を使用している間は Test mode をオンのままにしてください。Ship from の住所を入力します。DHL アカウントがストアの既定の通貨で請求されない場合は、DHL quote currency と Exchange rate を設定します。必要に応じて、国ごとの料金と代替料金を設定します（Configuration を参照）。Enable DHL Express Africa をオンにして、Save をクリックします。
OpenCart 4
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_dhl_africa.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変更したパッケージは動作しません。
2. 同じページの、インストール済みの拡張機能の一覧にパッケージが表示されます。その横の Install（緑色の + ボタン）をクリックします。
3. Extensions > Extensions に移動し、拡張機能のタイプとして Shipping を選択します。VibeFox DHL Africa を見つけ、Install（緑色の + ボタン）をクリックしてから、Edit（鉛筆のボタン）をクリックします。
4. ライセンスキーと設定は、OpenCart 3 の手順 4 と 5 と同じように入力します。設定ページとそのフィールドは、両方のバージョンで同じです。
インストール後は、Enable DHL Express Africa をオンにして保存するまで、この配送方法はオフのままです。アンインストール後に拡張機能を再インストールした場合は、残しておいた DHL の設定が再び使用されます。
設定
すべての設定は拡張機能のページにあります: Extensions > Extensions > Shipping > VibeFox DHL Africa > Edit。セクションは左側に並んでいます。Save ボタンを 1 つ押すと、ページを再読み込みせずにページ全体を保存します。保存のたびに、キャッシュされた DHL の見積もりも消去されます。料金と重量は小数点のカンマまたはピリオドを受け付けます。この拡張機能の変更権限を持つ管理者ユーザーだけが設定を保存できます。
ページ上部の警告は、API key、API secret、またはアカウント番号が未入力のとき（XML Services の場合は Site ID またはパスワード）、発送元の国または都市が未入力のとき、XML Services が選択されているとき（DHL は提供を終了します）、為替レートなしで見積もりの通貨が設定されているとき、そしてストアの重量単位または長さ単位を拡張機能が認識できないときに、リアルタイム料金が無効になっていることを知らせます。後者の場合、商品の重量は kg、寸法は cm として読み取られます。その場合は、System > Localisation > Weight Classes で単位 kg の重量クラス、または System > Localisation > Length Classes で単位 cm の長さクラスを追加してください。
保存時に値が無効な場合（配送方法名が空または 64 文字を超える、数値が無効または負、為替レートが 0、最小重量が最大重量より大きい、見積もりの通貨、発送元の国、税区分、地域ゾーンが不明、並び順が整数ではない）は、設定の上にある警告がフィールドを示します。例: Select a valid origin country. It was not saved. そのフィールドの以前の値は保持され、他の設定は保存されます。
一般
Enable DHL Express Africa: チェックアウトで DHL Express を表示または非表示にします。既定値: off。
Method title: チェックアウトで購入者に表示される配送方法の名前。既定値: DHL Express。必須、最大 64 文字。
Tax class: 配送料の税区分、または No tax（既定）。税区分を設定すると（かつストアで税金が有効な場合）、DHL の料金は DHL が見積もった税を含まずに取得され、OpenCart が独自の税を加算します。No tax の場合、DHL の料金は見積もりどおり、税込みで請求されます。
Sort order: チェックアウトの配送方法の中での DHL Express の表示順。整数。
DHL Express アカウント（リアルタイム料金の場合のみ必要）
DHL API: 使用する DHL のインターフェース。
API key: MyDHL API のユーザー名（API key）。
API secret: MyDHL API のパスワード（API secret）。保存後、API key と API secret のフィールドは空のままになり、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。
Remove the saved API key and API secret: MyDHL API で、キーまたは secret が保存されている場合にのみ表示されます。オンにして Save をクリックすると、両方が削除されます。
XML Site ID: DHL XML Services の Site ID（旧 API の場合のみ）。これを消去すると、保存された XML パスワードも削除されます。
XML password: DHL XML Services のパスワード（旧 API の場合のみ）。API secret と同様に、保存後は再表示されません。
DHL account number: DHL Express のアカウント番号（9 桁）。MyDHL API で必須です。XML Services の場合は、公開料金ではなく、お客様のアカウントの料金が返されます。
Test mode: DHL のテスト環境を使用します。既定でオンです。テスト用の認証情報はテスト環境でのみ、本番用の認証情報は本番環境でのみ機能します。本番運用を開始するときはオフにしてください。
発送元住所
DHL が荷物を集荷する住所です。料金はこの住所によって決まります。OpenCart はストアの住所を自由記述のテキストとして保存するため、発送元は必ずここで入力します。このセクションの注記には、ストアの国が表示されます。
Origin country: 発送元の国。
Origin city: 発送元の都市（例: Johannesburg）。MyDHL API で必須です。
Origin postcode: 郵便番号のない国（例: ケニア、ナイジェリア、ガーナ）の場合は空欄のままにします。
料金
すべての料金は、ストアの既定の通貨で、税抜きで表示されます。リアルタイム料金は、荷物に対して最も安い DHL Express 製品の料金です。DHL が設定されていない、エラーになる、またはそのルートに対応するサービスがない場合は、国の料金が使用され、次に代替料金が使用されます。どちらもない場合、配送方法は非表示になります。
DHL quote currency: DHL は、DHL アカウントの国の通貨で見積もります（例: ZAR、NGN、KES）。DHL がストアの既定の通貨での金額を返さない場合、リアルタイム料金は、この通貨から下記の為替レートで換算されます。それ以外の場合は使用されません。既定値: — None —。
Exchange rate: DHL の見積もり通貨 1 単位が、ストアの既定の通貨でいくらに相当するか（例: 1 ZAR = 0.05）。0 より大きい必要があります。換算しない場合は空欄のままにします。為替レートは手動で設定します。
Fallback cost: リアルタイム料金も国の料金もない場合に使用される固定料金。その場合に配送方法を非表示にするには、空欄のままにします。
Country prices: 届け先の国ごとの代替料金。1 行に 1 つ、CC:Price の形式で入力します（例: ZA:25.00）。リアルタイム料金がない場合に使用されます。別の形式の行は無視され、保存時の警告で一覧が表示されます。
Fallback price basis: Per order（既定）は料金を 1 回だけ請求します。Per item (multiplied by the cart quantity) は、カート内の商品数を掛けます。国の料金と代替料金にのみ適用されます。リアルタイムの DHL 料金は、常に荷物全体が対象です。
Free shipping from: 配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額以上の場合、この配送方法は無料になります。DHL への問い合わせは行いません。一切無料にしない場合は空欄のままにします。
条件
Minimum weight (kg): カートの重量がこの値未満の場合、配送方法を非表示にします。0 は制限なし（既定）を意味します。Maximum weight (kg) より大きくすることはできません。
Maximum weight (kg): カートの重量がこの値を超える場合、配送方法を非表示にします。既定値: 70（フィールドが空の場合も使用されます）。0 は制限なしを意味します。
Minimum subtotal: 配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額以上の場合にのみ、配送方法を表示します。常に表示する場合は空欄のままにします。
利用可否
Geo zone: この地域ゾーン内の住所に対してのみ DHL Express を提供します。All zones（既定）は制限なしを意味します。地域ゾーンは System > Localisation > Geo Zones で管理します。Ignore shipping zones の場合は確認されません。
Ignore shipping zones: 選択された地域ゾーンに関係なく、下記の国に対して配送方法を提供します（リストが空の場合はすべての国）。
Countries: このモードの届け先の国。Ignore shipping zones と組み合わせた場合にのみ使用されます。
詳細設定
Debug log: 料金の計算結果を storage/logs/vfd_dhla_debug.log.php（OpenCart 4 では system/storage/logs/vfd_dhla_debug.log.php）に書き込みます。このファイルは Web から読み取ることはできません。この設定がオフでも、DHL のエラーは常に記録されます。認証情報、アカウント番号、お客様の住所は決して記録されません。ファイルが 5 MB に達すると、vfd_dhla_debug.old.log.php に移動され、新しいログが開始されます。
Log: デバッグログのサイズと最新のエントリを表示します。Clear log をクリックすると空になります。
Remove data on uninstall: オンにすると、拡張機能のアンインストール時に、設定、キャッシュされた DHL の見積もり、ログが削除されます。オフ（既定）の場合は、再インストールに備えてすべて保持されます。注文済みの DHL 製品は、常に保持されます。
インポート / エクスポート
Export: Download JSON をクリックして、設定を JSON ファイルとして保存します。API key、API secret、XML パスワードはエクスポートされません。
Import: 以前にエクスポートした JSON を貼り付け、Import をクリックして設定を復元します（別のストアでの復元などに使用できます）。値は通常の保存と同様に確認されます。保存済みの認証情報は保持されます。
チェックアウトでの動作
OpenCart が配送方法を表示するとき、拡張機能に DHL Express の料金を問い合わせます。Geo zone が設定されていて（かつ Ignore shipping zones がオフの場合）、住所がその外にあれば、DHL Express は提供されません。Requires Shipping が Yes に設定されている商品だけが対象になります。それ以外の商品は重量に加算されず、小計にも含まれません。次に拡張機能は条件を確認します。Ignore shipping zones の国、カートの重量、最小小計です。小計は、配送が必要な商品の価格で、クーポン割引後、税抜きの金額です。ギフト券、ポイント、ストアのクレジットは考慮されません。送料無料が適用される場合、料金は 0 になり、DHL へのリクエストは送信されません。
それ以外の場合、拡張機能は DHL に、発送元と届け先（国、都市、郵便番号）、商品の重量クラスから kg に換算したカートの重量（最低 0.5 kg）、そして商品の寸法から cm 単位で作成した 1 つの箱を送信します。箱は、最も長い長さ、最も広い幅、積み重ねた高さで構成されます。寸法のない商品は加算されません。どの商品にも寸法がない場合は、10 x 10 x 10 cm の箱を使用します。他の国への発送は、カートの小計を申告価格として税関に申告されます。国内の発送は申告されません。集荷日は、ストアのタイムゾーンでの今日、週末の場合は月曜日です。リアルタイム料金は、お客様が都市を入力した後にのみ要求されます（XML Services の場合は都市または郵便番号）。それまでは代替料金が適用されます。
最も安い DHL Express 製品は、配送方法のタイトルとともに 1 つの料金として表示されます。お客様には DHL の製品は表示されません。料金は既定の通貨で計算され、その通貨の小数点以下の桁数に丸められ、選択した Tax class の税とともに、お客様の通貨で表示されます。
各見積もりは、荷物とルートごとに 1 時間キャッシュされます。失敗したリクエストは 10 分間キャッシュされるため、チェックアウトは更新のたびに DHL の応答を待つことがありません。API のタイムアウトは 12 秒です。DHL がエラーを返す、サービスがない、または使用できない通貨で応答した場合、お客様にエラーは表示されません。代替料金が使用されるか、配送方法が非表示になります。理由はデバッグログに書き込まれます。
この拡張機能は料金の計算のみを行います。DHL の荷物の作成、ラベルや商業インボイスの印刷、集荷の予約、荷物の追跡、DHL のサービスポイントの提供、お客様による DHL 製品の選択、複数の箱への梱包、保険の追加、関税や税金の計算は行いません。見積もりは配送料金のみが対象です。関税と輸入税は受取人が負担します。
OpenCart 4 では、お客様はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options のウィンドウで DHL Express を選択します。この方法は OpenCart 3 と同じように動作します。
注文
注文が確定すると、拡張機能はそのカートについて計算された料金を保持します。注文を Sales > Orders で開きます。注文履歴の上にある DHL Express Africa のパネルに、DHL で予約すべき内容が表示されます。
DHL product: リアルタイム料金の DHL Express 製品（例: "EXPRESS WORLDWIDE (P)"）。リアルタイム料金の場合にのみ表示されます。
Price source: Live DHL rate、Fallback price (no live rate)、または Free shipping threshold。
Calculated price (excl. tax): ストアの既定の通貨での料金。
DHL の製品は、お客様へのメールやお客様の注文ページには表示されません。注文には、他の OpenCart の配送方法と同様に、配送方法のタイトルと送料が表示されます。
OpenCart 4 では、チェックアウトは 1 つの注文を保持し、お客様が再度確定するたびにその注文を更新します。その場合、パネルにはチェックアウトの最新の料金が表示されます。お客様が別の配送方法に切り替えると、その注文ではパネルは表示されなくなります。
ライセンスキー
この拡張機能は、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox DHL Africa は、Extensions > Extensions > Shipping > VibeFox DHL Africa > Edit ページの一番上（設定の上）にあります。キーを License key に貼り付け、Activate をクリックします。その後、ブロックにはマスクされたキー、ステータス（例: ライセンスの有効期限の日付とドメイン）、そして次のボタンが表示されます。ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key。その下には、Product: opencart-shipping-dhl-africa の行と、vibefox.net のアカウントを開く Manage licenses and domains in your account のリンクがあります。拡張機能に対する変更権限を持つ管理者ユーザーだけがキーを変更できます。ブロックのテキストは管理画面の言語に従います（英語とロシア語が含まれています）。
キーが受け付けられない場合、ブロックにその理由が表示されます。例: Key not found、This key belongs to another product、Domain limit reached、License expired on と日付。ストアのアドレスを変更した後、またはアカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、拡張機能は最後に確認されたステータスで動作を続けます。
1 つのキーは 1 つのドメインで動作します。対象のドメインは、OpenCart の設定にあるストアのアドレスです。ストアからキーを削除しても、ドメインの枠は解放されません。枠は vibefox.net のアカウントで解放してください。
有効なキーがない場合、DHL Express の配送方法はチェックアウトでお客様に表示されず、料金も計算されません。同じブラウザで管理画面にログインしている管理者ユーザーには、ストアでこの配送方法が引き続き表示され、(unlicensed — visible to admins only) と表示されます。そのため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 では、このプレビューは利用できません。ストアは管理画面へのログインを認識しないため、有効なキーがない場合は、すべてのユーザーに対してこの配送方法が非表示になります。Edit ページを一度開くと、管理画面の Dashboard にお知らせが表示されます。× を押して閉じると、7 日間は非表示になります。既存の注文には影響しません。
ライセンスの期限が切れても、拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスが自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日に 1 回、その後は週に 1 回です。cron ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスのステータスは常に削除されます。
トラブルシューティング
チェックアウトに DHL Express が表示されない: ライセンスが有効であること、Enable DHL Express Africa がオンであることを確認してください。Geo zone を確認し（または Ignore shipping zones をオンにして Countries を確認します）、重量の制限と Minimum subtotal も確認してください。リアルタイム料金がない場合、国の料金または代替料金が設定されているときにのみ配送方法が表示されます。商品の Requires Shipping が Yes に設定されていることも確認してください。
リアルタイム料金が表示されない: 拡張機能のページ上部の警告（認証情報や発送元が未入力など）を確認してください。Debug log をオンにし、チェックアウトを再読み込みして、拡張機能のページにある Log の欄を確認します。MyDHL API の HTTP エラー、そのルートの製品がない、通貨の問題などの DHL のエラーは、常に記録されます。Test mode が認証情報と一致しているか、お客様の住所に都市が入力されているかを確認してください。
DHL が ZAR、NGN、KES で料金を返すが、ストアは別の通貨を使用している: ログに DHL quote not usable と表示されます。DHL quote currency をその通貨に設定し、Exchange rate を入力してください。これがないと、リアルタイム料金は使用されず、代替料金が適用されます。
古い DHL XML Services の認証情報があります: DHL API で XML Services (legacy) を選択してください。MyDHL の認証情報を受け取ったら、MyDHL API に切り替えてください。
配送料に税金が二重にかかる: Tax class を設定すると、DHL の税を含まない料金が使用されます。または No tax を選ぶと、DHL の金額を見積もりどおりに請求します。
変更後も料金が古いままに見える: 拡張機能のページで Save をクリックしてください。これにより、キャッシュされた DHL の見積もりが消去されます。
ページに "Warning: You do not have permission to modify VibeFox DHL Africa!" と表示される: 管理者のユーザーグループが設定を閲覧のみできる可能性があります。System > Users > User Groups で、グループに extension/shipping/vfd_dhl_africa（OpenCart 3）または extension/vfd_dhl_africa/shipping/vfd_dhl_africa（OpenCart 4）の変更権限を付与してください。
開発者向け: この拡張機能は、OpenCart のイベント catalog/vfd_dhl_africa/api_url、is_dutiable、package_box、rest_request、xml_request（同じ接頭辞）を発行します。これらにより、API のアドレス、税関申告、箱、DHL へのリクエストを変更できます。
アンインストール
Extensions > Extensions に移動し、タイプ Shipping を選択して、VibeFox DHL Africa の横にある Uninstall（赤い − ボタン）をクリックします。OpenCart は、Enable DHL Express Africa、Sort order、Tax class、Geo zone を常にリセットします。キャッシュされた DHL の見積もりと拡張機能のイベントは、常に削除されます。Remove data on uninstall がオンの場合は、DHL の設定とデバッグログも削除されます。オフの場合は、その他の設定が保持され、拡張機能を再インストールすると再び使用されます。注文済みの DHL 製品は削除されることはありません。既存の注文は、配送方法と料金を保持します。
OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済みの拡張機能の一覧にある VibeFox DHL Africa の横の Uninstall（オレンジ色の − ボタン）をクリックしてから、アップロードしたパッケージを削除するために Delete（赤いごみ箱のボタン）をクリックします。
DHL は、それぞれの所有者の商標です。この拡張機能は DHL と提携しておらず、DHL による推奨もされていません。