VibeFox Correos CityPaq for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: 8.0 以降。古い PHP バージョンではモジュールをインストールできません。

スペインへの配送: CityPaq ロッカーはスペイン国内にのみ存在するため、配送業者はスペイン国内の配送先住所に対してのみ提供されます。

Correos API 認証情報（リアルタイムのロッカー一覧にのみ必要）: Correos CityPaq の一覧は、Correos の "terminals" API から有効なロッカーを読み込みます。Correos デベロッパーポータルで "terminals" API を開き、貴社のアプリケーションに対して Request access を使用してください。Correos は法人顧客からのリクエストを承認し、client ID と client secret を送付します。これらはポータルの My applications にも表示されます。購入者が自分でロッカーを入力する場合、または貴店の一覧から選択する場合は、API 認証情報は不要です。

VibeFox ライセンスキー: vibefox.net で購入できます。1 つのキーは 1 つのドメインで利用できます。

インストール

1. 管理画面で Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択してください。

2. アップロードが完了したら Configure をクリックします。後からモジュール一覧で VibeFox Correos CityPaq を見つけて Configure をクリックすることもできます。

3. Configure ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。

4. 料金表を入力し、購入者がロッカーを選択する方法を選んで（設定の項を参照）、Save をクリックします。

インストール時、モジュールは配送時間のテキストが Delivery to a Correos CityPaq parcel locker の Correos CityPaq 配送業者を作成します。配送業者はすべての顧客グループとスペインのゾーンに割り当てられます。ゾーン、顧客グループ、配送時間、ロゴ、サイズ制限は Shipping > Carriers で変更できます。ここでは料金を設定しないでください。料金は常にモジュールから取得されます。

設定

すべての設定はモジュールページにあります：Modules > Module Manager > VibeFox Correos CityPaq > Configure。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。料金と金額は小数点のカンマまたはピリオドを受け付けます。

設定の上部にある警告は、次のような状況を知らせます：配送業者が見つからない場合、料金表にスペインの行も既定の行もない場合、選択したロッカー選択方法が機能しない場合（一覧にロッカーがない、API 認証情報がない）、Correos API の最後のエラー内容、およびストアの重量単位がモジュールで認識されない場合（その場合、商品の重量は kg として読み込まれます。International > Localization で kg、g、lb、oz のいずれかを設定してください）。名前が空、無効、または 64 文字を超える場合、重量または金額が 0 以上の有効な数値ではない場合、または Min weight (kg) が Max weight (kg) より大きい場合は、ページにエラーが表示され、何も保存されません。料金表の無効な料金や、My lockers の無効または重複した行は警告として報告され、残りの内容は保存されます。

一般

CityPaq ロッカーはスペインにのみ存在するため、配送業者が他の国に表示されることはありません。

Enable/Disable: Correos CityPaq の配送を有効または無効にします。これは Shipping > Carriers の配送業者ステータスと同じスイッチです。

Name: チェックアウトで購入者に表示される配送方法の名前です。配送業者の名前にもなります。既定値：Correos CityPaq。必須、最大 64 文字。

Tax: 配送業者の税ルールです。PrestaShop は料金表の料金にこの税を加算します。No tax は料金が確定額であることを意味します。

料金（セクションの見出しには、ストアの既定通貨が表示されます）

Correos は CityPaq の料金 API を公開していないため、料金はこの表から取得されます。Correos との契約料金を、税抜きでストアの既定通貨に入力してください。

Price table: Spain (ES) の行、および/または既定の行 * Default を用意します。各行には基本の Price と、包装サイズ XS（1 kg まで）、S（2 kg まで）、M（3 kg まで）、L（5 kg まで）、XL（5 kg 超）の任意料金があります。サイズの料金が 0 または空欄の場合は、基本料金が使われます。+ Add row をクリックすると行を追加でき、ゴミ箱アイコンで行を削除できます。該当する行がない場合、配送業者は非表示になります。同じ国が 2 回出現する場合は、最初の行のみが使用されます。

