VibeFox Correos CityPaq for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 で検証済み）または 4.0.2 以降（4.1.0.3 で検証済み）。

PHP: 8.0 以降。

スペインへの配送: 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 つのドメインで使用できます。

インストール

ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。ご利用のコンピューターで解凍してください。README.txt、OpenCart 3 用パッケージの vfd_correos_citypaq-oc3-(version).ocmod.zip、OpenCart 4 用パッケージの vfd_correos_citypaq.ocmod.zip が含まれています。ご利用の OpenCart バージョン用のパッケージのみをインストールしてください。ライセンスキーは両方のバージョンで共通です。

OpenCart 3

1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_correos_citypaq-oc3-(version).ocmod.zip を選択します。本拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。Installer を使わず、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。

2. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選択します。VibeFox Correos CityPaq を見つけて Install（緑色の + ボタン）をクリックします。

3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。

4. Edit ページ上部のライセンスブロックにある License key の欄に VibeFox ライセンスキーを貼り付け、Activate をクリックします（「ライセンスキー」を参照）。

5. 料金表を入力し、購入者がロッカーを選択する方法を選び（設定を参照）、Enable/Disable をオンにして Save をクリックします。

OpenCart 4

1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_correos_citypaq.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変更したパッケージは動作しません。

2. パッケージは同じページのインストール済み拡張機能の一覧に表示されます。その横の Install（緑色の + ボタン）をクリックします。

3. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選択します。VibeFox Correos CityPaq を見つけて、Install（緑色の + ボタン）をクリックしてから、Edit（鉛筆のボタン）をクリックします。

4. ライセンスキーと設定は、OpenCart 3 の手順 4 および 5 と同様に入力します。設定ページとその項目は両方のバージョンで同じです。

インストール後は、Enable/Disable をオンにして保存するまで、この配送方法は無効のままです。アンインストール後に拡張機能を再インストールした場合、保持されていた設定が再び使用されます。

設定

すべての設定は拡張機能のページにあります：Extensions > Extensions > Shipping > VibeFox Correos CityPaq > Edit。セクションは左側に一覧表示されます。ページ下部の 1 つの Save ボタンで、ページを再読み込みせずにページ全体を保存します。料金と金額は、小数点としてカンマまたはピリオドを使用できます。この拡張機能の変更権限を持つ管理者ユーザーのみが設定を保存できます。

ページの上部には、料金表にスペインの行も既定の行もない場合、選択したロッカーの選び方が機能しない場合（一覧にロッカーがない、API の認証情報がない）、最後の Correos API エラーの内容、ストアに単位が kg の重量クラスがない場合（その場合、商品の重量は単位名（kg、g、lb、oz）で換算され、不明な単位は kg として扱われます）に警告が表示されます。System > Localisation > Weight Classes を確認してください。名前が空、無効、または 64 文字を超える場合、重量や金額が 0 以上の有効な数値でない場合、Min weight (kg) が Max weight (kg) より大きい場合、または Sort order が整数でない場合は、ページにエラーが表示され、何も保存されません。料金表の無効な料金、重複した行、My lockers の無効または重複した行は警告として報告され、それ以外は保存されます。

一般

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

Enable/Disable: Correos CityPaq の配送をオンまたはオフにします。既定値: オフ。

Name: チェックアウトで購入者に表示される配送方法の名前。既定値: Correos CityPaq。必須、64 文字以内、< > ; = # { } は使用不可。

Tax class: OpenCart は、料金表の料金にこのクラスの税金を加算します。No tax は、料金が最終価格であることを意味します。

Sort order: 配送方法の一覧での表示順。整数。

料金（セクションのタイトルにはストアの既定の通貨が表示されます）

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 に換算されます。

Conditions

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 が空の状態でお客様の一覧を選択した場合は、購入者にロッカーの手動入力が求められます。

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. と表示されます。認証情報またはロッカーの選択方法を変更すると、キャッシュされたロッカー一覧と最後の API エラーが消去されます。

利用可能性

Geo zone: この地域の住所にのみ配送方法を提供します。All zones（既定）は、スペイン国内のすべての住所を意味します。ジオゾーンは System > Localisation > Geo Zones で管理します。

Ignore geo zone: 上で指定したジオゾーンに含まれていなくても、スペイン国内のすべての住所に CityPaq を提供します。

詳細設定

