VibeFox Purolator for OpenCart — ヘルプ
要件
OpenCart：3.0.x（3.0.5.0 で動作確認）または 4.0.2 以降（4.1.0.3 で動作確認）。
PHP：8.0 以降。cURL 拡張が必要です。PHP の SOAP 拡張は不要です。
Purolator E-Ship Web Services（リアルタイム料金の場合のみ）：Purolator のウェブサイトにある Purolator E-Ship Resource Centre で E-Ship Web Services に登録してください。Purolator は開発環境と本番環境用に別々のキーとパスワードを発行します。また、Purolator の請求アカウント番号と、発送元となるカナダの郵便番号も必要です。固定料金のみを使用する場合は、API キーは不要です。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインでのみ使用できます。
インストール
このダウンロードは、両方の OpenCart バージョン用のパッケージが入った zip ファイル 1 つです。コンピュータで解凍してください。README.txt、OpenCart 3 用パッケージ vfd_purolator-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ vfd_purolator.ocmod.zip が含まれています。お使いの OpenCart のバージョンのパッケージのみをインストールしてください。ライセンスキーは両方のバージョンで同じです。
OpenCart 3
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_purolator-oc3-(version).ocmod.zip を選択します。本拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。Installer を使わずに、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。
2. Extensions > Extensions に移動し、拡張機能の種類 Shipping を選択します。VibeFox Purolator を見つけ、Install（緑色の + ボタン）をクリックします。
3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。
4. Edit ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを貼り付け、Activate をクリックします（ライセンスキーの項を参照）。
5. リアルタイム料金を使う場合は、Purolator API (live rates) セクションに入力します：API キー、パスワード、請求アカウント番号、発送元のカナダの郵便番号、そしてストアの通貨が CAD でない場合は CAD のレート。テストするには、開発用キーで Development environment をオンにします。固定料金や代替料金を使う場合は、Country prices または Fallback price に入力します（設定の項を参照）。Enable Purolator をオンにして、Save をクリックします。
OpenCart 4
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_purolator.ocmod.zip を選択します。ファイル名を変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から読み取るため、名前を変更したパッケージは動作しません。
2. パッケージは同じページのインストール済み拡張機能の一覧に表示されます。その横の Install（緑色の + ボタン）をクリックします。
3. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選択します。VibeFox Purolator を見つけ、Install（緑色の + ボタン）をクリックしてから、Edit（鉛筆のボタン）をクリックします。
4. ライセンスキーと設定は、OpenCart 3 の手順 4 と 5 と同じように入力します。設定ページとその項目は両方のバージョンで同じです。
インストール後、Enable Purolator をオンにして保存するまで、この配送方法は無効のままです。アンインストール後に拡張機能を再インストールした場合は、保持されていた Purolator の設定が再び使用されます。
設定
すべての設定は拡張機能のページにあります：Extensions > Extensions > Shipping > VibeFox Purolator > Edit。セクションは左側に並んでいます。ページ下部の Save ボタンで、ページを再読み込みせずにページ全体を保存します。保存のたびに、キャッシュされた Purolator の料金も消去されます。この拡張機能の変更権限を持つ管理者ユーザーだけが設定を保存できます。
保存された値ではリアルタイム料金が機能しない場合（キー、パスワード、請求アカウントがない、カナダの発送元郵便番号がない、CAD レートがない）、または API の認証情報も固定料金もない場合は、General セクションに警告が表示されます。その間は固定料金が使われるのか、配送方法が非表示になるのかも示されます。ストアの重量単位が拡張機能で認識できないものである場合も警告が表示されます。その場合、商品の重量は kg として読み取られます。System > Localisation > Weight Classes で、単位が kg の重量クラスを追加してください。
0 以上の数値を含まない数値フィールドは保存されません。Save の後に表示されるメッセージで、フィールドと値が示されます。フィールドは空になるか、重量フィールドの場合は既定値になります。Country prices の誤った値は 0 として保存され、メッセージに国と列が示されます。配送方法のタイトルが空、または 64 文字を超える場合、Min cart weight (kg) が Max cart weight (kg) より大きい場合、並べ替え順序が整数でない場合、税クラスやジオゾーンが無効な場合は、何も保存されず、エラーが表示されます。
一般
購入者には Purolator の料金が 1 つだけ表示されます。設定はすべてのジオゾーンに適用されます。Availability で、配送方法をジオゾーンまたは国に限定できます。
Enable Purolator：チェックアウトで Purolator を表示または非表示にします。デフォルト：オフ。
Method title：チェックアウトで購入者に表示される配送方法の名前。デフォルト：Purolator。必須、64 文字まで。
Tax class：配送料の税クラス、または No tax（デフォルト）。ストアが料金に税金を上乗せするかどうかを決めます。カナダの住所では、Purolator の合計額にすでに GST/HST/PST/QST が含まれています。下の Canadian sales taxes を参照してください。
Sort order：チェックアウトの配送方法の中で Purolator が表示される位置。整数です。
Purolator API（リアルタイム料金）
API キー、パスワード、請求アカウントを入力すると、料金は Purolator E-Ship Estimating ウェブサービス（カート全体の重量に対する Quick Estimate）から取得されます。Purolator から料金が返されない場合は固定料金が使われ、固定料金もない場合は配送方法が非表示になります。このセクションには、登録してキーを取得できる Purolator E-Ship Resource Centre へのリンクがあります。エラーの詳細はログに記録され、購入者に表示されることはありません。
API key：選択した環境用の E-Ship Web Services キーです。保存後、このフィールドは空になり、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。
API password：キーに対応するパスワードです。キーと同様に、保存後は再表示されません。
Billing account number：Purolator のアカウント番号です。見積もりはこのアカウントのレートを使用します。開発環境では、Purolator のドキュメントにあるテスト用アカウントを使用できます。このフィールドを空にすると、保存済みの API キーとパスワードも削除されます。
Development environment：Purolator の開発環境（devwebservices）と開発用キーを使用します。料金はテストデータです。実際に運用しているストアではオフにしてください。
Ship-from postal code：荷物を発送するカナダの郵便番号です（例：L4W 5M8）。OpenCart にはストアの郵便番号がないため、ストアの住所からは取得されません。ここに入力してください。
Service in Canada：Cheapest available（デフォルト）、Purolator Ground、Purolator Ground 9AM、Purolator Ground 10:30AM、Purolator Ground Evening、Purolator Express、Purolator Express 9AM、Purolator Express 10:30AM、Purolator Express 12PM、Purolator Express Evening のいずれか。
Service to the USA：Cheapest available（デフォルト）、Purolator Ground U.S.、Purolator Express U.S.、Purolator Express U.S. 9AM、Purolator Express U.S. 10:30AM、Purolator Express U.S. 12:00 のいずれか。
International service：Cheapest available（デフォルト）、Purolator Express International、Purolator Express International 9AM、Purolator Express International 10:30AM、Purolator Express International 12:00 のいずれか。
選択したサービスが住所で提供されていない場合は、利用可能な中で最も安いサービスが使われます。
Canadian sales taxes：GST/HST/PST/QST を除いた Purolator の料金を使用します。カナダの住所では、Purolator の合計額にこれらの税金が含まれます。ストアが配送料に独自に税金を上乗せしている場合（General の税クラス）は、税金の二重課税を防ぐためにオンにしてください。デフォルト：オフ。
CAD → (store currency) rate：Purolator の料金は CAD で表示されます。ストアのデフォルト通貨が CAD でない場合は、1 CAD がいくらのストア通貨に相当するかを入力してください（例：0.68）。この値がないと、リアルタイム料金は使用されません。デフォルト通貨が CAD の場合は空欄のままにしてください。
Default product weight (kg)：重量が設定されていない商品に使用されます。デフォルト：0.5。重量は商品の重量クラスから換算され、Purolator には切り上げた合計重量（ポンド単位の整数）として送信されます。
固定料金（API の認証情報がない場合に使われ、API から料金が返されない場合の代替としても使われます）
Country prices：ストアのデフォルト通貨による、国とカートの重量ごとの料金です（税抜き）。Add country をクリックすると行が追加され、× ボタンで削除されます。自身の行を持たないすべての国をカバーする行には、* Default (all other countries) を選択します。各行には Base 料金とサイズの列があります：XS は 1 kg まで、S は 1〜2 kg、M は 2〜3 kg、L は 3〜5 kg、XL は 5 kg を超える場合です。サイズの料金が空または 0 の場合は Base が使われます。Base が 0 の場合、または Base が空の場合、独自のサイズ料金がない重量については送料無料になります。9.99 と 9,99 のどちらも使用できます。料金が 1 つもない行は保存されず、国ごとに保存される行は 1 つだけです。
Fallback price：Country prices に行がなく、* の行もない国の料金です。空欄のままにすると、その国では配送方法が非表示になります。
Fixed price per：Order（デフォルト）は料金を 1 回だけ請求します。Item (price x quantity) は、カート内の商品数を掛けた金額を請求します。これは固定料金にのみ適用されます。リアルタイム料金は常に出荷全体に対して計算されます。
条件
Min cart weight (kg)：カートの重量がこの値より軽い場合に配送方法を非表示にします。0 は制限なし（デフォルト）を意味します。
Max cart weight (kg)：カートの重量がこの値より重い場合に配送方法を非表示にします。デフォルト：30。空欄の場合は 30 kg が使われます。0 は制限なしを意味します。
Minimum order amount：配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額に達した場合にのみ、配送方法を表示します。空欄の場合は常に表示します。
Free shipping from：配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額に達すると、配送は無料になります。その場合、Purolator へのリクエストは送信されません。送料無料を提供しない場合は空欄のままにします。
利用可能条件
Geo zone：このジオゾーン内の住所に対してのみ Purolator を提供します。All zones（デフォルト）は制限なしを意味します。ジオゾーンは System > Localisation > Geo Zones で管理します。Ignore shipping zones がオンの場合は確認されません。
Ignore shipping zones：選択されたジオゾーンに関係なく、下記の国に対して配送方法を提供します。
Countries：このモードの送付先の国です。空欄の場合は、ストアで有効になっているすべての国が対象になります。このフィールドは Ignore shipping zones がオンの場合にのみ使用されます。
詳細設定
Debug log：料金の計算結果を storage/logs/vfd_prlr_debug.log.php（OpenCart 4 では system/storage/logs/vfd_prlr_debug.log.php）に書き込みます。このファイルは Web から読み取ることはできません。デバッグログをオフにしていても、API のエラーは常に記録されます。API キー、請求アカウント、購入者の郵便番号は記録されません。作業が終わったらログをオフにしてください。ファイルが 5 MB に達すると、vfd_prlr_debug.old.log.php に移動され、新しいログが開始されます。
Log：デバッグログのサイズと最新のエントリを表示します。Clear log をクリックすると消去されます。
Remove data on uninstall：オンの場合、拡張機能のアンインストール時に Purolator の設定とログが削除されます。オフの場合は、再インストールのために保持されます。キャッシュされた料金は常に削除されます。注文済みの注文に保存された Purolator サービスは常に保持されます。
インポート / エクスポート
Export：Download JSON をクリックして、設定を JSON ファイルとして保存します。API キーとパスワードはエクスポートされません。
Import：以前にエクスポートした JSON を貼り付け、Import をクリックして設定を復元します（例：別のストアで使用する場合）。値は通常の保存と同じように確認されます。保存済みの API キーとパスワードは保持されます。
チェックアウト時の動作
OpenCart は配送方法を表示するときに、拡張機能に Purolator の料金を問い合わせます。Geo zone が設定されていて、住所がその外にある場合は、Purolator は提供されません（Ignore shipping zones がオンの場合を除く）。Requires Shipping が Yes に設定された商品のみが対象です。それ以外の商品は重量に加算されず、注文金額にも含まれません。拡張機能はまず条件を確認します：許可された国（Ignore shipping zones の場合）、カートの重量、最低注文金額。注文金額は、配送が必要な商品の価格で、クーポン割引後、税抜きの金額です。ギフト券、ポイント、ストアクレジットは考慮されません。送料無料が適用される場合、料金は 0 であり、Purolator へのリクエストは送信されません。それ以外の場合、料金を探します：まず Purolator のリアルタイム料金、次に国別の料金表、最後に代替料金です。料金がない場合は、配送方法が非表示になります。
API の認証情報がある場合、拡張機能は Purolator に Quick Estimate のリクエストを送信します。内容は、請求アカウント、発送元の郵便番号、購入者の市区町村、都道府県または州、国と郵便番号、そしてカート全体の重量（ポンド単位の整数）です。カナダの場合は有効な郵便番号、米国の場合は有効な ZIP コードが必要です。その他の国では、入力された郵便番号のまま送信されます。寸法（容積重量）は送信されません。Purolator は、購入者がフランス語でストアを閲覧している場合はフランス語で、それ以外は英語で応答します。Purolator はすべてのサービスの料金を返し、拡張機能は選択されたサービスまたは最も安いサービスを使用します。設定されている場合はカナダの販売税を除外し、CAD から料金を換算します。料金はストアのデフォルト通貨で計算され、小数点以下の桁数に丸められ、選択された Tax class の税金を含めて、購入者の通貨で表示されます。
各応答は 1 時間キャッシュされるため、同じカートでも新しいリクエストは発生しません。失敗したリクエストは 10 分間キャッシュされるため、Purolator の障害があってもチェックアウトの更新ごとに遅くなることはありません。API のタイムアウトは 10 秒です。
Purolator から料金が返されない場合（API がダウン、認証情報や郵便番号の誤り、サービスが利用できない、CAD レートがない）、購入者にはエラーは表示されません。固定料金が使われ、固定料金もない場合は配送方法が非表示になります。理由はログに記録されます。
拡張機能は料金の計算のみを行います。Purolator の出荷データの作成、送り状の印刷、集荷の予約、返品の処理、荷物の追跡は行いません。Full Estimate（寸法、複数個口、署名や危険物などのオプション）は使用せず、配送日は表示せず、複数のサービスを別々のオプションとして表示することもなく、為替レートを自動取得することもありません。購入者には Purolator のサービス名は表示されず、設定した配送方法のタイトルのみが表示されます。
OpenCart 4 では、購入者はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options のウィンドウで Purolator を選択します。この方法の動作は OpenCart 3 と同じです。
注文
Purolator のリアルタイム料金で注文が行われると、サービスは注文とともに保存されます。Sales > Orders の注文ページには、履歴の上に Purolator パネルが表示され、Purolator service（名前とコード）と Live rate (excl. tax) が示されます。配送方法がその後オフになっても、パネルは表示されたままです。固定料金または送料無料で計算された注文には、このパネルはありません。注文自体には、他の OpenCart の配送方法と同様に、配送方法のタイトルと配送料が表示されます。
OpenCart 4 は、チェックアウトごとに注文を 1 つ保持し、購入者が再度確定するたびにその注文を更新します。保存された Purolator サービスは、最新のリアルタイム料金に合わせて更新されます。注文が別の配送方法、またはリアルタイム料金のない料金に変わった場合、保存されたサービスは注文から削除されます。
ライセンスキー
拡張機能は、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Purolator は、Extensions > Extensions > Shipping > VibeFox Purolator > Edit ページで設定の上にある最初のブロックです。キーを License key に貼り付けて Activate をクリックします。その後、ブロックにはキーがマスク表示され、ステータス（ライセンスが有効な期限日や、お使いのドメインなど）と、ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key のボタンが表示されます。その下には Product: opencart-shipping-purolator の行と、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 のアカウントで解放してください。
有効なキーがない場合、Purolator の配送方法はチェックアウトで購入者に表示されず、リアルタイム料金の取得も計算も行われません。同じブラウザで管理画面にログインしている管理者ユーザーには、ストアでこの配送方法が (unlicensed — visible to admins only) と表示された状態で引き続き見えるため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 ではこのプレビューは利用できません。ストアは管理画面のログインを認識しないため、有効なキーがない場合は全員にこの方法が非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると 7 日間非表示になります。既存の注文は影響を受けません。
ライセンスの期限が切れても、拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスが自動的に再確認されます。キーの入力後最初の 14 日間は 1 日に 1 回、その後は 1 週間に 1 回です。cron ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスのステータスは常に削除されます。
トラブルシューティング
チェックアウトに Purolator が表示されない：ライセンスが有効で、Enable Purolator がオンになっていることを確認してください。Geo zone を確認してください（または Ignore shipping zones がオンになっていて、その国が許可されていることを確認してください）。重量の制限と Minimum order amount も確認してください。Purolator から料金が返されない場合、配送方法は、国の料金、* の行、または Fallback price がある場合にのみ表示されます。商品の Requires Shipping が Yes に設定されていることを確認してください。
リアルタイム料金が表示されない：拡張機能のページにある Log の欄を確認してください。API のエラーは常にそこに表示されます。Debug log をオンにして、チェックアウトを再読み込みすると詳細がわかります。API キーを使う場合、住所には有効な郵便番号（カナダ）または ZIP コード（米国）が必要です。General セクションの警告も確認してください。
ログに HTTP 401 が表示される：API キーまたはパスワードが、選択された環境と一致していません。開発用キーは Development environment がオンの場合にのみ使えます。本番用キーはオフの場合にのみ使えます。
料金が Purolator の Web サイトと異なる：Quick Estimate は、請求アカウントの料金と、ポンド単位の整数に切り上げたカートの合計重量を使用します。容積重量は含まれません。カナダの住所では、合計額に販売税が含まれます。Tax class を設定している場合は、Canadian sales taxes を使用してください。料金は CAD → (store currency) rate で換算されます。
保存後に値が消えた：Save の後に表示されたメッセージを確認してください。値が 0 以上の数値ではなかったため、保存されませんでした。通常の数値として再入力してください。
変更後に料金が古く見える：拡張機能のページで Save をクリックしてください。キャッシュされた Purolator の料金が消去されます。
ページに「Warning: You do not have permission to modify VibeFox Purolator!」と表示される：管理者ユーザーのグループは、設定の閲覧のみ可能な可能性があります。System > Users > User Groups で、グループに extension/shipping/vfd_purolator（OpenCart 3）または extension/vfd_purolator/shipping/vfd_purolator（OpenCart 4） の変更権限を付与してください。
開発者向け：Purolator API のアドレスは、設定 vfd_prlr_api_url（テスト用）で置き換えられます。この設定は設定ページにはフィールドがありません。
アンインストール
Extensions > Extensions に移動し、種類 Shipping を選択して、VibeFox Purolator の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは常に削除されます。OpenCart は常に Enable Purolator、Sort order、Tax class、Geo zone をリセットします。キャッシュされた料金は常に削除されます。Remove data on uninstall がオンの場合は、Purolator の設定とデバッグログも削除されます。オフの場合、その他の設定は保持され、拡張機能を再インストールしたときに再び使用されます。既存の注文は、配送方法と料金を保持します。注文に保存された Purolator サービスは常に保持されます。
OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧で VibeFox Purolator の横にある Uninstall（オレンジ色の − ボタン）をクリックしてから、アップロードしたパッケージを削除するために Delete（赤いゴミ箱ボタン）をクリックしてください。
Purolator は各所有者の商標です。本拡張機能は Purolator との提携や承認を受けたものではありません。