VibeFox Servientrega for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 で動作確認済み）または 4.0.2 以降（4.1.0.3 で動作確認済み）。

PHP: 8.0 以降。

Servientrega アカウント（リアルタイム料金の場合のみ）: リアルタイム料金は、Servientrega の Cotizador Corporativo（法人向け見積もり API）を使用します。これにアクセスできる Servientrega の法人（クレジット）アカウントが必要です。3 つの情報が必要です：ユーザー、パスワード、請求コード（código de facturación、通常は SER で始まります）。これらは SISCLINET の認証情報で、Servientrega の営業担当者が発行します。固定料金のみを使用する場合、Servientrega のアカウントは必要ありません。

サーバーへのアクセス（リアルタイム料金の場合のみ）: サーバーから、HTTP で web.servientrega.com のポート 8058（見積もり API）およびポート 8081（パスワード暗号化 Web サービス）に接続できる必要があります。

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

インストール

ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。お使いのコンピューターで解凍してください。内容は README.txt、OpenCart 3 用パッケージ vfd_servientrega-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ vfd_servientrega.ocmod.zip です。お使いの OpenCart のバージョンに対応するパッケージだけをインストールしてください。ライセンスキーは両方のバージョンで同じです。

OpenCart 3

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

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

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

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

5. リアルタイム料金を使う場合は、ユーザー、パスワード、請求コードを入力し、Servientrega の商品を選択して、発送元の DANE コードを入力します。ストアの通貨が COP でない場合は、通貨の換算レートも入力します。

6. 必要に応じて、国と重量ごとの固定料金と代替料金を追加し、Enable Servientrega をオンにして、Save をクリックします。

OpenCart 4

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

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

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

4. OpenCart 3 の手順 4 から 6 と同様に、ライセンスキーと設定を入力します。設定ページとそのフィールドは両方のバージョンで同じです。

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

設定

すべての設定は拡張機能のページにあります：Extensions > Extensions > Shipping > VibeFox Servientrega > Edit。セクションは左側に一覧表示されます。これらはすべてのジオゾーンに適用されます。ページ下部の Save ボタンを押すと、ページを再読み込みせずにページ全体が保存されます。保存するたびに、キャッシュされた Servientrega の見積もりとログイントークンが消去されます。この拡張機能の変更権限を持つ管理者ユーザーだけが設定を保存できます。

保存された設定でリアルタイム料金が機能しない場合、設定の上部に警告が表示され、理由が示されます。例えば、ユーザー、パスワード、請求コードの欠落、換算レートの欠落、または発送元の DANE コードの欠落です。ストアに kg の重量クラスまたは cm の長さクラスがなく、そのデフォルト単位が拡張機能で認識されない場合にも警告が表示されます。その場合、重量は kg、寸法は cm として扱われます。保存時、数値ではない値、負の数、換算レートが 0、最小重量が最大重量を超える場合、料金表の誤った価格、空の方法名、64 文字を超える名称、または < > ; = # { } を含む名称、整数ではない並び順は、エラーとして拒否され、何も保存されません。

一般

Enable Servientrega: チェックアウトで Servientrega を表示または非表示にします。既定値：オフ。

Method title: カートとチェックアウトでお客様に表示される配送方法の名称。既定値：Servientrega。必須、最大 64 文字。

Sort order: チェックアウトの配送方法の中で Servientrega が表示される位置。整数で指定します。

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 との契約のうち、見積もりの対象となるサービスです。

Mercancía Premier（小包；請求重量 3 kg 以上）: 既定値です。容積重量は 1 m³ あたり 222 kg です。

Mercancía Industrial（重量物）: 容積重量は 1 m³ あたり 400 kg です。

Documento unitario（書類）: 書類用です。

請求重量は、実重量と容積重量のうち大きい方です。

Currency conversion rate: Servientrega は COP で見積もります。ストアの既定通貨が COP でない場合は、1 COP のストア通貨での値を入力してください（例：0.00023）。荷物の申告価格も同じ方法で COP に換算されます。ストアの通貨が COP の場合、このフィールドには換算が不要と表示されます。空欄のままにしてください。ストアが別の通貨を使用しており、このフィールドが空欄の場合、リアルタイム料金は使用されず、固定料金が適用されます。拡張機能は為替レートを取得しません。小数点としては、ピリオドとカンマのどちらも使用できます。

Ship from（リアルタイム料金に使用）

Origin city (DANE code): 発送元の自治体の 8 桁の DANE コード（例：11001000 Bogotá、05001000 Medellín、76001000 Cali、08001000 Barranquilla）。5 桁の自治体コードも受け付けます。OpenCart のストア住所は自由記述のため、発送元はそこから取得されることはありません。このフィールドがなければ、リアルタイム料金は利用できません。