Calculation type: 包装サイズの決め方です。

Per order (size by the total cart weight): カート全体に対して 1 つの料金を、合計重量に応じて選択します。これが既定値です。

Per item (size by each item weight, multiplied by quantity): 各商品は、自身のサイズの料金に数量を掛けたものが適用され、その料金が合計されます。

商品の重量は、ストアの重量単位（例：kg、g、lb、oz）から kg に換算されます。

条件

Min weight (kg): カートがこれより軽い場合は配送業者を非表示にします。0 は制限なしを意味します。

Max weight (kg): カートがこれより重い場合は配送業者を非表示にします。既定値：30（CityPaq は最大 30 kg の荷物を受け付けるため）。0 は制限なしを意味します。

Minimum order amount: カートの小計（配送が必要な商品、割引後、税抜き）がこの金額に達した場合にのみ配送業者を表示します。常に表示する場合は空欄のままにします。

送料無料

Free shipping: 下記の金額以上で、CityPaq の配送を無料にします。

Free shipping from: この配送業者が 0 になるカート小計（割引後、税抜き）です。Free shipping が有効な場合にのみ使用されます。

CityPaq ロッカーの選択

このセクションには、Correos CityPaq の公式ファインダーへのリンクがあります。

Locker selection: 注文前に購入者がロッカーを選択する方法です。既定値：購入者がロッカーを入力します。

Customer chooses from the Correos CityPaq list (Correos API, credentials below): 購入者は、配送先住所の郵便番号にある有効な CityPaq ロッカーを確認でき、別の 5 桁の郵便番号を検索できます。郵便番号にロッカーがない場合は、同じエリアのロッカー、次に同じ県のロッカーが、近い郵便番号から順に一覧表示されます（最大 50 件）。各ロッカーには、名前、住所、郵便番号、市区町村、営業時間が表示されます。一覧を読み込めない場合、または何も見つからない場合は、購入者がロッカーを入力します。

Customer enters the locker (code or address from the Correos finder): ロッカーコード（例：S0000213D）または住所の入力欄です。必須で、3 文字から 120 文字まで入力でき、Correos CityPaq ファインダーへのリンクがあります。

Customer chooses from my list of lockers (below): My lockers のロッカーを選択する必須のドロップダウンです。購入者の郵便番号に近いロッカーが先に表示されます。

Do not ask for a locker: チェックアウトでロッカーについて質問しません。

API 認証情報なしで Correos の一覧を選択した場合、または My lockers が空の状態で貴店の一覧を選択した場合、購入者にはロッカーを入力するよう求められます。

My lockers: Locker selection が貴店の一覧に設定されている場合に使用されます。1 行に 1 つのロッカーを記入します：CODE | Name | Address | Postal code | City。コードと名前は必須です。同じコードが 2 回記載されている場合は、最初の行のみが使用されます。

Correos CityPaq 一覧（API）（Correos CityPaq の一覧を選択した場合にのみ使用されます）

このセクションには、Correos デベロッパーポータルの "terminals" API ページへのリンクがあります。読み込まれるのはロッカーの一覧のみです。料金は常に料金表から取得されます。

API client ID: Correos デベロッパーポータルでの貴社アプリケーションの client_id です。

API client secret: Correos デベロッパーポータルでの貴社アプリケーションの client_secret です。

保存後、両方の欄は空欄のまま Saved - leave empty to keep it と表示されます。変更したい場合のみ新しい値を入力してください。Remove the saved client ID and client secret にチェックを入れて Save をクリックすると、保存された値が削除されます。何も保存されていない場合、このセクションには No credentials saved と表示されます。認証情報またはロッカー選択を変更すると、キャッシュされたロッカー一覧は消去されます。

配送ゾーンを使わない場合の提供条件

