VibeFox Canada Post for OpenCart — ヘルプ
要件
OpenCart：3.0.x（3.0.5.0 で動作確認済み）、または 4.0.2 以降（4.1.0.3 で動作確認済み）。
PHP：8.0 以降。
Canada Post Developer Program（リアルタイム料金のみ必要）：リアルタイム料金は Canada Post Rating API を使用します。Canada Post のウェブサイトで Canada Post Developer Program に参加し、API キーと顧客番号をコピーしてください。API キーは username:password の形式で、Canada Post は開発（サンドボックス）環境と本番環境で別々のキーを発行します。また、発送元となるカナダの郵便番号も必要です。固定料金のみを使用する場合、API キーは不要です。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。お使いのコンピューターで解凍してください。中には README.txt、OpenCart 3 用パッケージ vfd_canada_post-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ vfd_canada_post.ocmod.zip が含まれています。お使いの OpenCart バージョン用のパッケージのみをインストールしてください。ライセンスキーは両方のバージョンで同じです。
OpenCart 3
1. 管理画面で Extensions > Installer に進み、Upload をクリックして、ファイル vfd_canada_post-oc3-(version).ocmod.zip を選択します。この拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。Installer を使う代わりに、パッケージ内の upload フォルダの内容をストアのルートフォルダにコピーすることもできます。
2. Extensions > Extensions に進み、拡張機能の種類として Shipping を選択します。VibeFox Canada Post を見つけて、Install（緑色の + ボタン）をクリックします。
3. Edit（鉛筆のボタン）をクリックして、設定ページを開きます。
4. Edit ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを入力し、Activate をクリックします（License key の項を参照）。
5. リアルタイム料金を使う場合は、API のユーザー名とパスワード、顧客番号、発送元の郵便番号を入力します。ストアの既定通貨が CAD でない場合は、CAD のレートを入力します。固定料金または代替料金が必要な場合は、Country prices に入力します（設定の項を参照）。Enable Canada Post をオンにして、Save をクリックします。
OpenCart 4
1. 管理画面で Extensions > Installer に進み、Upload をクリックして、ファイル vfd_canada_post.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変更したパッケージは動作しません。
2. パッケージは同じページのインストール済み拡張機能の一覧に表示されます。その横にある Install（緑色の + ボタン）をクリックします。
3. Extensions > Extensions に進み、種類 Shipping を選択します。VibeFox Canada Post を見つけて、Install（緑色の + ボタン）をクリックし、次に Edit（鉛筆のボタン）をクリックします。
4. ライセンスキーと設定は、OpenCart 3 の手順 4 および 5 と同じように入力します。設定ページとそのフィールドは両方のバージョンで同じです。
インストール後は、Enable Canada Post をオンにして保存するまで、この配送方法はオフのままです。アンインストール後に拡張機能を再インストールすると、保持した設定が再び使用されます。
設定
すべての設定は拡張機能のページにあります：Extensions > Extensions > Shipping > VibeFox Canada Post > Edit。セクションは左側に表示されます。Save ボタンを 1 回押すと、ページを再読み込みせずにページ全体が保存されます。保存するたびに、キャッシュされた Canada Post の料金も消去されます。この拡張機能の変更権限を持つ管理者ユーザーだけが設定を保存できます。
値が正しくない場合、ページはエラーを表示し、何も保存されません。たとえば、Country prices の数値欄や料金が 0 以上の数字ではない場合（例：-1、12abc）、CAD レートが 0 の場合、Min cart weight (kg) が Max cart weight (kg) より大きい場合、Method title が 64 文字を超える場合、または文字 < > ; = # { } を含む場合、Sort order が整数でない場合、税クラスまたはジオゾーンが不明な場合などです。ストアに単位 "kg" の重量クラスや単位 "cm" の長さクラスがない場合、ページは、重量と寸法はそのクラスの単位名（kg、g、lb、oz、cm、mm、m、in）に従って換算されること、またその他の単位は kg または cm として扱われることを警告します。
保存後、設定が意図どおりに機能しない場合、ページは警告を表示します。API のユーザー名とパスワードのどちらか一方だけが入力されている場合、発送元の郵便番号がカナダの郵便番号（A1A 1A1 形式）でない場合、別の通貨のストアで CAD レートがない場合、API 認証情報も固定料金もない場合です。警告には、その間の動作も示されます。国ごとの固定料金が使われるか、Country prices の表が空の場合は、チェックアウトで配送方法が非表示になります。
一般
この設定はすべてのジオゾーンに適用されます。料金は常にこの拡張機能から提供されます。Canada Post のリアルタイム料金か、国ごとの固定料金のいずれかです。
Enable Canada Post：チェックアウトで Canada Post を表示するか非表示にするかを切り替えます。既定値：オフ。
Method title：チェックアウトで購入者に表示される配送方法の名前です。既定値：入力欄が空の場合も Canada Post。最大 64 文字。
Tax class：OpenCart が送料に加算する税クラス、または No tax（非課税）です。
Sort order：チェックアウトの配送方法の中で Canada Post が表示される順序です。
Canada Post API（リアルタイム料金）
API のユーザー名とパスワードを入力すると、料金は Canada Post Rating API から取得されます。API が料金を返さない場合（API が停止している、郵便番号が正しくない、サービスが利用できないなど）は、Country prices の固定料金が使われます。固定料金がなければ、配送方法は非表示になります。このセクションには Canada Post Developer Program へのリンクがあり、そこで API キーと顧客番号を確認できます。エラーの詳細はログに記録され、購入者には表示されません。
API username：API キーのコロン（:）より前の部分です。開発用キーは Sandbox と組み合わせて使い、本番ストアでは本番用キーを使います。
API password：API キーのコロン（:）より後の部分です。保存後、この欄は空のままになり、A password is saved. Leave empty to keep it; clear the API username and save to remove both. と表示されます。変更する場合にのみ新しい値を入力してください。パスワードは入力どおりに保存され、ログに記録されることはありません。
Customer number：顧客番号を入力すると、Canada Post はお使いのアカウントの法人（割引）料金を返します。窓口（通常）料金を使う場合は空のままにしてください。空白は削除されます。
Contract number：契約顧客向けの任意項目です。顧客番号と一緒にのみ使用されます。
Sandbox：開発用 API キーでテストするために、Canada Post の開発環境を使用します。料金はテストデータです。本番ストアではオフにしてください。既定値：オフ。
Ship-from postal code：荷物を発送するカナダの郵便番号です（例：K1A 0B1）。リアルタイム料金に必要です。
Service in Canada：カナダの住所向けのサービスです：最安の利用可能なサービス、Regular Parcel（DOM.RP、既定値）、Expedited Parcel（DOM.EP）、Xpresspost（DOM.XP）、Priority（DOM.PC）。
Service to the USA：最安の利用可能なサービス（既定値）、Expedited Parcel USA（USA.EP）、Tracked Packet USA（USA.TP）、Small Packet USA Air（USA.SP.AIR）、Xpresspost USA（USA.XP）、Priority Worldwide parcel USA（USA.PW.PARCEL）。
International service：最安の利用可能なサービス（既定値）、International Parcel Surface（INT.IP.SURF）、International Parcel Air（INT.IP.AIR）、Tracked Packet International（INT.TP）、Small Packet International Surface（INT.SP.SURF）、Small Packet International Air（INT.SP.AIR）、Xpresspost International（INT.XP）、Priority Worldwide parcel International（INT.PW.PARCEL）。
選択したサービスが住所や荷物に提供されていない場合は、最安の利用可能なサービスが使われます。
Use Canada Post prices without GST/HST/PST：カナダの住所では、Canada Post の料金にこれらの税金が含まれます。OpenCart が配送料に税金を加算する場合（上記の Tax class）にオンにすると、税金の二重課税を防げます。
CAD to … rate：フィールド名にはストアの既定通貨が表示されます（例：CAD to USD rate）。Canada Post の料金は CAD です。既定通貨が CAD でない場合は、CAD 1 単位が自国通貨で何単位に相当するかを入力してください（例：0.68）。入力しないと、リアルタイム料金は使用されません。既定通貨が CAD の場合は空のままにしてください。レートは 0 より大きい値である必要があります。
Default product weight (kg)：重量が設定されていない商品ごとに Canada Post へ送信される重量です。既定値：0.5。商品の重量と寸法は商品の重量クラスと長さクラスから換算され、カートは 1 つの荷物として計算されます（最大 30 kg）。
固定料金（API 認証情報がない場合に使用され、API が料金を返さない場合の代替として使われます）
Country prices：国の表です。ストアの既定通貨で、税抜きの Base 料金と、カート重量ごとの料金を入力します：XS は 1 kg まで、S は 1〜2 kg、M は 2〜3 kg、L は 3〜5 kg、XL は 5 kg を超える場合。サイズの料金が空または 0 の場合は Base 料金が使われます。Add country をクリックすると行を追加できます。* All other countries の行は、独自の行がないすべての国の料金を設定します。行がない国（* もない場合）には固定料金はありません。基本料金が 0 の国は送料無料になります。
Fixed price per：Order（既定値）は料金を 1 回だけ請求します。Item (price × quantity) は、カート内の商品数を掛けた料金を請求します。これは固定料金にのみ適用されます。リアルタイム料金は常に荷物全体に対して計算されます。
条件
Min cart weight (kg)：このカート重量を下回る場合は配送方法を非表示にします。0 は制限なし（既定値）です。
Max cart weight (kg)：このカート重量を超える場合は配送方法を非表示にします。既定値：入力欄が空でも 25。0 は制限なしです。Canada Post の荷物は最大 30 kg まで可能です。
Minimum order amount：配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額に達した場合にのみ配送方法を表示します。常に表示する場合は空のままにしてください。
Free shipping：下記の金額以上で送料無料にする場合にオンにします。
Free shipping from：配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額以上の場合、送料は無料になります。その場合、API へのリクエストは行われません。Free shipping がオンの場合にのみ使用されます。
Geo zone：このジオゾーン内の住所にのみ Canada Post を提供します。All zones（既定値）は、どこでも有効であることを意味します。Ignore shipping zones がオンの場合は使用されません。ジオゾーンは System > Localisation > Geo Zones で管理されます。
配送ゾーンを使用しない場合の提供
通常、配送方法は Conditions で選択したジオゾーン内で提供されます。
Ignore shipping zones：ジオゾーンに関係なく、下記の国に対して配送方法を提供します。
Countries：このモードの配送先の国です。空のままにすると、ストアで有効なすべての国が許可されます。Ignore shipping zones がオンの場合にのみ使用されます。
詳細
Debug log：料金計算のログを storage/logs/vfd_canada_post.log.php に書き込みます。このファイルはウェブから読み取れません。5 MB に達すると、vfd_canada_post.old.log.php に移動され、新しいログが開始されます。このオプションがオフでも、API エラーは常に記録されます。API キー、顧客番号、購入者の郵便番号は記録されません。
Log：ログのサイズと最新のエントリを表示します。Clear log をクリックすると消去されます。
Remove data on uninstall：オンにすると、拡張機能のアンインストール時に設定、注文のサービス情報、キャッシュされた料金、ログが削除されます。オフ（既定値）の場合、再インストールに備えてこれらは保持されます。注文が変更されることはありません。
インポート / エクスポート
Export：Download JSON をクリックすると、設定を JSON ファイルとして保存できます。API パスワードはエクスポートされません。
Import：以前にエクスポートした JSON を貼り付け、Import をクリックすると、設定を復元できます（例：別のストアで）。値は通常の保存と同じように検証されます。保存済みの API パスワードは、API のユーザー名が入力されたままであれば保持されます。
チェックアウトでの動作
OpenCart が配送方法を表示する際、拡張機能に Canada Post の料金を問い合わせます。Geo zone が設定されていて（かつ Ignore shipping zones がオフ）、住所がそのゾーン外にある場合、Canada Post は提供されません。Requires Shipping を Yes に設定した商品のみが計算に含まれます。その他の商品は重量に加算されず、注文金額にも含まれません。拡張機能はまず条件を確認します。許可された国（Ignore shipping zones の場合）、カート重量、最低注文金額です。注文金額は、配送が必要な商品の価格で、クーポン割引後、税金の前です。ギフト券、ポイント、ストアクレジットは考慮されません。送料無料が適用される場合、料金は 0 となり、Canada Post へのリクエストは送信されません。
API 認証情報がある場合、拡張機能は Canada Post に発送元の郵便番号、配送先、荷物の重量、そしてすべての商品に寸法がある場合は推定荷物サイズを送信します。カナダの場合は配送先が郵便番号、米国の場合は ZIP コード、その他の国では国のみです。リアルタイム料金は、カナダまたは米国の住所に有効な郵便番号または ZIP コードがある場合にのみリクエストされます。Canada Post は荷物のすべてのサービスを返します。拡張機能は、配送先グループで選択されたサービス、または最安のサービスを選び、Use Canada Post prices without GST/HST/PST がオンの場合はカナダの売上税を除き、CAD の料金をお使いのレートで換算します。料金は既定通貨で計算され、その小数桁に丸められ、選択した Tax class の税金を加えて、購入者の通貨で表示されます。
各レスポンスは 1 時間キャッシュされるため、同じカートと住所では新しいリクエストは発生しません。失敗したリクエストは 10 分間キャッシュされるため、Canada Post の障害がチェックアウトの更新のたびに遅延を引き起こすことはありません。API のタイムアウトは 10 秒です。30 kg を超える荷物は API に送信されません。
API が料金を返さない場合は固定料金が使われ、固定料金がなければ配送方法は非表示になります。購入者に API のエラーの詳細が表示されることはありません。ログに記録されます。
拡張機能は料金の計算のみを行います。発送の作成、ラベルの印刷、マニフェストや返品の作成、荷物の追跡は行いません。購入者は郵便局や受け取り場所を選択できません。配送日、保険、署名オプションを含まない、1 つの Canada Post 料金を表示します。カートは常に 1 つの荷物として計算され、為替レートは自動では更新されません。
OpenCart 4 では、購入者はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options ウィンドウで Canada Post を選択します（例：Canada Post - $12.50）。この配送方法は OpenCart 3 と同じように動作します。
注文
Canada Post で注文が行われると、拡張機能はその料金の計算方法を保存します。管理画面の注文ページ（Sales > Orders、注文を開く）には、Canada Post のブロックが表示されます：
Canada Post service：リアルタイム料金のサービス名とコード（例：Regular Parcel（DOM.RP））。
Price source：Live rate (Canada Post Rating API)、Fixed price、または Free shipping。
OpenCart 4 では、このブロックは History の上に表示されます。チェックアウトは注文を 1 件だけ保持します。購入者が注文を再確認すると、保存されたサービスと料金のソースは置き換えられ、購入者が別の配送方法を選択した場合は削除されます。
サービスは注文メールや購入者の注文ページには追加されません。それらには、他の OpenCart 配送方法と同様に、配送方法の名前と送料が表示されます。
ライセンスキー
この拡張機能は、vibefox.net で取得した VibeFox ライセンスキーで動作します。License — VibeFox Canada Post のライセンスブロックは、Extensions > Extensions > Shipping > VibeFox Canada Post > Edit ページで設定より上にある最初のブロックです。License key にキーを入力し、Activate をクリックします。その後、ブロックにはマスクされたキー、ステータス（例：ライセンスの有効期限日とお使いのドメイン）、Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）のボタンが表示されます。その下には Product: opencart-shipping-canada-post の行と、お使いの 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 アカウントで枠を解放してください。
有効なキーがない場合、チェックアウトで購入者に Canada Post は表示されず、料金も計算されません。同じブラウザーで管理画面にログインしている管理者ユーザーには、(unlicensed — visible to admins only) と表示された状態で、ストアに配送方法が表示されます。そのため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 では、このプレビューは利用できません。ストアは管理画面へのログインを認識しないため、有効なキーがない場合、配送方法は全員に対して非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると、7 日間非表示になります。既存の注文には影響しません。
ライセンスの有効期限が切れても、拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスは自動的に再確認されます。キーの入力後最初の 14 日間は 1 日に 1 回、その後は週に 1 回です。cron ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスのステータスは常に削除されます。
トラブルシューティング
チェックアウトに Canada Post が表示されない：ライセンスが有効で、Enable Canada Post がオンになっているか確認してください。Geo zone を確認するか、Ignore shipping zones がオンで国が許可されているか確認してください。重量制限と Minimum order amount を確認し、商品の Requires Shipping が Yes になっているか確認してください。料金が存在する必要があります。API 認証情報がある場合、住所には有効な郵便番号（カナダ）または ZIP コード（米国）が必要です。そうでない場合は、その国または * の固定料金が存在する必要があります。
リアルタイム料金が表示されない：Debug log をオンにし、チェックアウトを再読み込みして、拡張機能のページの Log 欄を確認してください。理由が表示されます：API のユーザー名またはパスワードの不足、発送元または配送先の郵便番号の不正、CAD レートの不足、30 kg を超える荷物、または Canada Post のエラーメッセージです。その間、固定料金がある場合は、購入者には固定料金が表示されます。
料金が Canada Post のウェブサイトと異なる：顧客番号を入力すると、アカウントの法人（割引）料金が得られます。入力しない場合は、通常（窓口）料金になります。カナダの住所では、Canada Post の料金に GST/HST/PST が含まれます。料金は CAD レートで換算されます。
送料に税金が二重にかかる：Use Canada Post prices without GST/HST/PST をオンにするか、Tax class を No tax に設定してください。
本番ストアで料金をテストする：Sandbox をオフにし、本番用 API キーを使用してください。
変更後に料金が古く見える：拡張機能のページで Save をクリックしてください。これにより、キャッシュされた Canada Post の料金が消去されます。
ページに "Warning: You do not have permission to modify VibeFox Canada Post!" と表示される：管理者のユーザーグループに設定の閲覧権限しかない可能性があります。System > Users > User Groups で、そのグループに extension/shipping/vfd_canada_post（OpenCart 3）または extension/vfd_canada_post/shipping/vfd_canada_post（OpenCart 4）の変更権限を付与してください。
開発者向け：Canada Post の API アドレスは、設定 vfd_cp_api_url（テスト用）で置き換えられます。設定ページには、この項目の入力欄はありません。
アンインストール
Extensions > Extensions に進み、種類 Shipping を選択して、VibeFox Canada Post の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスのステータスは常に削除されます。OpenCart は常に Enable Canada Post、Sort order、Tax class、Geo zone をリセットします。キャッシュされた料金は常に削除されます。Remove data on uninstall がオンの場合、設定、注文のサービス情報、ログも削除されます。オフの場合、他の設定は保持され、拡張機能を再インストールすると再び使用されます。既存の注文は、配送方法と送料をそのまま保持します。
OpenCart 4 では、拡張機能のファイルも削除する場合は、アンインストール後に Extensions > Installer に進み、インストール済み拡張機能の一覧で VibeFox Canada Post の横にある Uninstall（オレンジ色の − ボタン）をクリックし、次にアップロードしたパッケージを削除するために Delete（赤いゴミ箱のボタン）をクリックします。
Canada Post は、各所有者の商標です。この拡張機能は Canada Post と提携しておらず、同社の承認も受けていません。