Fixed prices（リアルタイム料金がない場合に使用：認証情報がない、仕向先がコロンビア以外、自治体が不明、換算レートがない、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 より大きい場合にその重量の料金を置き換えます。* Default の行は、独自の行がないすべての国に適用されます。新しい行は * Default として始まります。料金が 1 つもない行は保存されません。

Fallback cost: リアルタイム料金がなく、料金表のどの行も一致しない場合に使用されます。その場合に方法を非表示にするには、空欄のままにしてください。

Fixed price applies: 固定料金の請求方法です。

Per order（カート全体の重量区分）: カートの重量に一致する重量列の料金を、1 回だけ請求します。これが既定値です。

Per item（各商品の重量区分 × 数量）: 各商品の重量列の料金に数量を掛けて合計します。代替料金は、商品の点数分だけ掛けられます。

Servientrega のリアルタイム料金は、常に出荷ごとに計算されます。

Conditions

Minimum weight (kg): このカート重量より軽い場合は、この方法を非表示にします。0 は制限なし（既定値）を意味します。

Maximum weight (kg): このカート重量より重い場合は、この方法を非表示にします。既定値：50。0 は制限なしを意味します。

Minimum order amount: 配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額に達した場合にのみ、この方法を表示します。空欄の場合は常に表示します。

Free shipping from: この小計がこの金額に達すると配送は無料になり、Servientrega にはリクエストが送信されません。この方法が提示されるすべての仕向先に適用され、料金表に行がない国も含まれます。送料無料を提示しない場合は、空欄のままにしてください。

Tax class: 送料の税クラス、または No tax（既定値）。Servientrega の見積もり（ValorTotal）にはすでに運送業者の料金が含まれています。その上に税を加算したくない場合は、No tax を選択してください。

Geo zone: この地理的ゾーン内の住所に対してのみ Servientrega を提示します。All zones（既定値）は制限なしを意味します。ジオゾーンは System > Localisation > Geo Zones で管理されます。Ignore shipping zones がオンの場合は確認されません。

Availability without geo zone

通常、この方法は Conditions で選択したジオゾーン内、またはどこでも提示されます。

Ignore shipping zones: ジオゾーンに関係なく、下記の国に対して Servientrega を提示します。

Countries: このモードの仕向先の国です。空欄の場合は、ストアで有効なすべての国を使用します。このフィールドは、Ignore shipping zones がオンの場合にのみ使用されます。

Advanced

Debug log: 料金の計算と API のエラーを storage/logs/vfd_svtg_debug.log.php に書き込みます。このファイルは Web から読み取ることはできません。認証情報、トークン、お客様の住所は記録されません。ログがオフの場合、API のエラーを含め、何も書き込まれません。ファイルが 5 MB に達すると、vfd_svtg_debug.old.log.php に移動され、新しいログが開始されます。作業が終わったら、ログをオフにしてください。

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

Remove data on uninstall: オンの場合、拡張機能をアンインストールすると、すべての Servientrega の設定とログが削除されます。オフ（既定値）の場合、再インストールに備えて保持されます。キャッシュされた見積もりは常に削除されます。

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

Export: Download JSON をクリックすると、設定が JSON ファイルとして保存されます。パスワードはエクスポートされません。

Import: 以前にエクスポートした JSON を貼り付け、Import をクリックして設定を復元します（例：別のストアで）。値は通常の保存と同じチェックを受けます。保存されたパスワードは、ユーザーが設定されている限り保持されます。

チェックアウトでの動作

OpenCart が配送方法を表示するとき、拡張機能に Servientrega の料金を問い合わせます。Geo zone が設定されていて、住所がその外にある場合、Servientrega は提示されません（Ignore shipping zones がオンの場合を除く）。Requires Shipping が Yes に設定された商品のみが対象です。それ以外の商品は重量に加算されず、注文金額にも含まれません。注文金額は、クーポン割引後、税抜きのこれらの商品の価格です。ギフト券とポイントは考慮されません。拡張機能はまず条件を確認します：配送先の国（Ignore shipping zones を含む）、カートの重量、最低注文金額。送料無料が適用される場合、料金は 0 で、Servientrega にはリクエストが送信されません。次に料金を探します：Servientrega のリアルタイム料金、次に料金表、最後に代替料金です。料金がない場合、そのカートでは方法は非表示になります。