Ignore shipping zones: 住所のゾーンが配送業者に関連付けられていなくても、スペイン国内のすべての住所に CityPaq を提供します。有効にすると、配送業者は後から作成されたものを含め、すべての有効なゾーンに関連付けられます。再び無効にすると、配送業者は以前のゾーンに戻ります。無効（推奨）の場合は、Shipping > Carriers で設定されたゾーンが使用されます。

詳細設定

Debug log: モジュールフォルダー内の logs/vfd_cpq_debug.log.php にデバッグ行を書き込みます。このファイルは Web から開くことはできません。この設定が無効でも、Correos API のエラーは常に書き込まれます。認証情報と個人データがログに記録されることはありません。

Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログを空にできます。

Remove data on uninstall: 有効にすると、モジュールをアンインストールした際に、設定、配送業者、キャッシュされた一覧、ログが削除されます。注文に保存されたロッカーは保持されます。無効にすると、再インストールに備えてすべてが保持されます。

チェックアウトでの動作

配送ステップで、PrestaShop はモジュールに CityPaq の料金を問い合わせます。実物の商品のみが対象となります。仮想商品は重量を加算せず、注文金額にも含まれません。モジュールは、配送先住所がスペイン国内であること、カートの重量と最低注文金額を確認し、スペインの料金行（または * の行）と包装サイズを見つけて、料金を返します。送料無料が適用される場合、料金は 0 になります。料金はストアの既定通貨で計算され、その後、購入者のカートの通貨で表示されます。税は配送業者の税ルールによって加算されます。

購入者が CityPaq を選択すると、配送業者の下に CityPaq locker のボックスが表示されます。選択内容は、購入者が選択した時点でカートに保存されます。受け付けられないロッカーは、メッセージとともに拒否され、以前の選択が維持されます。Correos の一覧を使用する場合、ロッカーコードは、検索した郵便番号について Correos が提示したものである場合にのみ受け付けられ、その名前と住所は Correos から取得されます。購入者は 1 つのカートにつき、最大 30 個の異なる郵便番号を検索できます。それを超えると、購入者には Too many searches. Please enter the CityPaq locker you found on the Correos map. と表示されます。

配送ステップの Continue ボタンは、有効なロッカーがない場合は先に進みません。これはサーバー側でも確認されます。購入者には、たとえば Please choose the CityPaq locker where you want to collect your parcel. と表示されます。注文が確定すると、カートのロッカーが注文に保存されます。

Correos の一覧は、購入者が CityPaq を選択したときにのみ要求され、配送ステップを訪れるすべての人には要求されません。一覧は郵便番号ごとに 12 時間キャッシュされます。失敗したリクエストは 10 分間キャッシュされるため、チェックアウトは更新のたびに Correos の応答を待つことがありません。API のタイムアウトは 12 秒です。購入者が技術的なエラーを目にすることはなく、短いメッセージと手入力欄だけが表示されます。ロッカーのボックスは Classic テーマと Hummingbird テーマで動作します。

モジュールは Correos からリアルタイムの料金を取得せず、地図を表示せず、荷物の事前登録、ラベルの印刷、集荷依頼、追跡は行いません。注文に保存されたロッカーを使用して、Correos アカウントで配送を作成してください。

受け取り場所

選択されたロッカーは注文に保存されます。購入者は、注文確認ページと、顧客アカウントの注文詳細ページで CityPaq locker: として確認できます。注文確認メールと Mail alerts モジュールの新規注文メールでは、配送業者の行にロッカーが追加されます（例：Correos CityPaq - CityPaq locker: ...）。

管理画面の注文ページでは、CityPaq locker ブロックにロッカーが表示され、一覧から選択された場合は Locker code: も表示されます。変更するには、Change CityPaq locker の欄を使用して Save をクリックします。貴店の一覧を使用している場合はドロップダウンから別のロッカーを選択し、Correos の一覧を使用している場合はロッカーコード（Correos で照会されます）または住所を入力し、それ以外の場合は新しいコードまたは住所を入力します。現在のロッカーをそのまま維持するには、欄を空欄のままにします。変更ごとに、注文に非公開のメッセージが追加されます：CityPaq ロッカーを変更しました: ...。ロッカーを変更するには注文を編集する権限が必要です。Modules のページへのアクセスは不要です。