Debug log: デバッグ行を storage/logs/vfd_cpq_debug.log.php（OpenCart 4 では system/storage/logs/vfd_cpq_debug.log.php）に書き込みます。このファイルはウェブから読み取ることはできません。このオプションがオフでも、Correos API のエラーは常に書き込まれます。認証情報や個人データが記録されることはありません。

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

Remove data on uninstall: オンにすると、拡張機能のアンインストール時に設定、キャッシュされた一覧、ログが削除されます。注文に保存されたロッカーは残ります。オフ（既定）の場合は、再インストール用にすべてが保持されます。

インポート / エクスポート

Export: Download JSON をクリックすると、設定が JSON ファイルとして保存されます。API の client ID と secret は含まれません。

Import: この拡張機能からエクスポートした設定の JSON を貼り付けて、Import をクリックします。値は通常の保存と同じように検証されます。保存済みの認証情報は保持されます。

チェックアウトでの動作

OpenCart が配送方法を表示する際、拡張機能に CityPaq の料金を問い合わせます。Geo zone が設定されていて（かつ Ignore geo zone がオフ）、住所がそのゾーンの外にある場合、CityPaq は提供されません。Requires Shipping が Yes に設定されている商品のみが計算に含まれます。その他の商品は重量に加算されず、注文金額にも含まれません。拡張機能は次に、配送先住所がスペイン国内であること、カートの重量、最低注文金額を確認し、スペインの料金行（または * の行）と荷物のサイズを探して、料金を返します。送料無料が適用される場合、料金は 0 になります。料金はストアの既定の通貨で計算され、その通貨の小数点以下の桁数で丸められ、選択した Tax class の税金を含めて購入者の通貨で表示されます。料金の計算のために Correos にリクエストは送信されません。

CityPaq locker のボックスは、配送方法の手順で CityPaq の方法の下に表示されます。選択内容は、購入者が選択するとすぐに保存されます。受け付けられないロッカーはメッセージとともに拒否され、以前の選択はそのまま残ります。Correos の一覧を使う場合、ロッカーのコードは、Correos が検索された郵便番号について提示したものだけが受け付けられ、その名前と住所は Correos から取得されます。購入者は、1 回のチェックアウトセッションで最大 30 件の異なる郵便番号を検索できます。その後、購入者には Too many searches. Please enter the CityPaq locker you found on the Correos map. と表示されます。

配送方法の手順の Continue ボタンは、有効なロッカーがないと CityPaq に進めません。これはサーバー側で確認されます。購入者には、例えば Please choose the CityPaq locker where you want to collect your parcel. と表示されます。注文が確定すると、ロッカーが注文に保存されます。

OpenCart 4 では、購入者はチェックアウトページの配送方法のブロックで Choose をクリックし、ウィンドウ Shipping method options で CityPaq を選択します。CityPaq locker のボックスは、そのウィンドウの CityPaq の選択肢の下に表示され、上記と同じように動作します。ウィンドウの Continue ボタンは、有効なロッカーがないと CityPaq に進めません。OpenCart 4 では、チェックアウトごとに 1 つの注文が保持され、購入者が確定し直すたびに更新されます。その際、注文のロッカーも一緒に更新されます。

Correos の一覧は、CityPaq が選択された配送方法である場合にのみ要求され、手順が描画されている間は要求されません。一覧は郵便番号ごとに 12 時間キャッシュされます。失敗したリクエストは 10 分間キャッシュされるため、チェックアウトの更新のたびに Correos の応答を待つことはありません。購入者には技術的なエラーは表示されず、The Correos CityPaq list cannot be loaded right now. というメッセージと手動入力欄だけが表示されます。

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

受け取りポイント

選択されたロッカーは、注文の配送方法に追加されます。例えば Correos CityPaq - CityPaq locker: ... のように表示されます。そのため購入者はアカウントの注文履歴と注文メールでそれを確認でき、請求書にも印刷され、Sales > Orders にも表示されます。OpenCart の注文完了ページには配送方法は表示されません。

管理画面の注文ページでは、履歴の上にある CityPaq locker パネルに、ロッカーと、一覧から選択された場合の Locker code: が表示されます。変更するには、Change CityPaq locker の入力欄を使用して Save をクリックします。お客様の一覧を使う場合はドロップダウンから別のロッカーを選びます。Correos の一覧を使う場合はロッカーのコード（Correos で照会されます）または住所を入力します。それ以外の場合は、新しいコードまたは住所を入力します。現在のロッカーを維持する場合は、入力欄を空のままにするか、-- Keep the current locker -- のままにします。変更のたびに、注文の配送方法のテキストも更新され、購入者に通知することなく、履歴に CityPaq locker changed to: ... のエントリが追加されます。ロッカーの変更には、注文の変更権限（sale/order）が必要です。拡張機能の設定へのアクセスは必要ありません。このパネルは、拡張機能が無効になっていても CityPaq の注文に表示されます。

