VibeFox Correios for PrestaShop — ヘルプ
要件
PrestaShop: 8.0 から 9.x。
PHP: 8.0 以降。モジュールは、それより古い PHP バージョンではインストールできません。
Correios の契約（リアルタイム料金の場合のみ）: リアルタイム料金は Correios Web Services（CWS）の料金 API を使用するため、posting card を持つ Correios の契約の認証情報が必要です。必要な情報は 3 つです。Meu Correios のユーザー（通常は契約の CNPJ または CPF）、API アクセスコード、posting card 番号。アクセスコードは Correios Web Services ポータル（cws.correios.com.br。ホモロゲーション用は cwshom.correios.com.br）で生成してください。発送元の CEP も必要です。認証情報がない場合、モジュールは固定料金のみで動作します。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
1. バックオフィスで Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックします。後からモジュール一覧で VibeFox Correios を探し、Configure をクリックすることもできます。
3. Configure ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。
4. Correios API のユーザー、アクセスコード、posting card 番号、発送元 CEP、サービスを入力します。ストアのデフォルト通貨が BRL でない場合は、BRL のレートを入力します。他の国およびフォールバック用の固定料金を入力し（設定を参照）、Save をクリックします。
インストール時に、モジュールは配達日時のテキスト Correios (Brazilian Post) を設定した Correios 配送業者を作成します。この配送業者は、すべてのゾーンとすべての顧客グループに割り当てられます。ゾーン、顧客グループ、配達日時、ロゴ、サイズ制限は Shipping > Carriers で変更できます。そこでは料金を設定しないでください。料金は常にモジュールから取得されます。
設定
すべての設定はモジュールのページにあります。Modules > Module Manager > VibeFox Correios > Configure です。各セクションには個別の Save ボタンがあり、ページ全体を保存します。保存するたびに、キャッシュされた Correios の料金と API トークンも消去されます。数値はピリオドまたはカンマで入力できます。
リアルタイム料金または配送業者が動作しない場合、ページに警告が表示されます。3 つの認証情報の一部しか入力されていない、発送元 CEP が未入力、別通貨のストアで BRL のレートが未入力、または認証情報も固定料金もない、といった場合です。各警告には、その間に固定料金が使われるのか、配送業者が非表示になるのかが記載されます。ストアの重量または寸法の単位がモジュールで認識されない場合（その場合は kg または cm として扱われます）にも警告が表示されます。その場合は International > Localization（Local units）で、kg、g、lb、oz のいずれか、および cm、mm、m、in のいずれかを設定してください。
メソッドのタイトルが空または無効（最大 64 文字）の場合、Country prices の数値フィールドや料金が 0 以上の数値でない場合、BRL のレートが 0 の場合、Min cart weight が Max cart weight より大きい場合、発送元 CEP が 8 桁でない場合、または他のサービスコードが 5 桁を超える場合は、メッセージとともに保存が拒否されます。値を修正するまで何も保存されません。
一般
Enable Correios: すべてのゾーンで配送業者を一度にオンまたはオフにします。これは Shipping > Carriers における配送業者のステータスと同じスイッチです。
Method title: カートとチェックアウトに表示される配送業者の名前。デフォルト: Correios。必須です。
Tax: 配送料に上乗せされる税ルール、または No tax（デフォルト）。
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 と Access code の両方を空にして保存します。
Posting card: 契約の posting card（cartão de postagem）番号。10 桁で、通常は 2 つのゼロで始まります（例: 0012345678）。短い番号は先頭にゼロを補って入力されます。番号は Correios の Correios Fácil ページで確認できます。
Homologation: Correios のテスト（ホモロゲーション）環境を使用します。リクエストはホモロゲーション用のアクセスコードを付けて 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）。契約コードには、そのサービスを含む契約の posting card が必要です。
Other service code: 任意。一覧にない、契約内の 5 桁のサービスコード（例: 03085）。短いコードは先頭にゼロを補って入力されます。入力されている場合は、Service の代わりに使用されます。
Package format: Correios に送信する荷物の種類。
Default product weight: kg 単位。重量が設定されていない商品ごとに Correios へ送信されます。デフォルト: 0.3。商品の重量と寸法はストアの単位から変換されます（フィールドの説明に表示されます）。カートは 1 つの荷物として料金が計算されます。
BRL → store currency rate: フィールド名にはストアのデフォルト通貨が表示されます。例: BRL → EUR rate。Correios の料金は BRL 建てです。デフォルト通貨が BRL でない場合は、1 BRL が自国通貨で何単位に相当するかを入力してください。例: 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 をクリックすると行が追加され、×印をクリックすると行が削除されます。* Default (all other countries) の行は、独自の行を持たないすべての国の料金を設定します。行がなく（* にも該当しない）国には固定料金は適用されません。料金が 1 つも入力されていない行は保存されません。数値でない料金や負の料金は、保存をエラーで中断します。基本料金を 0 にすると、その国は送料無料になります。
Fixed price per: Order は料金を 1 回だけ請求します。Item (price × quantity) は、カート内の商品数を掛けた料金を請求します。これは固定料金にのみ適用されます。リアルタイム料金は常に荷物全体について計算されます。
条件
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 へのリクエストは行われません。
配送ゾーンなしでの提供
通常、配送業者は Shipping > Carriers で割り当てられたゾーンに表示されます。
Ignore shipping zones: 該当するゾーンに関係なく、下の国に対して配送業者を提供します。保存すると、配送業者はすべてのゾーンに追加されます。このオプションをオフにすると、追加されたゾーンは削除されます。オプションがオンの間に作成されたゾーンは、自動的に追加されます。
Countries: このモードの配送先の国。空欄の場合、ストアで有効なすべての国が使われます。このフィールドは Ignore shipping zones がオンの場合にのみ使用されます。
詳細設定
Debug log: 料金の計算結果を、モジュールフォルダ内の logs/vfd_crr_debug.log.php に書き込みます。このファイルは Web から開くことはできません。API のエラーは、このオプションがオフでも常に記録されます。API のユーザー、アクセスコード、posting card、トークン、購入者の CEP は記録されません。
Log: デバッグログのサイズと最新のエントリを表示します。Clear log をクリックすると空になります。
Remove data on uninstall: オンの場合、モジュールをアンインストールすると、設定、配送業者、注文サービス、キャッシュされた料金、ログが削除されます。オフの場合、再インストールに備えてすべてが保持されます。
チェックアウト時の動作
配送のステップで、PrestaShop はモジュールに Correios の料金を問い合わせます。対象は実物の商品のみです。仮想商品は重量に加算されず、注文金額にも含まれません。モジュールはまず条件を確認します。許可された国（Ignore shipping zones と併用）、カートの重量、最低注文金額です。送料無料が適用される場合、料金は 0 となり、Correios へのリクエストは送信されません。
認証情報が設定されているブラジルの住所の場合、モジュールはまず posting card の API トークンを取得します。このトークンには契約番号と地域事務所番号も含まれるため、料金はお客様の契約の料金になります。次に、発送元と配送先の CEP、グラム単位の荷物の重量、cm 単位の荷物のサイズに基づいて、選択したサービスの料金をリクエストします。料金がリクエストされるのは、配送先の CEP が 8 桁の場合のみです。すべての商品にサイズがある場合は、それらから荷物のサイズを推定します。そうでない場合は、Correios の最小サイズが送信されます。30 kg を超える荷物は API に送信されません。BRL の料金は、お客様のレートで換算されます。料金はストアのデフォルト通貨で計算され、その後お客様のカートの通貨で表示されます。
各料金は荷物ごとに 1 時間キャッシュされます。失敗したリクエストは 10 分間キャッシュされるため、API の停止によってチェックアウトの更新が毎回遅くなることはありません。トークンは有効期限の少し前までキャッシュされ、自動的に更新されます。Correios がトークンを拒否した場合は、新しいトークンを取得して料金のリクエストを 1 回だけ繰り返します。API のタイムアウトは 12 秒です。
API が料金を返さない場合は、固定料金が使われます。固定料金がなければ、配送業者は非表示になります。お客様が API のエラーの詳細を見ることはありません。詳細はデバッグログに記録されます。
注文のある配送業者を Shipping > Carriers で編集した場合、PrestaShop はそれを配送業者の新しいバージョンとして保存します。モジュールは自動的に新しいバージョンに従います。
モジュールは料金の計算のみを行います。Correios の国際料金（Exporta Fácil、Packet）、配達日数の見積もり、送り状、事前登録、税関申告書、追跡は扱いません。お客様は Correios の営業所やロッカーを選択できません。追加サービス（申告価額、手渡し、受領通知）は追加されません。ストアごとに 1 つの Correios サービスのみが表示され、通貨レートは自動的には更新されません。
注文
Correios の配送業者で注文が行われると、モジュールは配送料の計算方法を保存します。その後、バックオフィスの注文ページに Correios ブロックが表示され、Correios service（リアルタイム料金の場合の例: PAC — contract (03298)）と Price source（Live price (Correios API)、Fixed price、Free shipping のいずれか）が表示されます。
ライセンスキー
このモジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Correios は、Modules > Module Manager > VibeFox Correios > Configure ページで設定の上にある最初のブロックです。キーを License key に入力し、Activate をクリックします。その後、ブロックにはマスクされたキー、ステータス（例: ライセンスの有効期限日と、お使いのドメイン）、および Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）のボタンが表示されます。その下には Product: presta-shipping-correios の行と、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 のアカウントで枠を解放してください。
有効なキーがない場合、チェックアウト時に Correios の配送業者は購入者に表示されず、料金も計算されません。PrestaShop のフロントエンドはバックオフィスにログインしていることを認識しないため、配送業者はお客様に対しても非表示になります。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。
ライセンスの有効期限が切れた場合も、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。ステータスは、バックオフィスで作業している間に自動的に再確認されます。キー入力後の最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
チェックアウトに Correios が表示されない: ライセンスが有効で、Enable Correios がオンになっていることを確認してください。Shipping > Carriers で、配送業者が購入者の国のゾーンと購入者のグループをカバーしているか確認してください（または Ignore shipping zones がオンで、その国が許可されていること）。重量制限と Minimum order amount を確認してください。リアルタイム料金がない場合は、その国または * の固定料金が必要です。また、商品ページで特定の配送業者に制限されている場合もあります。
Correios の料金ではなく固定料金が表示される: モジュールのページにある Log フィールドを確認してください。Correios のエラーはここに記録されます。アクセスコードの誤り、契約にないサービス、対応していない CEP、30 kg を超える荷物、サイズ制限を超える荷物などです。発送元 CEP が設定されているか、購入者の CEP が 8 桁か、デフォルト通貨が BRL でない場合は BRL のレートが設定されているかも確認してください。すべての計算を確認するには、Debug log をオンにしてください。
トークンのリクエストが失敗する: API のユーザー、アクセスコード、posting card、環境を確認してください。ホモロゲーション用のアクセスコードは Homologation がオンの場合にのみ有効で、本番用のコードはオフの場合にのみ有効です。
変更後に料金が古いようだ: モジュールのページで Save をクリックしてください。これにより、キャッシュされた料金と API トークンが消去されます。
Correios の配送業者が見つからないと表示される: Shipping > Carriers で配送業者が削除されています。Modules > Module Manager でモジュールをリセットすると、再度作成されます。
保存時に権限がないと表示される: 従業員プロファイルではモジュールを表示できても設定はできません。設定の保存とログの消去には、モジュールの設定権限が必要です。
アンインストール
Modules > Module Manager に移動し、VibeFox Correios の横のメニューを開いて Uninstall を選択します。ライセンスキー、ライセンスステータス、キャッシュされた料金とトークンは常に削除されます。Remove data on uninstall がオンの場合、配送業者は削除されます（注文は履歴を保持します）。また、設定、保存された注文サービス、ログも削除されます。オフの場合、配送業者は無効になるだけで、すべての設定は保持されます。モジュールを再インストールすると、配送業者は以前のステータスで復元されます。
Correios は各所有者の商標です。本モジュールは Correios と提携しておらず、Correios による推奨も受けていません。