ライセンスキー

本モジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Correos CityPaq は、Modules > Module Manager > VibeFox Correos CityPaq > Configure ページで設定の上にある最初のブロックです。キーを License key に入力し、Activate をクリックします。その後、ブロックにはマスクされたキー、ステータス（例: ライセンスの有効期限日と、お使いのドメイン）、および Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）のボタンが表示されます。その下には Product: presta-shipping-correos-citypaq の行と、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 のアカウントで枠を解放してください。

有効なキーがない場合、チェックアウト時に Correos CityPaq の配送業者は購入者に表示されず、料金も計算されません。PrestaShop のフロントエンドはバックオフィスにログインしていることを認識しないため、配送業者はお客様に対しても非表示になります。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。

ライセンスの有効期限が切れた場合も、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。ステータスは、バックオフィスで作業している間に自動的に再確認されます。キー入力後の最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。

トラブルシューティング

Correos CityPaq がチェックアウトに表示されない: ライセンスが有効であること、Enable/Disable が有効であること、配送先住所がスペイン国内であることを確認してください。Shipping > Carriers で、配送業者がスペインのゾーンと購入者の顧客グループをカバーしていることを確認してください（または Ignore shipping zones を有効にしてください）。料金表にスペインの行または * の行があること、カートが重量制限と Minimum order amount の範囲内であることを確認してください。また、商品ページで商品が特定の配送業者に制限されている場合もあります。

Correos の一覧が選択されているのに、購入者がロッカーを手入力しなければならない: API client ID と API client secret が保存されていることを確認し、設定の上部にある警告を確認してください。警告には、Correos API の最後のエラーが表示されます。HTTP 401/403 は、Correos が認証情報を拒否したことを意味します。認証情報と、アプリケーションが "terminals" API にアクセスできるかを確認してください。エラーの後、次の試行は 10 分後に行われます。

郵便番号にロッカーがない: Correos は、その郵便番号、そのエリア、またはその県に有効なロッカーを見つけられませんでした。購入者は別の郵便番号を検索するか、Correos CityPaq ファインダーで見つけたロッカーを入力できます。

マイロッカーのドロップダウンが表示されない: My lockers が空であるか、その行が無効です。各行には少なくとも CODE | Name が必要です。

購入者がロッカーコードを見つける場所: ロッカー欄の下にリンクされている Correos CityPaq ファインダーです。

ページに配送業者が見つからないと表示される、または配送業者を更新できないと表示される: 配送業者が Shipping > Carriers で削除されています。Modules > Module Manager でモジュールをリセットすると、再度作成されます。リセットしても、設定と配送業者のステータスは保持されます。

開発者向けの注意: カートと注文のロッカーは、テーブル vfd_cpq_locker（データベースの接頭辞付き）に保存されます。モジュールは Correos の本番用 "terminals" API を使用します。

アンインストール

Modules > Module Manager に移動し、VibeFox Correos CityPaq の横にあるメニューを開いて、Uninstall を選択してください。ライセンスキー、ライセンスステータス、キャッシュされた Correos のロッカー一覧と最後の API エラーは、常に削除されます。Remove data on uninstall が有効な場合、配送業者は削除され（注文は履歴を保持します）、設定、ログ、注文のないカートのロッカーも削除されます。無効な場合、配送業者は無効化されるだけで、すべての設定は保持されます。モジュールを再インストールすると、配送業者は以前のステータスに戻ります。注文に保存されたロッカーは、削除されることはありません。

Correos および CityPaq は、それぞれの所有者の商標です。本モジュールは Correos と提携しておらず、Correos による承認も受けていません。