VibeFox Servientrega for PrestaShop — ヘルプ
要件
PrestaShop：8.0 ～ 9.x
PHP：8.0 以降。モジュールは古い PHP バージョンではインストールできません。
Servientrega 口座（リアルタイム料金の場合のみ）：リアルタイム料金には Servientrega Cotizador Corporativo（法人向け見積もり API）を使用します。これにアクセスできる Servientrega の法人（クレジット）口座が必要です。ユーザー名、パスワード、請求コード（código de facturación、通常は SER で始まります）の 3 つの情報が必要です。これらは SISCLINET の認証情報で、Servientrega の営業担当者から発行されます。固定料金のみを使用する場合は、Servientrega 口座は不要です。
サーバーのアクセス（リアルタイム料金の場合のみ）：サーバーから web.servientrega.com へ、HTTP でポート 8058（見積もり API）およびポート 8081（パスワード暗号化 Web サービス）に接続できる必要があります。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
1. 管理画面で Modules > Module Manager を開き、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックします。後でモジュール一覧から VibeFox Servientrega を探し、Configure をクリックすることもできます。
3. Configure ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。
4. リアルタイム料金を使う場合は、ユーザー名、パスワード、請求コードを入力し、Servientrega の製品を選択し、発送元の DANE コードを入力します。店舗の通貨が COP でない場合は、通貨換算レートも入力します。店舗にまだコロンビアの県がない場合は、Add Colombian departments をクリックします（「設定」を参照）。
5. 必要に応じて、国と重量ごとの固定料金と代替料金を追加し、Save をクリックします。
インストール時に、モジュールは配送時間のテキスト Servientrega courier delivery を付けて Servientrega 配送業者を作成します。配送業者はすべてのゾーンとすべての顧客グループに割り当てられます。ゾーン、顧客グループ、配送時間、ロゴ、サイズの上限は Shipping > Carriers で変更できます。料金はそこでは設定しないでください。料金は常にモジュールから取得されます。
設定
すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Servientrega > Configure。設定はすべてのゾーンに適用されます。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。保存するたびに、キャッシュされた Servientrega の見積もりとログイントークンが消去されます。
保存された設定でリアルタイム料金が機能しない場合、フォームの上に警告が表示され理由が示されます。ユーザー名、パスワード、請求コードの欠落、換算レートの欠落、発送元 DANE コードの欠落が該当します。店舗の重量または寸法の単位（International > Localization の Local units）がモジュールで認識されない場合も警告が表示されます。その場合、重量は kg、寸法は cm として扱われます。保存時、数値以外の値、負の数、換算レート 0、最低重量が最高重量を超える設定、テーブル内の誤った料金、64 文字を超えるメソッドタイトルは、エラーとして拒否され、何も保存されません。
一般
Enable Servientrega：すべてのゾーンで配送業者を一度にオンまたはオフにします。Shipping > Carriers の配送業者のステータスと同じスイッチです。
Method title：カートとチェックアウトでお客様に表示される配送業者名です。デフォルト：Servientrega。必須、最大 64 文字。
Servientrega API（コロンビアのリアルタイム料金）（任意。認証情報がない場合は固定料金のみが使われます）
User (login)：Servientrega / SISCLINET のユーザー名です。この欄を空にすると、保存されたパスワードも削除されます。
Password：Servientrega / SISCLINET のパスワードです。入力したとおりに保存されます。ログイン前に Servientrega の Web サービスで暗号化されます。保存後、この欄は空のままになり、Saved — leave empty to keep it と表示されます。変更する場合のみ新しい値を入力してください。
Billing code：Servientrega 口座の código de facturación です。SISCLINET に表示されます。通常は SER で始まります。
リアルタイム料金には 3 つの欄がすべて必要です。リアルタイム料金は、コロンビア国内の配送先に対してのみ取得されます。他の国では固定料金が使われます。
Servientrega product：Servientrega 契約の中から、見積もりを取得するサービスです。
請求重量は、実重量と容積重量のうち大きい方です。
Currency conversion rate：Servientrega の料金は COP 建てです。店舗のデフォルト通貨が COP でない場合は、店舗の通貨で 1 COP の値を入力します（例：0.00023）。申告する荷物の価値も同じ方法で COP に換算されます。店舗の通貨が COP の場合は空欄のままにします。店舗が別の通貨を使い、この欄が空の場合、リアルタイム料金は使われず、固定料金が適用されます。モジュールは為替レートを取得しません。小数点とカンマのどちらも小数点区切りとして使えます。
Colombian departments：県は、同じ名前の自治体を区別するのに役立ちます。PrestaShop には標準でコロンビアの県がありません。県がない場合、コロンビア国内で一意の市区町村名しか認識されません。Add Colombian departments をクリックすると、33 の県をコロンビアの州（ISO コード ANT、DC など）として追加し、コロンビアで Contains states を有効にし、コロンビアの住所フォームに県フィールドを追加します。既に存在する県は二重には追加されません。すべての設定が完了すると、この欄にコロンビアの住所が持つ県の数が表示されます。
Ship from（リアルタイム料金に使用）
Origin city (DANE code)：発送元の自治体の 8 桁の DANE コードです。例：11001000 Bogotá、05001000 Medellín、76001000 Cali、08001000 Barranquilla。5 桁の自治体コードも使用できます。この欄が空で、Shop Parameters > Contact > Stores の店舗住所がコロンビアにある場合は、店舗住所の自治体が使われます。
固定料金（リアルタイム料金がない場合に使われます：認証情報がない、配送先がコロンビア外、自治体が不明、換算レートがない、API エラー、またはルートに対応していない場合）
Price per country：店舗のデフォルト通貨（税抜き）による国と料金の表です。Add country をクリックすると行を追加し、ゴミ箱アイコンをクリックすると行を削除します。Price はどの重量にも適用されます。重量列 XS ≤1 kg、S 1–2 kg、M 2–3 kg、L 3–5 kg、XL >5 kg は、0 より大きい場合にその重量で Price の代わりに使われます。* Default 行は、独自の行がないすべての国に適用されます。料金が 1 つも入力されていない行は保存されません。
Fallback cost：リアルタイム料金がなく、表のどの行も一致しない場合に使われます。空欄にすると、その場合は配送業者が非表示になります。
Fixed price applies：固定料金の課金方法です。
Servientrega のリアルタイム料金は、常に 1 出荷ごとに計算されます。
条件
Minimum weight：カートの重量がこの値より軽い場合、配送業者を非表示にします（kg）。0 は制限なしを意味します。
Maximum weight：カートの重量がこの値より重い場合、配送業者を非表示にします（kg）。デフォルト：50。0 は制限なしを意味します。
Minimum order amount：カートの小計（割引後、税抜き）がこの金額に達した場合にのみ、配送業者を表示します。空欄にすると常に表示されます。
Free shipping from：カートの小計（割引後、税抜き）がこの金額に達すると配送料は無料になり、Servientrega にリクエストは送信されません。配送業者が提供されるすべての配送先に適用されます。料金表に行がない国も含みます。空欄にすると、送料無料は一切提供されません。
Tax：配送業者の税ルール、または No tax。Servientrega の見積もり（ValorTotal）にはすでに配送業者の料金が含まれています。その上に税を加えたくない場合は No tax を選択してください。
配送ゾーンなしでの提供
通常、配送業者は Shipping > Carriers で割り当てられたゾーンで提供されます。
Ignore shipping zones：配送業者がそのゾーンに割り当てられていなくても、下記の国に対して Servientrega を提供します。その場合、配送業者は後から作成するゾーンも含め、すべてのゾーンに割り当てられます。このオプションをオフにすると、配送業者は以前のゾーンに戻ります。
Countries：このモードの配送先の国です。空欄にすると、店舗で有効なすべての国を使用します。この欄は Ignore shipping zones がオンの場合にのみ使われます。
詳細設定
Debug log：料金の計算と API エラーを、モジュールフォルダ内の logs/vfd_svtg_debug.log.php に書き込みます。このファイルは Web からは開けません。認証情報、トークン、お客様の住所は記録されません。ログがオフのときは、API エラーを含め何も書き込まれません。作業が終わったらログをオフにしてください。
Log：デバッグログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログを消去できます。
Remove data on uninstall：オンの場合、モジュールをアンインストールすると、Servientrega のすべての設定、配送業者、キャッシュされた見積もり、ログが削除されます。過去の注文は配送業者を保持します。オフの場合は、再インストールに備えてすべてが保持されます。
チェックアウトでの動作
配送ステップで、PrestaShop はモジュールに Servientrega の料金を問い合わせます。対象となるのは実物の商品のみです。仮想商品は重量を加算せず、注文金額にも含まれません。モジュールはまず条件を確認します。配送先の国（Ignore shipping zones の設定を含む）、カートの重量、最低注文金額です。送料無料が適用される場合、料金は 0 になり、Servientrega にリクエストは送信されません。次に料金を探します。Servientrega のリアルタイム料金、料金表、代替料金の順です。料金がない場合は、そのカートでは配送業者が非表示になります。
認証情報が設定されたコロンビアの配送先では、モジュールはお客様の自治体の DANE コードを探します。郵便番号欄または市区町村欄に入力された DANE コードを使うか、県と市区町村を内蔵の約 1,130 自治体の一覧と照合します。アクセント記号と「D.C.」は無視されます。1 つの県にしか存在しない市区町村名は、県が入力されていなくても見つかります。
その後、モジュールは注文ごとに 1 個の荷物として Servientrega に送信します。合計重量は店舗の単位から kg に換算されます。箱の縦と横は最も大きい商品の長さと幅、高さはすべての商品の合計容積から求められ、cm に換算されます。寸法のない商品は 10 × 10 × 10 cm として扱われます。申告価格は、カートの小計を COP に換算した額で、最低 6,000 COP です。Servientrega は COP で合計を返します。モジュールはそれを店舗のデフォルト通貨に換算し、お客様はカートの通貨で料金を確認します。
ログイントークンは期限切れまで保持され、最長 4 日です。拒否されたトークンは一度だけ自動的に更新されます。各見積もりは、ルートと荷物ごとに 1 時間キャッシュされるため、同じカートで新たなリクエストが発生することはありません。失敗したリクエスト（暗号化、ログイン、見積もり）は 10 分間キャッシュされます。これにより、チェックアウトの再読み込みのたびに Servientrega の応答を待つことがなくなります。リクエストごとのタイムアウトは 10 秒です。
お客様が API エラーを目にすることはありません。デバッグログがオンの場合、理由はログに書き込まれます。
注文のある配送業者を Shipping > Carriers で編集すると、PrestaShop はそれを配送業者の新しいバージョンとして保存します。モジュールは新しいバージョンに自動的に追従します。
モジュールは料金の計算のみを行います。送り状（guías）、ラベル、ステッカーの作成、集荷の依頼、出荷の追跡やキャンセルは行わず、お客様が Servientrega の営業所（Centro de Soluciones）を選ぶこともできません。送り状は SISCLINET または Servientrega のポータルで作成してください。代金引換（logística de recaudo）の見積もりは行われません。リアルタイム見積もりは、コロンビア国内の国内発送にのみ適用されます。その他の国では固定料金が使われます。
ライセンスキー
モジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Servientrega は、Modules > Module Manager > VibeFox Servientrega > Configure の設定の上にある最初のブロックです。License key にキーを入力し、Activate をクリックします。その後、ブロックにはマスクされたキー、ステータス（例: ライセンスの有効期限日と使用中のドメイン）、そして次のボタンが表示されます。Check now はステータスを再確認します。Change key は別のキーを入力します。Remove key はこのショップからキーを削除します。その下には Product: presta-shipping-servientrega の行と、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 のアカウントで解放してください。
有効なキーがない場合、チェックアウトで Servientrega の配送業者はお客様に表示されず、料金の照会や計算も行われません。PrestaShop のフロントエンドは、バックオフィスにログインしていることを認識しないため、配送業者はあなたにも表示されません。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。
ライセンスの有効期限が切れた場合も、モジュールは動作し続けますが、アップデートとサポートには更新が必要です。バックオフィスで作業している間、ステータスは自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは必要ありません。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスのステータスは常に削除されます。
トラブルシューティング
チェックアウトに Servientrega が表示されない：ライセンスが有効で、Enable Servientrega がオンになっていることを確認します。Shipping > Carriers で、配送業者がお客様の国のゾーンとお客様の顧客グループをカバーしていることを確認するか、Ignore shipping zones をオンにして Countries を確認します。重量の上限と Minimum order amount も確認してください。リアルタイム料金がない場合は、国または * Default 行に料金があること、または Fallback cost が設定されていることを確認します。商品ページで、特定の配送業者に限定されている場合もあります。
リアルタイム料金が表示されない：Debug log をオンにして、チェックアウトを再読み込みし、モジュールのページにある Log 欄を確認します。よくある原因：換算レートがない（店舗の通貨が COP ではない）、発送元の DANE コードがない、お客様の県または市区町村が未入力、または既知の自治体ではない、認証情報が誤っている、またはルートに対応していない。固定料金を設定している場合は、これらのケースでも固定料金が適用されます。
ログインに失敗する：ユーザー名、パスワード、請求コードを Servientrega の営業担当者と照らし合わせて確認してください。ログインに失敗すると、モジュールは次の試行まで 10 分待機します。すぐに再試行するには、設定を保存してください。
お客様の市区町村が認識されない：Add Colombian departments をクリックして、お客様が県を選択できるようにしてください。表記の揺れが多い場合は、お客様が 8 桁の DANE コードを郵便番号として入力することもできます。
変更後も見積もりが古いまま：モジュールのページで Save をクリックしてください。キャッシュされた Servientrega の見積もりとトークンが消去されます。
ページに Servientrega 配送業者が見つからないと表示される：Shipping > Carriers で配送業者が削除されています。Modules > Module Manager でモジュールをリセットすると、再作成されます。
開発者向け：フック actionVfdSvtgDaneCode と actionVfdSvtgQuoteRequest を使うと、配送先の DANE コードと見積もりリクエストを変更できます。
アンインストール
Modules > Module Manager を開き、VibeFox Servientrega の横のメニューを開いて Uninstall を選択します。ライセンスキーとライセンスのステータスは常に削除されます。キャッシュされた見積もり、トークン、暗号化されたパスワードは常に削除されます。Remove data on uninstall がオンの場合、配送業者が削除され（注文は履歴を保持します）、設定とログも削除されます。オフの場合、配送業者は無効化されるだけで、すべての設定は保持されます。モジュールを再インストールするか、Reset を使うと、配送業者は以前の状態に戻ります。
Servientrega は、それぞれの所有者の商標です。本モジュールは Servientrega と提携しておらず、Servientrega による推奨もされていません。