VibeFox SF Express for OpenCart — ヘルプ
必要環境
OpenCart：3.0.x（3.0.5.0 で動作確認済み）または 4.0.2 以降（4.1.0.3 で動作確認済み）。
PHP：8.0 以降。
SF Express アカウント（リアルタイム料金のみ）：リアルタイム料金は、SF Express の FengQiao オープンプラットフォーム（open.sf-express.com）を利用します。SF Express の月額契約と FengQiao の開発者アカウントが必要です。FengQiao に登録してアプリケーションを作成し、API「Delivery time standard and price query」（EXP_RECE_QUERY_DELIVERTM）を追加して、顧客コードとチェックワードをコピーしてください。サンドボックス環境と本番環境のチェックワードは異なります。料金表のみを使用する場合、SF Express アカウントは不要です。
中国の省（リアルタイム料金のみ）：リアルタイム料金には、配送先住所の省が必要です。これは住所の OpenCart の地域（Region / State）です。OpenCart には中国の地域が登録されていますが、チベットは含まれていません。本拡張機能で追加できます（後述の Chinese provinces を参照）。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
ダウンロードは、OpenCart の両方のバージョン用のパッケージを含む 1 つの zip ファイルです。お使いのコンピューターで解凍してください。README.txt、OpenCart 3 用パッケージ vfd_sf_express-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ vfd_sf_express.ocmod.zip が含まれています。お使いの OpenCart のバージョンに対応するパッケージのみをインストールしてください。ライセンスキーは両方のバージョンで共通です。
OpenCart 3
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_sf_express-oc3-(version).ocmod.zip を選択します。本拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。Installer を使わず、パッケージの upload フォルダーの内容をストアのルートフォルダーにコピーすることもできます。
2. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選択します。VibeFox SF Express を見つけて、Install（緑色の + ボタン）をクリックします。
3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。
4. Edit ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。
5. 料金表や代替料金を入力します。
6. 中国本土でリアルタイム料金を使う場合は、顧客コードとチェックワード、発送元の省と都市を入力します。ストアの通貨が CNY 以外の場合は、通貨換算レートも入力してください。ページから求められた場合は Add Chinese provinces をクリックします。最初は Sandbox とサンドボックスの認証情報でテストしてください。
7. Enable SF Express をオンにして、Save をクリックします。
OpenCart 4
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_sf_express.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変えたパッケージは動作しません。
2. パッケージは、同じページのインストール済み拡張機能の一覧に表示されます。その横の Install（緑色の + ボタン）をクリックします。
3. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選択します。VibeFox SF Express を見つけ、Install（緑色の + ボタン）をクリックしてから、Edit（鉛筆のボタン）をクリックします。
4. ライセンスキーと設定は、OpenCart 3 の手順 4 から 7 と同じように入力します。設定ページとそのフィールドは両方のバージョンで同じです。
インストール後は、Enable SF Express をオンにして保存するまで、この配送方法はオフのままです。アンインストール後に拡張機能を再インストールした場合は、保持されていた SF Express の設定が再び使われます。
設定
すべての設定は拡張機能のページにあります：Extensions > Extensions > Shipping > VibeFox SF Express > Edit。セクションは左側に一覧表示されます。設定はすべてのジオゾーンに適用されます。ページ下部の Save ボタンで、ページを再読み込みせずにページ全体を保存できます。保存するたびに、キャッシュされた SF Express の料金も削除されます。この拡張機能の変更権限を持つ管理者ユーザーだけが設定を保存できます。
保存時に、拡張機能は値を検証します。配送方法の名称が空の場合、64 文字を超える場合、または < > ; = # { } を含む場合、数値ではない値、負の金額や重量、通貨換算レートが 0 の場合、Min weight (kg) が Max weight (kg) より大きい場合、料金表の料金が誤っている場合、並び順が整数ではない場合は、メッセージが表示され、修正するまで保存されません。設定の上部の警告では、リアルタイム料金の設定が一部だけ完了している（不足している設定が一覧表示されます）場合、通貨換算レートがない場合、ストアに中国の地域がない場合、またはストアに kg の重量単位や cm の長さ単位がなく、既定の単位が拡張機能で認識されない場合に通知されます。
一般
Enable SF Express：チェックアウトで SF Express を表示するかどうかを設定します。既定：オフ。
Method title：カートとチェックアウトでお客様に表示される配送方法の名称。既定：SF Express。必須、最大 64 文字。
Tax class：送料の税クラス、または No tax。税クラスを選ぶと、送料にストアの送料税が加算されます。SF Express の料金に請求したい内容がすべて含まれている場合は、No tax を選択してください。
Sort order：チェックアウトで、配送方法の中での SF Express の表示順。整数。
SF Express FengQiao API（リアルタイム料金）（任意。中国本土の配送先住所向け）
Customer code (partnerID)：FengQiao アプリケーションの顧客コード（顾客编码）。これを消去すると、保存されたチェックワードも消去されるため、認証情報を削除できます。
Checkword：同じ環境のチェックワード（校验码）。リクエストへの署名にのみ使われ、送信やログ出力は行われません。保存後、このフィールドは空になり、Saved — leave empty to keep it. と表示されます。変更する場合のみ新しい値を入力してください。
Sandbox：サンドボックス用の認証情報でテストするため、FengQiao のサンドボックス（sfapi-sbox.sf-express.com）を使用します。サンドボックスの料金は実際の料金ではありません。本番のストアではオフにしてください。既定：オフ。
SF Express product：料金を表示する SF Express の商品。
Sender province：荷物の発送元の省（例：Guangdong / 广东）。最初の選択肢は、ストアが中国にある場合にストアの地域（System > Settings > Store > Local）を使用します。その場合、省の名前を添えて Same as the store region と表示されます。そうでない場合は — Select — と表示されます。
Sender city：都市の標準的な中国語名（例：深圳市）。リアルタイム料金には必須です。OpenCart のストア住所は自由入力のため、都市はそこから取得されません。
Currency conversion rate：SF Express の料金は CNY（元）で提供されます。ストアの既定の通貨が CNY でない場合は、1 CNY が自店の通貨で何単位に相当するかを入力してください（1 CNY = ? 単位）。例：0.13。これがない場合、リアルタイム料金は使用されません。ストアの通貨が CNY の場合、このフィールドは不要と表示され、料金はそのまま使用されます。小数点として、ピリオドとカンマのどちらも使用できます。
Chinese provinces：SF Express の 32 の省、自治区、直轄市のうち、OpenCart で中国の地域として登録されているものの数と、不足しているものを表示します。不足している省の住所には、料金表の料金が適用されます。Add Chinese provinces をクリックすると、不足している地域のみを中国の地域（ISO コードと "Tibet / 西藏" などの名前）として追加します。既存の地域は変更されません。このクリックを行うまでは何も変更されません。この方法で追加された地域は、アンインストール後もストアに残ります。
料金表と代替料金（香港、マカオ、台湾、その他の国に使用されます。リアルタイム料金が設定されていない場合、または 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 を超える場合です。Base の料金が 0 の場合は送料無料を意味します。基本料金が空の場合、その国には料金がないことを意味し、代替料金が使用されます。"9.99" と "9,99" の両方を入力できます。料金が一つも入力されていない行は保存されません。
Fallback cost：SF Express も料金表も料金を提供しない場合に使用されます。この場合に配送方法を非表示にするには、空欄のままにします。
Table / fallback price is：料金表と代替料金の課金方法。
SF Express のリアルタイム料金は、常に注文全体に対して適用されます。
条件
Free shipping from：送料が無料になるための、配送が必要な商品の小計（クーポン適用後、税抜き）。送料無料を提供しない場合は空欄にします。送料無料は料金の検索より前に確認されるため、この金額を超えると、この配送方法が利用可能なすべての配送先で無料になります。料金表に行がない国や Fallback cost がない国でも同様です。
Minimum subtotal：カートの小計がこの金額以上の場合のみ、配送方法を表示します。常に表示する場合は空欄にします。
Min weight (kg)：配送方法を表示するためのカートの最小重量（kg）。商品の重量は、その重量クラスから換算されます。0 は制限なしを意味します。
Max weight (kg)：カートの重量がこの値を超えると、配送方法を非表示にします。既定：50。0 または空欄は制限なしを意味します。
Geo zone：このジオゾーン内の住所にのみ SF Express を提供します。All zones（既定）は制限なしを意味します。ジオゾーンは System > Localisation > Geo Zones で管理します。Ignore shipping zones がオンの場合は確認されません。
配送ゾーンを使用しない場合の利用可否
Ignore shipping zones：ジオゾーンに関係なく、下に指定した国に SF Express を提供します。オフの場合は、ジオゾーンで判断され、国のリストは使用されません。
Countries：このモードで対象とする配送先の国。空欄の場合は、有効なすべての国を許可します。このフィールドは Ignore shipping zones がオンの場合にのみ使用されます。
詳細設定
Debug log：料金の計算を storage/logs/vfd_sfex_debug.log.php に記録します。このファイルは Web から読み取ることはできません。このオプションがオフの場合でも、API のエラーは常に記録されます。チェックワードや顧客の住所は書き込まれません。ファイルが 5 MB に達すると、vfd_sfex_debug.old.log.php に移動され、新しいログが開始されます。
Log：ログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログが空になります。
Remove data on uninstall：オンの場合、拡張機能をアンインストールすると、設定とログが削除されます。オフ（既定）の場合は、再インストールのために保持されます。キャッシュされた料金は常に削除されます。
インポート / エクスポート
Export：Download JSON をクリックすると、チェックワードを除いた設定を JSON ファイルとして保存します。
Import：以前にエクスポートした JSON を貼り付け、Import をクリックすると、設定を復元します。値は通常の保存と同様に検証されます。保存済みのチェックワードは保持されます。
チェックアウトでの動作
OpenCart が配送方法を表示するとき、拡張機能に SF Express の料金を問い合わせます。Geo zone が設定されていて住所がその外にある場合、SF Express は提供されません（Ignore shipping zones がオンの場合を除きます）。Requires Shipping が Yes に設定された商品のみが計算に含まれます。それ以外の商品は重量を加算せず、小計にも含まれません。小計は、これらの商品のクーポン割引後、税抜きの価格です。ギフト券、ポイント、ストアクレジットは考慮されません。その後、拡張機能は条件を確認します。許可された国（Ignore shipping zones の場合）、カートの重量、最低小計です。小計が Free shipping from に達した場合、料金は 0 となり、SF Express へのリクエストは送信されません。
顧客コードとチェックワードが設定されている中国本土の配送先住所の場合、拡張機能は発送元の省と都市、お客様の省と都市、カートの重量（0.1 kg 以上）、カートの容積（3 辺すべてが入力された商品から算出）を SF Express に送信します。リクエストはチェックワードで署名されます。SF Express は CNY で料金を返し、拡張機能は選択された料金をストアの既定の通貨に換算し、小数点以下の桁数に丸めます。料金は、選択された Tax class の税とともに、お客様の通貨で表示されます。
SF Express は、標準的な中国語の名称で住所を認識します。お客様の省は、住所の Region / State の地域から、その名称を照合して取得されます。"Hong Kong" の地域は中国本土の省ではないため、料金表の料金が適用されます。都市は中国語で入力する必要があります（例：广州市）。北京、上海、天津、重慶の場合は、都市が自動的に入力されます。"Guangzhou" のようにラテン文字で入力された都市は、料金表の料金が適用されます。
各料金は 1 時間キャッシュされるため、同じカートで新しいリクエストが発生することはありません。失敗したリクエストは 10 分間キャッシュされるため、チェックアウトの更新のたびに SF Express の応答を待つ必要はありません。HTTP のタイムアウトは 10 秒です。
リアルタイム料金がない場合、料金は料金表から、次に Fallback cost から取得されます。どちらも適用されない場合、配送方法は非表示になります。お客様にエラーが表示されることはありません。エラーはログに記録されます。
本拡張機能が計算するのは料金のみです。送り状や伝票は作成せず、SF Express で注文を作成せず、集荷の予約や配送のキャンセル、追跡も行いません。通常どおり、SF Express のアカウントで発送の作成と追跡を行ってください。お客様は SF の受取拠点やロッカーを選ぶことはできません。SF Express はドアツードアの宅配サービスとして使われます。リアルタイム料金は中国本土の配送先住所に対してのみ存在します。本拡張機能は FengQiao のドキュメントとモックの応答に基づいて作成されているため、本番運用の前に（まずサンドボックスで）SF Express のアカウントで料金を確認してください。
OpenCart 4 では、お客様はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options のウィンドウで SF Express を選択します。そのウィンドウには、配送方法の名称と料金が表示されます。この配送方法は OpenCart 3 と同じように動作します。
ライセンスキー
本拡張機能は、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox SF Express は、Extensions > Extensions > Shipping > VibeFox SF Express > Edit ページの一番上、設定の上にあります。キーを License key に貼り付け、Activate をクリックします。その後、ブロックにはキーが伏せ字で表示され、ステータス（ライセンスの有効期限日や、お使いのドメインなど）と、ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key のボタンが表示されます。その下には、Product: opencart-shipping-sf-express の行と、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 のアカウントで枠を解放してください。
有効なキーがない場合、SF Express の配送方法はチェックアウト時にお客様に表示されず、料金も計算されません。同じブラウザーで管理画面にログインしている管理者ユーザーには、ストアでこの方法が (unlicensed — visible to admins only) と表示されたまま見えるため、キーを購入する前に拡張機能の設定と動作確認ができます。OpenCart 4 ではこのプレビューは利用できません。ストアは管理画面へのログインを認識しないため、有効なキーがない場合は全員にこの方法が表示されなくなります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると、7 日間非表示になります。既存の注文には影響しません。
ライセンスの有効期限が切れても拡張機能は動作し続けますが、アップデートとサポートを受けるには更新が必要です。ステータスは、管理画面の Dashboard または Edit ページを開いたときに自動で再確認されます。キー入力後の最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは必要ありません。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは必ず削除されます。
トラブルシューティング
チェックアウトに SF Express が表示されない：ライセンスが有効で、Enable SF Express がオンになっていることを確認してください。Geo zone を確認するか、Ignore shipping zones をオンにして Countries を確認してください。重量制限と Minimum subtotal を確認してください。料金表または Fallback cost に、その国の料金があることを確認してください。商品の Requires Shipping が Yes に設定されていることを確認してください。
料金が SF Express ではなく料金表から取得されている：リアルタイム料金には、顧客コードとチェックワード、発送元の省と都市、省と中国語の都市名を含む中国本土の配送先住所、そして（CNY 以外のストアの場合）通貨換算レートが必要です。拡張機能ページの上部にある警告を確認し、Debug log をオンにして、チェックアウトを再読み込みし、Log フィールドで理由を確認してください。失敗したリクエストは 10 分後に再試行されます。
ログに署名エラーが表示される：チェックワードが誤っているか、別の環境のものです。Sandbox の設定を確認してください。SF Express が API の使用を許可していないと表示する場合は、FengQiao のアプリケーションに料金照会 API を追加してください。
チベットの住所に料金表の料金が適用される：拡張機能ページの API セクションで Add Chinese provinces をクリックしてください。
香港：料金表と代替料金で動作します。FengQiao の料金照会は、中国本土の住所を対象としています。
変更後の料金が古いように見える：拡張機能ページで Save をクリックしてください。キャッシュされた SF Express の料金が消去されます。
ページに "Warning: You do not have permission to modify VibeFox SF Express!" と表示される：管理者のユーザーグループには、設定の閲覧権限しかない可能性があります。System > Users > User Groups で、extension/shipping/vfd_sf_express（OpenCart 3）または extension/vfd_sf_express/shipping/vfd_sf_express（OpenCart 4）の変更権限をグループに付与してください。
開発者向け：OpenCart のイベント vfd_sf_express/quote_request と vfd_sf_express/api_url を使用すると、別の拡張機能で料金リクエスト（別の商品コードへの変更など）やゲートウェイの URL を変更できます。
アンインストール
Extensions > Extensions に移動し、種類として Shipping を選択して、VibeFox SF Express の横にある Uninstall（赤い − ボタン）をクリックします。本拡張機能のライセンスキーとライセンスステータスは常に削除されます。OpenCart は常に Enable SF Express、Sort order、Tax class、Geo zone をリセットします。キャッシュされた料金は常に削除されます。Remove data on uninstall がオンの場合は、その他の設定とログも削除されます。オフの場合は保持され、拡張機能を再インストールしたときに再び使われます。Add Chinese provinces で追加した中国の地域は残ります。既存の注文は、配送方法と送料を保持します。
OpenCart 4 では、拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧で VibeFox SF Express の横にある Uninstall（オレンジ色の − ボタン）をクリックしてから、Delete（赤いごみ箱のボタン）をクリックして、アップロードしたパッケージを削除します。
SF Express は、各所有者の商標です。本拡張機能は SF Express との提携や承認を受けたものではありません。