VibeFox SF Express for PrestaShop — ヘルプ
要件
PrestaShop：8.0 から 9.x。
PHP：8.0 以降。古い PHP バージョンではモジュールをインストールできません。
SF Express アカウント（リアルタイム料金のみ）：リアルタイム料金は SF Express の FengQiao オープンプラットフォーム（open.sf-express.com）を使用します。SF Express の月額契約アカウントと、FengQiao の開発者アカウントが必要です。そちらに登録してアプリケーションを作成し、API "Delivery time standard and price query"（EXP_RECE_QUERY_DELIVERTM）を追加して、顧客コードと checkword をコピーしてください。サンドボックスと本番環境の checkword は異なります。料金表のみを使う場合、SF Express アカウントは不要です。
中国の省（リアルタイム料金のみ）：リアルタイム料金には、配送先住所の省が必要です。PrestaShop には標準で中国の省が登録されていません。モジュールが追加できます（下の Chinese provinces を参照してください）。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
1. 管理画面で Modules > Module Manager を開き、Upload a module をクリックします。モジュールの ZIP ファイルを選択してください。
2. アップロードが完了したら Configure をクリックします。後から行う場合は、モジュール一覧で VibeFox SF Express を探し、Configure をクリックしてください。
3. Configure ページ上部のライセンスブロックの License key に、VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。
4. 料金表や代替料金を入力し、Save をクリックします。
5. 中国本土向けのリアルタイム料金を使う場合は、顧客コードと checkword、発送元の省と市区町村（または中国にあるショップの住所）を入力します。ショップの通貨が CNY でない場合は、通貨換算レートも入力してください。ページで求められた場合は Add Chinese provinces をクリックしてください。まず Sandbox とサンドボックスの認証情報でテストしてください。
インストール時に、モジュールは配送時間のテキスト Courier delivery を持つ SF Express 配送業者を作成します。配送業者はすべてのゾーンとすべての顧客グループに割り当てられます。ゾーン、顧客グループ、配送時間、ロゴ、サイズ制限は Shipping > Carriers で変更できます。ただし、そこでは料金を設定しないでください。料金は常にモジュールから取得されます。
設定
すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox SF Express > Configure。設定は配送業者のすべてのゾーンに適用されます。各セクションにはそれぞれ Save ボタンがあり、ページ全体を保存します。保存するたびに、キャッシュされた SF Express の料金も消去されます。
保存時、モジュールは数値を検証します。数値でない値、負の金額や重量、換算レートが 0 の場合、Min weight が Max weight より大きい場合、または料金表の料金が不正な場合は、メッセージとともに拒否され、修正するまで何も保存されません。設定の上部の警告は、リアルタイム料金の設定が一部だけ済んでいること（不足している設定が一覧表示されます）、換算レートが未入力であること、中国の住所に省のフィールドがないこと、またはショップの重量やサイズの単位をモジュールが認識できないことを知らせます。単位は International > Localization（Local units）で設定します。
一般
Enable SF Express：配送業者を有効または無効にします。これは Shipping > Carriers の配送業者のステータスと同じスイッチです。
Method title：カートとチェックアウトに表示される配送業者の名称です。デフォルト：SF Express。必須、最大 64 文字。
Tax：配送業者の税ルール、または No tax です。税ルールを選ぶと、ショップの配送税が料金に加算されます。SF Express の料金に、請求したいものがすべて含まれている場合は No tax を選んでください。
SF Express FengQiao API（リアルタイム料金）（任意、中国本土の配送先住所向け）
Customer code (partnerID)：FengQiao アプリケーションの顧客コード（顾客编码）です。これを消去すると、保存された checkword も消去されるため、認証情報を削除できます。
Checkword：同じ環境の checkword（校验码）です。リクエストの署名にのみ使われ、送信や記録は行われません。保存後、このフィールドは空のまま Saved — leave empty to keep it. と表示されます。変更する場合のみ新しい値を入力してください。
Sandbox：FengQiao のサンドボックス（sfapi-sbox.sf-express.com）を、サンドボックスの認証情報とともにテストに使用します。サンドボックスの料金は実際の料金ではありません。本番のショップではオフにしてください。デフォルト：オフ。
SF Express product：どの SF Express 商品の料金を表示するかを選びます。
Sender province：荷物を発送する省です。ショップが中国にある場合は、空欄のままにすると Shop Parameters > Contact > Stores のショップ住所の省を使用します。
Sender city：標準的な中国語の市区町村名（例：深圳市）です。ショップが中国にある場合は、空欄のままにするとショップの市区町村を使用します。
Currency conversion rate：SF Express の料金は人民元（CNY、元）建てです。ショップのデフォルト通貨が CNY でない場合は、1 CNY があなたの通貨で何単位に相当するかを入力してください（1 CNY = ? 単位）。未入力の場合、リアルタイム料金は使用されません。ショップの通貨が CNY の場合、料金はそのまま使用されます。小数点とカンマのどちらも小数の区切りとして受け付けます。
Chinese provinces：中国の住所に省を入れられるかどうかを示します。入れられない場合は Add Chinese provinces をクリックしてください。このボタンは、32 の省、自治区、直轄市を中国の州（states）として追加します（GD や BJ などの ISO コード、"Guangdong / 广东" などの名称）。また、中国で "Contains states" を有効にし、中国の住所フォームに州のフィールドを追加します。既に存在する省は再度追加されません。このクリックをしない限り、何も変更されません。
料金表と代替料金（香港、マカオ、台湾、その他の国で使われます。リアルタイム料金が設定されていない場合、または SF Express が料金を返さない場合に適用されます。料金はショップのデフォルト通貨で、税抜きです）
Country prices：国ごとの基本料金の表です。Add country をクリックすると行が追加され、ごみ箱アイコンをクリックすると行が削除されます。* All other countries の行は、独自の行がないすべての国に適用されます。重量区分の料金（0 より大きい値）は、その区分の荷物について基本料金を置き換えます：XS ≤1 kg、S ≤2 kg、M ≤3 kg、L ≤5 kg、XL >5 kg。基本料金が 0 の場合は送料無料を意味します。基本料金が空欄の場合、その国の料金はなく、代替料金が使用されます。"9.99" と "9,99" のどちらも受け付けます。料金が 1 つもない行は保存されません。
Fallback cost：SF Express も料金表も料金を提供しない場合に使用されます。空欄のままにすると、その場合は配送業者を非表示にします。
Table / fallback price is：料金表と代替料金の課金方法です。
SF Express のリアルタイム料金は常に注文全体に対するものです。
条件
Free shipping from：送料無料になるカートの小計（割引後、税抜き）です。空欄のままにすると、送料無料は提供されません。送料無料は料金を照会する前に確認されるため、この金額以上であれば、配送業者が利用可能なすべての配送先で無料で提供されます。料金表に行がない国や Fallback cost がない国であってもです。
Minimum subtotal：カートの小計（割引後、税抜き）がこの金額に達した場合にのみ配送業者を表示します。空欄のままにすると、常に表示されます。
Min weight：カートの最小重量（kg）です。商品の重量は、ショップの重量単位から変換されます。0 は制限なしを意味します。
Max weight：カートの最大重量（kg）です。デフォルト：50。0 または空欄は制限なしを意味します。
配送ゾーンを使わない場合の利用可否
Ignore shipping zones：どの配送ゾーンが一致するかに関係なく、下記の国に SF Express を提供します。保存時、配送業者はすべての配送ゾーンに追加され、後から作成されたゾーンにも追加されます。このオプションをオフにすると、追加されたゾーンは削除されます。オフの場合、配送業者は本来のゾーンにのみ表示されます。
Countries：このモードの配送先の国です。空欄のままにすると、有効なすべての国が許可されます。このフィールドは Ignore shipping zones がオンの場合にのみ使われます。
詳細設定
Debug log：料金の計算結果を、モジュールのフォルダにある logs/vfd_sfex_debug.log.php に書き込みます。このファイルはウェブから開くことはできません。このオプションがオフでも、API のエラーは常に記録されます。checkword や顧客の住所は書き込まれません。
Log：ログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログを空にできます。
Remove data on uninstall：オンの場合、モジュールをアンインストールすると、設定、配送業者、キャッシュされた料金、ログが削除されます。オフの場合は、再インストールのためにすべて保持されます。
チェックアウト時の動作
配送ステップで、PrestaShop はモジュールに SF Express の料金を問い合わせます。対象となるのは実物の商品のみです。バーチャル商品は重量を加算せず、小計にも含まれません。モジュールは最初に条件を確認します：許可された国（Ignore shipping zones を使用）、カートの重量、最低小計です。小計が Free shipping from に達している場合、料金は 0 になり、SF Express へのリクエストは送信されません。
顧客コードと checkword が設定されており、配送先が中国本土の住所の場合、モジュールは SF Express に対して、発送元の省と市区町村、お客様の省と市区町村、カートの重量、そしてカートの容積（3 つのサイズすべてがある商品から計算）を送信します。リクエストは checkword で署名されます。SF Express は人民元で料金を返し、モジュールは選択された料金をショップのデフォルト通貨に換算します。その後、料金はお客様のカートの通貨で表示されます。
SF Express は標準の中国語名称で住所を認識します。お客様の省は、住所の州のフィールドから取得されます。市区町村は中国語で入力する必要があります（例：広州市）。北京、上海、天津、重慶の場合、市区町村は自動的に入力されます。"Guangzhou" のようにラテン文字で入力された市区町村では、料金表の料金が使われます。
各料金は 1 時間キャッシュされるため、同じカートでも新しいリクエストは発生しません。失敗したリクエストは 10 分間キャッシュされるため、チェックアウトのたびに SF Express の応答を待つことはありません。HTTP のタイムアウトは 10 秒です。
リアルタイム料金がない場合、料金は料金表から、次に Fallback cost から取得されます。いずれも適用されない場合、配送業者は非表示になります。お客様にエラーが表示されることはありません。エラーはログに記録されます。
注文を受けた後で Shipping > Carriers から配送業者を編集すると、PrestaShop はそれを新しい配送業者のバージョンとして保存します。モジュールは自動的に新しいバージョンに従います。
モジュールが行うのは料金の計算のみです。送り状やラベルの作成、SF Express での注文作成、集荷の予約、配送のキャンセルや追跡は行いません。通常どおり、SF Express のアカウントで配送を作成・追跡してください。お客様が SF のサービスポイントやロッカーを選ぶことはできません。SF Express は戸口配送の宅配サービスとして使われます。リアルタイム料金は中国本土の配送先住所に対してのみ利用できます。このモジュールは FengQiao のドキュメントとモックのレスポンスに基づいて開発されたため、本番運用の前に（まずサンドボックスで）、料金を SF Express のアカウントで確認してください。
ライセンスキー
このモジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox SF Express は、Modules > Module Manager > VibeFox SF Express > Configure の最初のブロックで、設定の上にあります。キーを License key に貼り付けて Activate をクリックします。その後、ブロックにはキーがマスクされて表示され、ステータス（例：ライセンスの有効期限日とドメイン）と、ボタン Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このショップからキーを削除）が表示されます。その下には Product: presta-shipping-sf-express の行と、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 アカウントで枠を解放してください。
有効なキーがない場合、SF Express 配送業者はチェックアウト時にお客様に表示されず、料金も計算されません。PrestaShop のフロントエンドは、バックオフィスにログインしていることを認識しないため、配送業者はあなたにも表示されません。キーを購入する前にモジュールを設定することはできますが、チェックアウトで試すことはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。
ライセンスの期限が切れても、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。バックオフィスで作業している間、ステータスは自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
チェックアウトに SF Express が表示されない：ライセンスが有効であること、Enable SF Express がオンであることを確認してください。Shipping > Carriers で、配送業者がお客様の国のゾーンとお客様の顧客グループをカバーしていることを確認してください（または Ignore shipping zones をオンにして Countries を確認してください）。重量制限と Minimum subtotal を確認してください。料金表または Fallback cost に、その国の料金が設定されていることを確認してください。商品ページで、特定の配送業者に制限されている場合もあります。
料金が SF Express ではなく料金表から来ている：リアルタイム料金には、顧客コードと checkword、発送元の省と市区町村、省と中国語の市区町村名を含む中国本土の配送先住所、そして（CNY 以外のショップの場合）通貨換算レートが必要です。モジュールページ上部の警告を読み、Debug log をオンにして、チェックアウトを再読み込みし、Log フィールドで理由を確認してください。失敗したリクエストは 10 分後に再試行されます。
中国の住所フォームに省がない：モジュールページの API セクションで Add Chinese provinces をクリックしてください。
ログのエラー A1006：署名が無効です。checkword が間違っているか、別の環境のものです。Sandbox の設定を確認してください。
ログのエラー A1004：料金照会 API が FengQiao アプリケーションに追加されていません。
香港：料金表と代替料金で動作します。FengQiao の料金照会は中国本土の住所のみが対象です。
変更後に料金が古いように見える：モジュールページで Save をクリックしてください。キャッシュされた SF Express の料金が消去されます。
SF Express の配送業者が見つからないというメッセージが表示される：配送業者が Shipping > Carriers で削除されています。Modules > Module Manager でモジュールをリセットすると、再作成されます。
開発者向け：フック actionVfdSfExpressQuoteRequest は料金のリクエストを変更できます（例：別の商品コードへの変更）。actionVfdSfExpressApiUrl はゲートウェイの URL を変更できます。
アンインストール
Modules > Module Manager に移動し、VibeFox SF Express の横のメニューを開いて Uninstall を選択してください。ライセンスキーとライセンスステータスは常に削除されます。キャッシュされた料金は常に削除されます。Remove data on uninstall がオンの場合、配送業者は削除され（注文は履歴を保持します）、設定とログも削除されます。オフの場合、配送業者は無効化されるだけで、すべての設定は保持されます。モジュールを再インストールする、または Reset を行うと、配送業者はそれ以前のステータスに戻ります。既存の注文は配送の行を保持します。
SF Express は、それぞれの所有者の商標です。このモジュールは SF Express と提携しておらず、SF Express による推奨も受けていません。