ライセンスキー

本拡張機能は、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Correos CityPaq は、Extensions > Extensions > Shipping > VibeFox Correos CityPaq > Edit ページの先頭で、設定の上にあります。License key にキーを入力して Activate をクリックします。その後、ブロックにはキーがマスク表示され、ステータス（例: ライセンスの有効期限の日付とドメイン）と、ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key のボタンが表示されます。その下には、行 Product: opencart-shipping-correos-citypaq と、vibefox.net のアカウントを開くリンク Manage licenses and domains in your account があります。キーを変更できるのは、この拡張機能の変更権限を持つ管理者ユーザーのみです。ブロックのテキストは管理画面の言語に従います（英語とロシア語が含まれています）。

キーが受け付けられない場合、ブロックにはその理由が表示されます。例えば Key not found、This key belongs to another product、Domain limit reached、日付付きの License expired on などです。ストアのアドレスを変更した後、またはアカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、拡張機能は最後に確認されたステータスで動作を続けます。

1 つのキーは 1 つのドメインで使用できます。ドメインとは、OpenCart の設定にあるストアのアドレスです。ストアからキーを削除しても、ドメインの枠は解放されません。枠は vibefox.net のアカウントで解放してください。

有効なキーがない場合、チェックアウトで Correos CityPaq は購入者に表示されず、料金も計算されません。管理画面に同じブラウザーでログインしている管理者ユーザーには、ストアで配送方法が (unlicensed — visible to admins only) の印付きで表示されるため、キーを購入する前に設定やテストができます。OpenCart 4 では、このプレビューは利用できません。ストアは管理画面のログインを認識しないため、有効なキーがない場合はすべてのユーザーに対して配送方法が非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると 7 日間非表示になります。既存の注文には影響しません。

ライセンスの有効期限が切れた後も拡張機能は動作し続けますが、アップデートとサポートには更新が必要です。ステータスは、管理画面の Dashboard または Edit ページを開いたときに自動的に再確認されます。キーの入力後最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスのステータスは常に削除されます。

トラブルシューティング

チェックアウトに Correos CityPaq が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、配送先住所がスペイン国内であることを確認してください。Geo zone を確認してください（または Ignore geo zone をオンにしてください）。料金表にスペインの行または * の行があること、カートが重量の制限と Minimum order amount の範囲内であること、商品の Requires Shipping が Yes に設定されていることを確認してください。

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

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

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

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

ページに "Warning: You do not have permission to modify VibeFox Correos CityPaq!" と表示される: 管理者ユーザーのグループには、設定の閲覧権限しかない可能性があります。System > Users > User Groups で、そのグループに extension/shipping/vfd_correos_citypaq（OpenCart 3）または extension/vfd_correos_citypaq/shipping/vfd_correos_citypaq（OpenCart 4）の変更権限を付与してください。

開発者向け: チェックアウトセッションと注文のロッカーは、テーブル vfd_cpq_locker（データベースの接頭辞付き）に保存されます。Correos API のアドレスは、設定 vfd_cpq_api_url（テスト用）で置き換えられます。設定ページにこの項目の入力欄はありません。

アンインストール

Extensions > Extensions に移動し、種類 Shipping を選んで、VibeFox Correos CityPaq の横にある Uninstall（赤い − ボタン）をクリックします。OpenCart は常に Enable/Disable、Sort order、Tax class、Geo zone をリセットします。キャッシュされた Correos のロッカー一覧と最後の API エラーは常に削除されます。Remove data on uninstall がオンの場合は、設定、ログ、注文のないチェックアウトセッションのロッカーも削除されます。オフの場合は、他の設定が保持され、拡張機能を再インストールしたときに再び使用されます。注文に保存されたロッカーは決して削除されず、既存の注文は配送方法と送料をそのまま維持します。

OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧で VibeFox Correos CityPaq の横にある Uninstall（オレンジ色の − ボタン）をクリックしてから、アップロードしたパッケージを削除するために Delete（赤いゴミ箱のボタン）をクリックします。

Correos と CityPaq は、それぞれの所有者の商標です。本拡張機能は Correos と提携しておらず、Correos による承認や支持も受けていません。