認証情報が設定されたコロンビアの仕向先の場合、拡張機能はお客様の自治体の DANE コードを探します。郵便番号または市の欄に入力された DANE コードを使用するか、県と市を、約 1,130 の自治体を組み込んだ表と照合します。県は住所の Region / State です。OpenCart にはコロンビアの 33 の県がすでに含まれています。アクセント記号と「D.C.」は無視されます。1 つの県にしか存在しない市は、県が指定されていなくても見つかります。

次に、拡張機能は注文ごとに 1 つの荷物を Servientrega に送信します。商品の重量クラスから kg に換算した合計重量と、最も大きな商品の長さと幅、およびすべての商品の合計体積から cm に換算した箱です。寸法のない商品は 10 × 10 × 10 cm として扱われます。申告価格は、COP に換算された注文金額で、最低 6,000 COP です。Servientrega は COP で合計を返します。拡張機能はそれをストアの既定通貨に換算し、その小数桁数に丸めます。お客様は、選択した Tax class の税を含めて、自分の通貨で料金を確認します。

ログイン用トークンは期限切れまで保持され、最長 4 日です。拒否されたトークンは 1 回自動的に更新されます。各見積もりは、ルートと荷物ごとに 1 時間キャッシュされるため、同じカートでも新しいリクエストは発生しません。失敗したリクエスト（暗号化、ログイン、見積もり）は 10 分間キャッシュされるため、チェックアウトは更新のたびに Servientrega を待つことはありません。タイムアウトは、リクエストごとに 10 秒です。

お客様が API のエラーを目にすることはありません。理由は、デバッグログが有効な場合にログに書き込まれます。

この拡張機能は料金を計算するだけです。ガイド（guías）、ラベル、ステッカーの作成、集荷の依頼、出荷の追跡やキャンセル、お客様による Servientrega の営業所（Centro de Soluciones）の選択は行いません。ガイドは SISCLINET または Servientrega のポータルで作成してください。代金引換（logística de recaudo）は見積もりに含まれません。リアルタイムの見積もりは、コロンビア国内の国内発送のみが対象です。注文に何かを追加することはありません。注文には、他のすべての OpenCart の配送方法と同様に、方法名と送料が表示されます。

OpenCart 4 では、お客様はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options ウィンドウで Servientrega を選択します。このウィンドウには方法名と料金が表示されます。この方法は OpenCart 3 と同じように動作します。

ライセンスキー

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

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

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

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

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

トラブルシューティング

チェックアウトに Servientrega が表示されない：ライセンスが有効であること、Enable Servientrega がオンであることを確認してください。Geo zone を確認するか、Ignore shipping zones をオンにして Countries を確認してください。重量の上限と Minimum order amount を確認してください。リアルタイム料金がない場合は、その国または * Default に料金があるか、Fallback cost が設定されているかを確認してください。商品の Requires Shipping が Yes に設定されていることを確認してください。

リアルタイム料金が表示されない：Debug log をオンにし、チェックアウトを再読み込みして、拡張機能のページにある Log フィールドを確認してください。よくある原因：換算レートがない（ストアの通貨が COP でない）、発送元の DANE コードがない、お客様の県や市がまだ入力されていないか、既知の自治体ではない、認証情報が誤っている、ルートに対応していない、またはサーバーがポート 8058 と 8081 で web.servientrega.com に接続できない。固定料金を設定しておけば、これらの場合も対応できます。

ログインに失敗する：ユーザー、パスワード、請求コードを Servientrega の営業担当者に確認してください。ログインに失敗すると、拡張機能は次の試行まで 10 分待機します。設定を保存すると、すぐに再試行されます。

お客様の市が認識されない：お客様は Region / State フィールドで県を選択する必要があります。まれな綴りの場合は、お客様が 8 桁の DANE コードを郵便番号として入力できます。

変更後に見積もりが古いように見える：拡張機能のページで Save をクリックしてください。これにより、キャッシュされた Servientrega の見積もりとトークンが消去されます。

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

開発者向け：OpenCart のイベント vfd_servientrega/dane_code と vfd_servientrega/quote_request により、別の拡張機能が仕向先の DANE コードと見積もりリクエストを変更できます。

アンインストール

Extensions > Extensions に移動し、種類 Shipping を選択して、VibeFox Servientrega の横にある Uninstall（赤色の − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは常に削除されます。OpenCart は、Enable Servientrega、Sort order、Tax class、Geo zone を常にリセットします。キャッシュされた見積もり、トークン、暗号化されたパスワードは常に削除されます。Remove data on uninstall がオンの場合、その他の設定とログも削除されます。オフの場合は保持され、拡張機能を再インストールしたときに再び使用されます。既存の注文は、配送方法と送料を保持します。

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

Servientrega は、その所有者の商標です。この拡張機能は Servientrega と提携しておらず、Servientrega による承認も受けていません。