VibeFox Correios for OpenCart — ヘルプ
要件
OpenCart: 3.0.x（3.0.5.0 で検証済み）または 4.0.2 以降（4.1.0.3 で検証済み）。
PHP: 8.0 以降。
Correios の契約（リアルタイム料金のみ必要）: リアルタイム料金は Correios Web Services（CWS）の料金 API を使用し、郵送カードを持つ Correios 契約の認証情報が必要です。必要な値は 3 つです。Meu Correios のユーザー（通常は契約の CNPJ または CPF）、API のアクセスコード、郵送カード番号。アクセスコードは Correios Web Services ポータル（cws.correios.com.br。テスト環境は cwshom.correios.com.br）で生成してください。発送元の CEP も必要です。認証情報がない場合、本拡張機能は固定料金のみで動作します。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。お使いのコンピューターで解凍してください。内容は README.txt、OpenCart 3 用パッケージ vfd_correios-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ vfd_correios.ocmod.zip です。お使いの OpenCart バージョンに対応するパッケージのみをインストールしてください。ライセンスキーは両方のバージョンで同じです。
OpenCart 3
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_correios-oc3-(version).ocmod.zip を選択します。本拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。Installer を使わず、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。
2. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選択します。VibeFox Correios を見つけて Install（緑色の + ボタン）をクリックします。
3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。
4. VibeFox ライセンスキーを、Edit ページ上部のライセンスブロックにある License key に貼り付け、Activate をクリックします（ライセンスキーを参照）。
5. Correios API のユーザー、アクセスコード、郵送カード番号、発送元の CEP、サービスを入力します。ストアの既定の通貨が BRL でない場合は、BRL のレートを入力します。他の国とフォールバック用の固定料金を入力し（Configuration を参照）、Enable Correios をオンにして Save をクリックします。
OpenCart 4
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_correios.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変えたパッケージは動作しません。
2. 同じページのインストール済み拡張機能の一覧にパッケージが表示されます。その横の Install（緑色の + ボタン）をクリックします。
3. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選択します。VibeFox Correios を見つけて Install（緑色の + ボタン）をクリックし、続いて Edit（鉛筆のボタン）をクリックします。
4. ライセンスキーと設定は、OpenCart 3 の手順 4 と 5 と同じように入力します。設定ページとその項目は両方のバージョンで同じです。
インストール後は、Enable Correios をオンにして保存するまで、この配送方法は無効のままです。アンインストール後に拡張機能を再インストールした場合、保持されていた Correios の設定が再び使用されます。
Configuration
すべての設定は拡張機能のページにあります：Extensions > Extensions > Shipping > VibeFox Correios > Edit。セクションは左側に一覧表示されます。ページ下部の 1 つの Save ボタンで、ページを再読み込みせずにページ全体を保存します。保存のたびに、キャッシュされた Correios の料金と API トークンも消去されます。数値はピリオドまたはカンマで入力できます。この拡張機能の変更権限を持つ管理者ユーザーのみが設定を保存できます。
リアルタイム料金または配送方法が機能しない場合、ページに警告が表示されます。3 つの認証情報のうち一部しか入力されていない場合、発送元の CEP がない場合、ストアの通貨が異なるのに BRL のレートがない場合、認証情報も固定料金もない場合です。各警告には、その間は固定料金が使われるのか、配送方法が非表示になるのかが示されます。ストアに単位が kg の重量クラスまたは単位が cm の長さクラスがない場合にも警告が表示されます。その場合、商品の単位はそのクラスの単位名に基づいて換算されます（不明な単位は kg または cm として扱われます）。System > Localisation > Weight Classes と Length Classes を確認してください。
配送方法のタイトルが空または無効（最大 64 文字、< > ; = # { } は使用不可）である場合、Country prices の数値欄や料金が 0 以上の数値でない場合、BRL のレートが 0 の場合、Min cart weight が Max cart weight より大きい場合、発送元の CEP が 8 桁でない場合、その他のサービスコードが 5 桁を超える場合、または Sort order が整数でない場合は、メッセージとともに保存が拒否されます。値を修正するまで、何も保存されません。
一般
設定はすべてのジオゾーンに適用されます。Conditions でジオゾーンに限定するか、Ignore shipping zones で国のリストに限定することができます。
Enable Correios: チェックアウトで Correios を表示または非表示にします。既定値: オフ。
Method title: カートとチェックアウトで購入者に表示される配送方法の名前。既定値: Correios。必須。
Sort order: チェックアウトの配送方法の中での Correios の表示順。整数。
Correios API（ブラジルのリアルタイム料金）
ブラジルの住所の料金は Correios 料金 API から取得されます。API が料金を返さない場合（API の停止、CEP が対応範囲外、荷物が大きすぎる場合）は、Country prices の固定料金が使われます。固定料金もない場合は、配送方法が非表示になります。エラーの詳細はログに記録され、購入者には表示されません。
API user: Meu Correios ポータルへのログイン名。通常は契約の CNPJ または CPF です。この欄を消去すると、保存されているアクセスコードも消去されます。
Access code: Correios Web Services ポータルで生成される API のアクセスコード（código de acesso）。ポータルのパスワードではありません。保存後、この欄は空のままになり、Saved — leave empty to keep it (empty the API user as well to remove it). と表示されます。変更する場合にのみ新しい値を入力してください。保存されたコードを削除するには、API user を空にして保存します。
Posting card: 契約の郵送カード（cartão de postagem）番号。10 桁で、通常は 2 つの 0 で始まります（例: 0012345678）。短い番号は先頭に 0 を補って入力されます。番号は Correios の Correios Fácil のページで確認できます。
Homologation: Correios のテスト環境（homologation）を使用します。リクエストはテスト用のアクセスコードを使って apihom.correios.com.br に送信されます。本番のストアではオフにしてください。
Origin CEP: 荷物の発送元の CEP（8 桁）。例: 01001-000。
Service: チェックアウトで料金を計算する Correios のサービス。通常料金のコード: PAC（04510、既定）、SEDEX（04014）、SEDEX 12（04782）、SEDEX 10（04790）、SEDEX Hoje（04804）。契約のコード: PAC（03298）、SEDEX（03220）、SEDEX 12（03140）、SEDEX 10（03158）、SEDEX Hoje（03204）、Correios Mini Envios（04227）。契約のコードには、そのサービスを含む契約の郵送カードが必要です。
Other service code: 任意。一覧にない、契約内の 5 桁のサービスコード（例: 03085）。短いコードは先頭に 0 を補って使用されます。入力すると、Service の代わりにこのコードが使用されます。
Package format: Correios に送信される荷物の種類。
Default product weight (kg): 重量が設定されていない各商品について Correios に送信される重量。既定値: 0.3。商品の重量とサイズは、重量と長さのクラスから換算され、カートは 1 つの荷物として料金が計算されます。
BRL → store currency rate: フィールド名にはストアの既定の通貨が表示されます（例: BRL → EUR rate）。Correios の料金は BRL で設定されています。既定の通貨が BRL でない場合は、BRL 1 単位がお使いの通貨の何単位に相当するかを入力してください（例: 0.17）。入力しない場合、リアルタイム料金は使用されません。レートは 0 より大きい必要があります。既定の通貨が BRL の場合は、空欄のままにしてください。
固定料金（ブラジル以外の国、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 の行は、独自の行がないすべての国の料金を設定します。行がない国（* にも含まれない国）には固定料金は適用されません。1 行には少なくとも 1 つの料金が必要です。基本料金が 0 の場合、その国では送料無料になります。
Fixed price per: Order（既定）は料金を 1 回だけ請求します。Item (price × quantity) は、カート内の商品点数を掛けた料金を請求します。これは固定料金にのみ適用されます。リアルタイム料金は常に荷物全体について計算されます。
Conditions
Min cart weight (kg): カートの重量がこの値より少ない場合、配送方法を非表示にします。0 は制限なしを意味します。Max cart weight より大きくすることはできません。
Max cart weight (kg): カートの重量がこの値より多い場合、配送方法を非表示にします。既定値: 30。0 は制限なし、空欄は 30 kg を意味します。Correios の PAC と SEDEX の荷物は最大 30 kg まで可能です。
Minimum order amount: 配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額に達した場合にのみ、配送方法を表示します。常に表示する場合は空欄のままにしてください。
Free shipping: 下記の金額以上で送料無料を有効にします。
Free shipping from: 配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額以上になると送料が無料になります。その場合、API へのリクエストは行われません。
Tax class: 送料に加算される税率クラス、または No tax（既定）。
Geo zone: この地域の住所にのみ Correios を提供します。All zones（既定）は制限なしを意味します。ジオゾーンは System > Localisation > Geo Zones で管理します。Ignore shipping zones と併用する場合は使用されません。
配送ゾーンを使用しない場合の利用可否
通常、配送方法は Conditions で選択したジオゾーンで提供されます（何も選択されていない場合はすべてのゾーンで提供されます）。
Ignore shipping zones: 一致するジオゾーンに関係なく、下記の国に対して配送方法を提供します。その場合、Conditions の Geo zone は確認されません。
Countries: このモードの配送先の国。空欄の場合、ストアで有効なすべての国が対象になります。このフィールドは Ignore shipping zones がオンの場合にのみ使用されます。
詳細設定
Debug log: 料金の計算を storage/logs/vfd_crr_debug.log.php（OpenCart 4 では system/storage/logs/vfd_crr_debug.log.php）に書き込みます。このファイルはウェブから読み取ることはできません。このオプションがオフでも、API のエラーは常に記録されます。API のユーザー、アクセスコード、郵送カード、トークン、購入者の CEP は記録されません。ファイルが 5 MB に達すると、vfd_crr_debug.old.log.php に移動され、新しいログが開始されます。
Log: デバッグログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログが空になります。
Remove data on uninstall: オンにすると、拡張機能のアンインストール時に Correios の設定とログが削除されます。オフ（既定）の場合は、再インストール用に保持されます。注文とともに保存された Correios のサービスは、常に保持されます。
インポート / エクスポート
Export: Download JSON をクリックすると、設定が JSON ファイルとして保存されます。アクセスコードはエクスポートされません。
Import: 以前にエクスポートした JSON を貼り付けて Import をクリックすると、設定が復元されます（別のストアでの利用など）。値は通常の保存と同じように検証されます。保存されたアクセスコードは保持されます。
チェックアウトでの動作
OpenCart が配送方法を表示する際、拡張機能に Correios の料金を問い合わせます。Geo zone が設定されていて（かつ Ignore shipping zones がオフ）、住所がそのゾーンの外にある場合、Correios は提供されません。Requires Shipping が Yes に設定されている商品のみが計算に含まれます。その他の商品は重量に加算されず、注文金額にも含まれません。次に拡張機能は、許可された国（Ignore shipping zones の場合）、カートの重量、最低注文金額などの条件を確認します。注文金額は、配送が必要な商品の、クーポン割引後かつ税抜きの価格です。送料無料が適用される場合、料金は 0 となり、Correios へのリクエストは送信されません。
認証情報が設定されているブラジルの住所の場合、拡張機能はまず郵送カードの API トークンを取得します。このトークンには契約番号と地域事務所の番号も含まれるため、料金はお客様の契約の料金になります。次に、発送元と届け先の CEP、グラム単位の荷物の重量、cm 単位の荷物のサイズに基づき、選択したサービスの料金をリクエストします。料金のリクエストは、届け先の CEP が 8 桁の場合にのみ行われます。すべての商品にサイズがある場合は、それらから荷物のサイズを推定します。そうでない場合は、Correios の最小サイズを送信します。30 kg を超える荷物は API に送信されません。BRL の料金はお客様のレートで換算されます。料金はストアの既定の通貨で計算され、その通貨の小数点以下の桁数で丸められ、選択した Tax class の税金を含めて購入者の通貨で表示されます。
各料金は 1 時間キャッシュされます。失敗したリクエストは 10 分間キャッシュされるため、API の停止によってチェックアウトの更新のたびに遅くなることはありません。トークンは期限の少し前までキャッシュされ（最長で OpenCart のキャッシュの有効期間まで、既定では 1 時間）、自動的に更新されます。Correios がトークンを拒否した場合は、新しいトークンが要求され、料金のリクエストが 1 回だけ再試行されます。API のタイムアウトは 12 秒です。
API が料金を返さない場合は固定料金が使用され、固定料金がない場合は配送方法が非表示になります。購入者に API のエラーの詳細が表示されることはありません。それらはデバッグログに記録されます。
拡張機能は料金の計算のみを行います。Correios の国際料金（Exporta Fácil、Packet）、配送日数の見積もり、送り状、事前登録、税関申告、追跡情報は取得しません。購入者は Correios の窓口やロッカーを選択できません。追加サービス（申告価格、手渡し、受領通知）は追加されません。ストアごとに 1 つの Correios のサービスのみが表示され、通貨レートは自動的に更新されません。
OpenCart 4 では、お客様はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options のウィンドウで Correios を選択します。この方法は OpenCart 3 と同じように動作します。
注文
Correios で注文が行われると、拡張機能は配送料金がどのように計算されたかを保存します。Sales > Orders の注文ページには、Correios service（例: PAC — contract (03298)）と Price を含む Correios ブロックが表示されます。料金の種類は Live price (Correios API)、Fixed price、または Free shipping です。このブロックは管理画面にのみ表示され、購入者へのメールには表示されません。また、拡張機能が無効になっていても表示されたままです。
OpenCart 4 では、チェックアウトで注文は 1 件だけ保持され、お客様が再度確定すると更新されます。注文の Correios データもそれに合わせて更新され、お客様が別の配送方法に変更すると、その注文では Correios のブロックは表示されなくなります。
ライセンスキー
本拡張機能は、vibefox.net で取得した VibeFox ライセンスキーで動作します。License — VibeFox Correios のライセンスブロックは、Extensions > Extensions > Shipping > VibeFox Correios > Edit ページで設定の上にある最初のブロックです。キーを License key に貼り付けて Activate をクリックしてください。その後、ブロックにはキーがマスク表示された状態、ステータス（例: ライセンスの有効期限日とお使いのドメイン）、そして Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）のボタンが表示されます。その下には Product: opencart-shipping-correios の行と、Manage licenses and domains in your account のリンクがあり、vibefox.net のアカウントが開きます。キーを変更できるのは、本拡張機能に対する Modify 権限を持つ管理者ユーザーのみです。ブロックの文言は管理画面の言語に従います（英語とロシア語を含みます）。
キーが受け付けられない場合、ブロックにその理由が表示されます。例: Key not found、This key belongs to another product、Domain limit reached、または日付付きの License expired on。ストアのアドレスを変更した後、またはアカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、拡張機能は最後に確認できたステータスで動作を続けます。
1 つのキーは 1 つのドメインでのみ使用できます。ドメインは OpenCart の設定にあるストアのアドレスです。ストアからキーを削除しても、ドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。
有効なキーがない場合、チェックアウトで Correios は顧客に表示されず、料金も計算されません。同じブラウザで管理画面にログインしている管理者ユーザーには、ストアで引き続きこの配送方法が表示され、(unlicensed — visible to admins only) と表示されます。そのため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 ではこのプレビューは利用できません。ストアは管理画面のログインを認識しないため、有効なキーがない場合は全員にこの配送方法が表示されません。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると 7 日間非表示になります。既存の注文には影響しません。
ライセンスの期限が切れても拡張機能は動作し続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスは自動的に再確認されます。キーの入力後最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
チェックアウトに Correios が表示されない: ライセンスが有効であること、Enable Correios がオンであることを確認してください。Geo zone（または Ignore shipping zones と Countries）、重量の制限、Minimum order amount を確認してください。リアルタイム料金がない場合は、その国または * に対する固定料金が必要です。商品の Requires Shipping が Yes に設定されていることを確認してください。
Correios の料金ではなく固定料金が表示される: 拡張機能のページにある Log の欄を確認してください。Correios のエラーは、そこに記録されています。アクセスコードの誤り、契約にないサービス、CEP が対応範囲外、30 kg を超える荷物、サイズ制限の超過などです。また、発送元の CEP が設定されていること、購入者の CEP が 8 桁であること、既定の通貨が BRL でない場合は BRL のレートが設定されていることも確認してください。すべての計算を確認するには Debug log をオンにしてください。
トークンのリクエストが失敗する: API のユーザー、アクセスコード、郵送カード、環境を確認してください。テスト用のアクセスコードは Homologation がオンの場合にのみ機能し、本番用のコードはオフの場合にのみ機能します。
変更後も料金が古いまま: 拡張機能のページで Save をクリックしてください。これにより、キャッシュされた料金と API トークンが消去されます。
ページに "Warning: You do not have permission to modify VibeFox Correios!" と表示される: 管理者ユーザーのグループには、設定の閲覧権限しかない可能性があります。System > Users > User Groups で、そのグループに extension/shipping/vfd_correios（OpenCart 3）または extension/vfd_correios/shipping/vfd_correios（OpenCart 4）の変更権限を付与してください。
開発者向け: Correios API のホストは、設定 vfd_crr_api_url（テスト用）で置き換えられます。設定ページにこの項目の入力欄はありません。
アンインストール
Extensions > Extensions に移動し、種類 Shipping を選んで、VibeFox Correios の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは常に削除されます。OpenCart は常に Enable Correios、Sort order、Tax class、Geo zone をリセットします。キャッシュされた料金とトークンは常に削除されます。Remove data on uninstall がオンの場合は、Correios の設定とデバッグログも削除されます。オフの場合は、他の設定が保持され、拡張機能を再インストールしたときに再び使用されます。注文とともに保存された Correios のサービスは常に保持され、既存の注文は配送方法と送料をそのまま維持します。
OpenCart 4 で拡張機能のファイルも削除するには、アンインストールの後に Extensions > Installer に移動し、インストール済み拡張機能の一覧で VibeFox Correios の横にある Uninstall（オレンジ色の − ボタン）をクリックし、次にアップロードしたパッケージを削除するために Delete（赤いごみ箱のボタン）をクリックします。
Correios は、各所有者の商標です。本拡張機能は Correios と提携しておらず、Correios による承認や支持も受けていません。