VibeFox DHL Africa for PrestaShop — ヘルプ
要件
PrestaShop: 8.0 から 9.x。
PHP: cURL 拡張機能を備えた 8.0 以降。古いバージョンの PHP または cURL がない環境では、モジュールはインストールできません。DHL XML Services には PHP の SimpleXML 拡張機能も必要です。
DHL Express アカウント（リアルタイム料金のみ必要）: リアルタイム料金は MyDHL API を使用します。DHL Express のアカウント番号と、MyDHL API の認証情報（API キーと API シークレット）が必要です。DHL Developer Portal（MyDHL API、"Get access"）または DHL Express のアカウントマネージャーから取得できます。DHL XML Services の認証情報（Site ID とパスワード）をまだお持ちのアカウントは、代わりにそれを使用できます。代替料金のみを使用する場合、DHL の認証情報は不要です。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインでのみ使用できます。
インストール
1. バックオフィスで Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックします。後からモジュール一覧で VibeFox DHL Africa を見つけて、Configure をクリックすることもできます。
3. Configure ページ上部のライセンスブロックで、License key に VibeFox ライセンスキーを入力し、Activate をクリックします（「ライセンスキー」を参照）。
4. DHL API を選択し、API key、API secret、DHL アカウント番号を入力します。テスト用の認証情報を使用している間は、Test mode をオンのままにしてください。Ship from の発送元住所を入力します。DHL アカウントがショップのデフォルト通貨で請求されない場合は、DHL quote currency と Exchange rate を設定します。必要に応じて、国ごとの料金と代替料金を設定します（設定を参照）。Save をクリックします。
インストール時、モジュールは配送時間テキスト DHL Express courier を持つ DHL Express 配送業者を作成します。配送業者はすべてのゾーンとすべての顧客グループに割り当てられます。ゾーン、顧客グループ、配送時間、ロゴ、サイズ制限は Shipping > Carriers で変更できます。料金はそこで設定しないでください。料金は常にモジュールから取得されます。
設定
すべての設定はモジュールページにあります: Modules > Module Manager > VibeFox DHL Africa > Configure。設定は配送業者のすべてのゾーンに適用されます。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。保存するたびに、キャッシュされた DHL の見積もりもクリアされます。料金と重量は小数点またはカンマで入力できます。
ページ上部の警告は、次の場合に表示されます。API key、API secret、アカウント番号が未入力のためリアルタイム料金が無効になっている場合（XML Services の場合は Site ID またはパスワード）、発送元の国または都市が未入力の場合、XML Services が選択されている場合（DHL はこれを廃止する予定です）、為替レートなしで見積もり通貨が設定されている場合、International > Localization（Local units）のショップの重量または寸法の単位をモジュールが認識できない場合（その場合は kg または cm として扱われます）。保存時に値が無効な場合（名前が空または 64 文字を超える、数値が無効または負の値、為替レートが 0、最小重量が最大重量を超える、見積もり通貨、発送元の国、税ルール）、エラーでその項目が示され、その項目の以前の値は維持されるとともに、他の設定は保存されます。
一般
Enable DHL Express Africa: 配送業者のオン/オフを切り替えます。Shipping > Carriers の配送業者のステータスと同じスイッチです。
Name: チェックアウトで購入者に表示される配送業者の名前。デフォルト: DHL Express。必須、64 文字以内。
Tax: 配送業者の税ルール、または No tax。税ルールを設定した場合（ショップで税金が有効なとき）、DHL の料金は DHL が見積もる税金を除いて取得され、PrestaShop が独自の税金を追加します。No tax の場合、DHL の料金は見積もられたとおり、税込みで請求されます。
DHL Express アカウント（リアルタイム料金にのみ必要）
DHL API: 使用する DHL のインターフェース。選択した API の項目のみが表示されます。
API key: MyDHL API のユーザー名（API キー）。
API secret: MyDHL API のパスワード（API シークレット）。保存後、API key と API secret の項目は空のままになり、Saved — leave empty to keep it. と表示されます。変更する場合のみ新しい値を入力してください。
Remove the saved API key and 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 のテスト環境を使用します。デフォルトでオンです。テスト用の認証情報はテスト環境でのみ、本番用の認証情報は本番環境でのみ有効です。本番稼働時にはオフにしてください。
Ship from
DHL が荷物を集荷する住所です。料金はこの住所によって変わります。
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 を超えることはできません。
Maximum weight: カートの重量がこの値を超える場合、配送業者を非表示にします（kg 単位）。デフォルト: 70（項目が空の場合にも使用されます）。0 は制限なしを意味します。
Minimum subtotal: カート小計（割引後、税抜き）がこの金額以上の場合にのみ、配送業者を表示します。常に表示する場合は空欄のままにします。
配送ゾーンなしでの提供
Ignore shipping zones: 配送業者にゾーンを手動で割り当てることなく、配送業者を提供します。配送業者は後で作成するゾーンも含め、すべてのゾーンを対象とし、下記の国によって判定されます。オフにすると、配送業者は自分専用のゾーンに戻ります。
Countries: このモードの届け先の国。すべての配送先の国を許可する場合は空欄のままにします。Ignore shipping zones を使用している場合にのみ使用されます。
詳細設定
Debug log: 料金の計算結果をモジュールフォルダー内の logs/vfd_dhla_debug.log.php に書き込みます。このファイルは Web からは開けません。この設定がオフでも、DHL のエラーは常に記録されます。認証情報と顧客の住所は記録されません。
Log: デバッグログのサイズと最新のエントリーを表示します。Clear log をクリックすると、ログを空にできます。
Remove data on uninstall: オンの場合、モジュールをアンインストールすると、設定、配送業者、注文の保存済み DHL 製品、ログが削除されます。オフの場合は、再インストールに備えてすべて保持されます。
チェックアウトでの動作
配送ステップで、PrestaShop はモジュールに DHL Express の料金を問い合わせます。対象は物理的な商品のみです。仮想商品は重量を追加せず、小計にも含まれません。モジュールはまず条件を確認します。Ignore shipping zones の国、カートの重量、最低小計です。送料無料が適用される場合、料金は 0 になり、DHL へのリクエストは送信されません。
それ以外の場合、モジュールは DHL に、発送元と届け先（国、都市、郵便番号）、kg に換算したカートの重量（最低 0.5 kg）、そして商品の寸法（cm 単位）から作成した 1 つの箱を送信します。箱の寸法は、最も長い長さ、最も広い幅、積み重ねた高さです。寸法のない商品は計算に含まれません。どの商品にも寸法がない場合は、10 x 10 x 10 cm の箱が使用されます。他国への発送は、カート小計を申告価格として税関に申告されます。国内の発送は申告されません。集荷日は今日、週末の場合は月曜日です。リアルタイム料金は、購入者が都市を入力した後にのみ請求されます（XML Services の場合は都市または郵便番号）。それまでは、代替料金が適用されます。
最も安い DHL Express の製品は、配送業者名の 1 つの料金として表示されます。購入者には DHL の製品は表示されません。料金はデフォルト通貨で計算され、丸められた後、購入者のカートの通貨で表示されます。
各見積もりは、荷物と経路ごとに 1 時間キャッシュされます。リクエストが失敗した場合は 10 分間キャッシュされるため、更新のたびにチェックアウトが DHL の応答を待つことはありません。API のタイムアウトは 12 秒です。DHL がエラーを返す、サービスがない、または使用できない通貨で応答した場合、購入者にエラーは表示されません。代替料金が使用されるか、配送業者が非表示になります。理由はデバッグログに記録されます。
注文がある配送業者を Shipping > Carriers で編集すると、PrestaShop はそれを新しいバージョンの配送業者として保存します。モジュールは自動的に新しいバージョンに従います。
モジュールが行うのは料金の計算のみです。DHL の配送の作成、商用インボイスやラベルの印刷、集荷の予約、荷物の追跡、DHL のサービスポイントの提供、購入者による DHL 製品の選択、複数の箱への梱包、保険の追加、関税や税金の見積もりは行いません。見積もりは配送料のみを対象とします。関税と輸入税は受取人が負担します。
注文
注文が確定すると、モジュールはそのカートについて計算された料金を保持します。バックオフィスの注文ページには、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): ショップのデフォルト通貨での料金。
注文の編集時など、後からカートを再計算しても、これらの値は変わりません。注文にならなかったカートの料金は、30 日後に削除されます。
ライセンスキー
このモジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。License — VibeFox DHL Africa のライセンスブロックは、Modules > Module Manager > VibeFox DHL Africa > Configure ページの設定より上にある最初のブロックです。License key にキーを入力し、Activate をクリックします。その後、ブロックにはキーがマスク表示され、ステータス（ライセンスの有効期限日やドメインなど）が表示されます。また、ステータスを再確認する Check now、別のキーを入力する Change key、このショップからキーを削除する Remove key のボタンが表示されます。その下には Product: presta-shipping-dhl-africa という行と、vibefox.net のアカウントを開く Manage licenses and domains in your account のリンクがあります。キーを変更できるのは、このモジュールの Configure 権限を持つスタッフのみです。ブロックのテキストはバックオフィスの言語に従います（英語とロシア語が含まれています）。
キーが受け付けられない場合、ブロックに理由が表示されます。例: Key not found、This key belongs to another product、Domain limit reached、または日付付きの License expired on。ショップのアドレスを変更した後、またはアカウントでドメインの枠を解放した後に、Check now をクリックしてください。ライセンスサーバーに接続できない場合、モジュールは最後に確認されたステータスで動作を続けます。
1 つのキーは 1 つのドメインでのみ使用できます。メインショップのドメインで、マルチストア構成でも同じです。ショップからキーを削除しても、ドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。
有効なキーがない場合、DHL Express の配送業者はチェックアウトで購入者に表示されず、料金も計算されません。PrestaShop のフロントエンドはバックオフィスにログインしていることを認識しないため、配送業者はあなたに対しても非表示になります。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。
ライセンスが期限切れになっても、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。バックオフィスで作業している間、ステータスは自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日に 1 回、その後は 1 週間に 1 回です。cron ジョブは不要です。モジュールのアンインストールまたはリセットでは、常にライセンスキーとライセンスステータスが削除されます。
トラブルシューティング
チェックアウトに DHL Express が表示されない: ライセンスが有効で、Enable DHL Express Africa がオンになっていることを確認してください。Shipping > Carriers で、配送業者が顧客の国のゾーンと顧客のグループを対象にしているか確認してください（または Ignore shipping zones をオンにして Countries を確認してください）。重量の制限と Minimum subtotal も確認してください。リアルタイム料金がない場合、国ごとの料金または代替料金が設定されていないと、配送業者は表示されません。商品ページで、特定の配送業者に制限されている場合もあります。
リアルタイム料金が表示されない: モジュールページ上部の警告（認証情報または発送元の不足）を確認してください。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 で税ルールを設定し、DHL の料金が DHL の VAT を除いて取得されるようにするか、No tax を選択して DHL の金額を見積もどおりに請求してください。
変更後も料金が古いまま: モジュールページで Save をクリックしてください。これにより、キャッシュされた DHL の見積もりがクリアされます。
DHL Express 配送業者が見つからないと表示される: Shipping > Carriers で配送業者が削除されています。Modules > Module Manager でモジュールをリセットすると、再作成されます。
開発者向けに、モジュールは API アドレス、税関申告、箱、DHL へのリクエストを変更するためのフック actionVfdDhlaApiUrl、actionVfdDhlaIsDutiable、actionVfdDhlaPackageBox、actionVfdDhlaRestRequest、actionVfdDhlaXmlRequest を提供します。
アンインストール
Modules > Module Manager に移動し、VibeFox DHL Africa の横にあるメニューを開いて、Uninstall を選択します。ライセンスキー、ライセンスステータス、キャッシュされた DHL の見積もりは、常に削除されます。Remove data on uninstall がオンの場合、配送業者は削除され（注文は履歴を保持します）、設定、注文の保存済み DHL 製品、ログも削除されます。オフの場合、配送業者は無効化されるだけで、設定と配送済み注文の DHL 製品は保持されます。モジュールを再インストールすると、配送業者は以前のステータスに戻ります。
DHL は、それぞれの所有者の商標です。このモジュールは DHL の関連会社ではなく、DHL による承認も受けていません。