VibeFox Jadlog for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 でテスト済み）または 4.0.2 以降（4.1.0.3 でテスト済み）。

PHP: 8.0 以降。

Jadlog との契約（リアルタイムの送料と受け取りポイントに必要）: リアルタイムの送料と受け取りポイントの一覧は、Jadlog Embarcador API から取得されます。アクセス権は、契約締結後に Jadlog のフランチャイズ先が発行します。Embarcador API のトークン、契約に登録された発送元の CNPJ（または CPF）、当座預金口座（conta corrente）、そして契約番号（お持ちの場合）が必要です。固定料金のみを使用する場合は、Jadlog との契約は不要です。

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

インストール

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

OpenCart 3

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

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

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

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

5. API トークンを貼り付け、CNPJ、当座預金口座、契約番号、発送元の CEP を入力し、Jadlog のサービスを選択します。ストアの既定通貨が BRL でない場合は、BRL の為替レートを入力します。必要に応じて、固定料金またはフォールバック料金を追加します（「設定」を参照）。

6. Enable Jadlog home delivery、Enable Jadlog Pickup、またはその両方をオンにして、Save をクリックします。

OpenCart 4

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

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

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

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

インストール直後は、オンにして保存するまで、両方のオプションが無効のままです。アンインストール後に拡張機能を再インストールした場合は、保持されていた Jadlog の設定が再び使用されます。

設定

すべての設定は拡張機能のページにあります。Extensions > Extensions > Shipping > VibeFox Jadlog > Edit です。設定は両方の Jadlog オプションに適用されます。セクションは左側に一覧表示されます。Save ボタンを 1 回押すと、ページを再読み込みせずにページ全体が保存されます。保存するたびに、キャッシュされた Jadlog の料金と受け取りポイントの一覧も消去されます。この拡張機能に対する変更権限を持つ管理者ユーザーだけが設定を保存できます。

ページの上部には、設定が不完全な場合の警告が表示されます。API トークンがない（固定料金のみが使われ、受け取りポイントは一覧表示できません）、API トークンも固定料金もない（この配送方法は表示されません）、CNPJ または当座預金口座がない、発送元の CEP がない、ストアの既定通貨が BRL でないのに BRL の為替レートがない、ストアに「kg」の重量区分や「cm」の長さ区分がない（この場合、重量と寸法は区分の単位名に従って換算されます。System > Localisation > Weight Classes と Length Classes を確認してください）。

保存時に、どちらかのオプションのタイトルが無効（空、64 文字を超える、または < > ; = # { } を含む）である場合、Sort order が整数でない場合、または税クラスやジオゾーンが存在しない場合は、保存がエラーで中止されます。その他の不正な値は、設定の上に注意書きを表示して保存されます。有効でない値、または 0 未満の数値は保存されません。最小重量が最大重量を超える場合は、両方の保存済みの重量が残ります。正の数でない BRL の為替レートは消去されます。8 桁未満の CEP、または 14 桁（CPF の場合は 11 桁）未満の CNPJ は、入力どおりに警告付きで保存されます。料金表で国が不明な行は削除され、無効な料金は空欄になります。

一般

Jadlog には 2 つの配送オプションがあります。Jadlog home delivery（このセクション）と Jadlog Pickup（独立したセクション）です。このページの設定は両方に適用されます。

Enable Jadlog home delivery: 下で選択したサービスにより、購入者の住所への Jadlog 配送を提供します。既定値: off。

Method title: チェックアウトで購入者に表示される宅配オプションの名前。既定値: Jadlog。必須、最大 64 文字。

Sort order: チェックアウトの配送方法の中で Jadlog が表示される順番。整数。

Tax class: 送料の税クラス、または No tax（既定値）。Jadlog の料金は確定した運送料金です。OpenCart に税を加算させたくない場合は、No tax を選択してください。両方のオプションに適用されます。

Jadlog のリアルタイム料金

リアルタイムの料金は、郵便番号（CEP）8 桁が完全に入力されたブラジル国内の住所に対してのみ請求されます。

API token: Jadlog から提供される Embarcador トークン。「Bearer」という語の有無にかかわらず貼り付けられます。固定料金のみを使う場合は、空欄のままにします。保存後、この欄は空のままで、Saved - leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。トークンが保存されていない場合、ページには No token saved. と表示されます。

Remove the saved API token: チェックを入れて Save をクリックすると、保存されたトークンが削除されます。

CNPJ: Jadlog の契約に登録された発送元の CNPJ（14 桁）または CPF（11 桁）。例: 00.000.000/0000-00。

Current account (conta corrente): Jadlog の当座預金口座番号。これがなく、CNPJ もない場合、Jadlog は見積もりを出せず、固定料金のみが使われます。

Contract number: フランチャイズ先から契約番号が発行されている場合は、Jadlog の契約番号。

Origin CEP: 荷物を発送する郵便番号。8 桁（00000-000）。リアルタイムの料金に必要です。OpenCart にはストアの郵便番号がないため、この欄がないと固定料金のみが使われます。

Jadlog service: 宅配用の契約サービス（modalidade）。.Package（3、既定値）、.Com（9）、Expresso（0）、Rodoviário（4）、Econômico（5）、Doc（6）、Corporate（7）、Internacional（10）、Cargo（12）、Emergencial（14）のいずれかです。Jadlog Pickup（40）は 2 つ目の選択肢です。

Insurance type: Jadlog の契約で合意された内容に従い、Normal (N)（既定値）または Own insurance policy (A - apolice) を選択します。

Volumetric weight: Jadlog は、実重量と容積重量のうち大きい方で課金します。

BRL exchange rate: Jadlog はブラジル・レアルで見積もります。ストアの既定通貨が BRL の場合、この欄は不要です。それ以外の場合は、1 BRL が既定通貨でいくらになるかを入力します（例: 0.16）。Jadlog の料金にこのレートが掛けられ、Jadlog に送信される申告注文金額は BRL に換算し直されます。レートがない場合、リアルタイムの料金は使われず、固定料金のみが適用されます。

Delivery time: チェックアウトで、送り先の宅配オプションのタイトルの横と、各受け取りポイントの横に、Jadlog が返す配送日数を表示します（例: 「Jadlog (3 business days)」）。既定でオンです。配送日数は常に注文と一緒に保存されます。

Jadlog Pickup

Jadlog Pickup（40）サービスを使う 2 つ目の配送オプションです。API トークンが必要です。ポイントがない場合、このオプションは非表示になります。

Enable Jadlog Pickup: チェックアウトで選んだ Jadlog Pickup の受け取りポイントへの配送を提供します。既定値: off。

Jadlog Pickup title: チェックアウトでのこのオプションの名前。既定値: Jadlog Pickup。必須、最大 64 文字。

Points to show: 提供する受け取りポイントの数（1〜10）。既定値: 5。

固定料金（API トークンがない場合、Jadlog が対応していない国の場合、Jadlog が料金を返さない場合に使用されます）

Price per country: ストアの既定通貨で、Country、Price、XS、S、M、L、XL の列を持つ表です。Add country をクリックすると行が追加され、× ボタンをクリックすると行が削除されます。サイズの列はカートの重量によって選ばれます。XS は 1 kg まで、S は 2 kg まで、M は 3 kg まで、L は 5 kg まで、XL は 5 kg 超です。サイズの列が空欄の場合は Price が使われます。料金が 0 の場合、その国は送料無料になります。他のすべての国には * Default (other countries) を使用します。

Fallback cost: Jadlog も表も料金を提供しない場合に使われます。その場合に配送方法を非表示にするには、空欄のままにします。

Fixed price applies: Per order（既定値）は料金を 1 回だけ請求します。Per item (price x quantity) は、カート内の商品数を掛けます。これは固定料金とフォールバック料金にのみ適用されます。Jadlog の料金は、カート全体をすでにカバーしています。

条件

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

Maximum weight (kg): このカート重量を超える場合は、配送方法を非表示にします。既定値: 150。0 は制限なしを意味します。

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

Free shipping from: 小計（クーポン適用後、税抜き）がこの金額に達すると、配送が無料になります。無料配送にしない場合は空欄のままにします。

提供条件

Geo zone: このジオゾーン内の住所にのみ Jadlog を提供します。All zones（既定値）は制限なしを意味します。Ignore shipping zones がオンのときは、ジオゾーンは確認されません。ジオゾーンは System > Localisation > Geo Zones で管理します。

Ignore shipping zones: オンにすると、Geo zone は確認されず、Jadlog は以下の国に対して提供されます。オフ（既定値）の場合は、Geo zone のみが適用されます。

Countries: このモードの配送先の国。すべての国を許可する場合は空欄のままにします。この欄は、Ignore shipping zones がオンの場合にのみ使用されます。

詳細設定

Debug log: Jadlog へのすべてのリクエストとレスポンスを storage/logs/vfd_jdlg_debug.log.php（OpenCart 4 では system/storage/logs/vfd_jdlg_debug.log.php）に記録します。このファイルは Web から読み取ることはできません。API エラーや、受け取りポイントなしの Jadlog Pickup の注文は、このオプションがオフでも常に記録されます。トークン、CNPJ、口座は決して記録されず、購入者の CEP は短縮されます。作業が終わったらログをオフにしてください。

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

Remove data on uninstall: オンにすると、拡張機能をアンインストールしたときに、すべての Jadlog の設定、ログ、注文にならなかったチェックアウトのポイント選択が削除されます。オフ（既定値）の場合、再インストールに備えて設定は保持されます。キャッシュされた料金は常に削除されます。注文の Jadlog データは削除されません。

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

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

Import: 以前にエクスポートした JSON を貼り付けて Import をクリックすると、設定を復元できます（別のストアに移行する場合など）。値は通常の保存と同じように検証されます。保存されている API トークンは保持されます。

チェックアウトでの動作

OpenCart が配送方法を表示するとき、拡張機能に各 Jadlog オプションの料金を問い合わせます。宅配と Jadlog Pickup は、1 つの Jadlog 配送方法の下に 2 つの選択肢として表示されます。Ignore shipping zones がオンの場合、その国が許可されているときにのみ Jadlog が提供されます（ジオゾーンは確認されません）。それ以外の場合、Geo zone が設定されていて住所がその外にあれば、Jadlog は提供されません。Requires Shipping が Yes に設定された商品のみが計算に含まれます。他の商品は重量に加算されず、注文金額にも含まれません。注文金額は、配送が必要な商品の料金の合計で、クーポン割引後、税抜きの金額です。拡張機能はカート重量と最低注文金額を確認します。小計が Free shipping from に達すると、配送は無料になり、Jadlog への料金の問い合わせは行われません。

ブラジル国内の住所で郵便番号（CEP）8 桁が完全に入力されている場合、拡張機能は Jadlog に、発送元と配送先の CEP、重量、貴店の CNPJ、当座預金口座、契約、サービス、保険の種類、申告注文金額を送信します。商品の重量は OpenCart の重量区分から kg に、寸法は長さ区分から cm に換算されます。重量のないカートは 0.1 kg として見積もられます。返された料金は、貴店の既定通貨に換算され、その通貨の小数桁に丸められ、選択した Tax class の税額を加えて購入者の通貨で表示されます。リアルタイムの料金がない場合（トークンがない、住所がブラジル国外、CEP が不完全、BRL の為替レートがない、Jadlog のエラー）は、拡張機能が Price per country の表を使い、次に Fallback cost を使います。いずれも料金を提供しない場合は、そのカートではこのオプションが非表示になります。

各料金は 1 時間キャッシュされるため、同じカートでも新たなリクエストは発生しません。失敗したリクエストは 10 分間キャッシュされます。Jadlog が応答しない、サーバーエラーを返す、またはトークンを拒否する場合、10 分間は API が再度呼び出されません。API のタイムアウトは 10 秒です。購入者に API エラーが表示されることはありません。理由はログに記録されます。

OpenCart 4 では、購入者はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options ウィンドウで Jadlog のオプションを選択します。料金は OpenCart 3 の場合と同じです。

拡張機能が行うのは、料金の計算と受け取りポイントの一覧表示のみです。Jadlog の配送の作成、ラベルの印刷、集荷の依頼、配送のキャンセル、荷物の追跡は行いません。受け取りポイントの地図は表示せず、Jadlog に国際的な見積もりを依頼することもありません。その他の国には固定料金を使用してください。

受け取りポイント

Jadlog Pickup の選択肢は、ブラジル国内の住所に対してのみ提供され、Enable Jadlog Pickup がオンで、API トークンが保存されている場合に限られます。購入者が郵便番号（CEP）8 桁を完全に入力すると、拡張機能は、その近くにある有効な受け取りポイントを Jadlog に問い合わせ、オプションの下に最大 Points to show 件のポイントを、それぞれの料金とともに表示します（例: 「ポイント名 — 料金（3 business days）— 住所」）。一覧がまだキャッシュされていない場合は、購入者が Jadlog Pickup を選択したときにバックグラウンドで読み込まれるため、配送方法の手順が Jadlog の応答を待つことはありません。

各ポイントの料金は Jadlog に問い合わせて取得します。Jadlog がポイントの料金を提供しない場合は固定料金が使われ、どの料金もないポイントは除外されます。ポイントの一覧は 12 時間キャッシュされます。オプションの料金は、選択したポイントの料金です。ポイントが選ばれる前は、料金が設定されている最も近いポイントの料金が表示されます。購入者がポイントを選ぶと、Jadlog Pickup の横に表示される料金が更新されます。

ポイントの選択は必須です。購入者が配送方法の手順でポイントを選ばずに Continue をクリックすると、Please select a Jadlog Pickup point. と表示されます。拡張機能は、そのポイントが配送先の CEP に対する Jadlog のリストに含まれているかをサーバー上で確認します。含まれていない場合、購入者には The selected Jadlog Pickup point is not in the Jadlog list for this CEP. Please choose the point again. と表示されます。CEP が不完全な場合、近くにポイントがない場合、または Jadlog が利用できない場合は、オプションの下にメッセージが表示されます。

API トークンがない場合、Jadlog が利用できない場合、近くに有効なポイントがない場合は、Jadlog Pickup のオプションは非表示になります。ポイントのない注文は発送できないためです。

OpenCart 4 では、受け取りポイントの一覧が Shipping method options ウィンドウの Jadlog Pickup のオプションの下に表示されます。一覧はバックグラウンドで読み込まれ、最初にキャッシュから、次に Jadlog から他のポイントの料金とともに取得されます。購入者がポイントを選ぶと、ウィンドウ内の Jadlog Pickup の横の料金が更新されます。ウィンドウの Continue ボタンは、有効なポイントがないと先に進まず、同じメッセージが表示されます。

注文

Jadlog のオプションで注文が行われると、拡張機能は Jadlog のサービスを保存し、Jadlog が返した場合は営業日単位の配送日数も保存します。Jadlog Pickup の注文の場合は、受け取りポイントの名前、住所、ID も保存します。OpenCart 4 では、チェックアウトごとに 1 つの注文を保持し、購入者が再度確定するたびにその注文を更新します。このとき注文の Jadlog データも更新されます。購入者がその注文の配送方法を別の方法に切り替えた場合、その注文の Jadlog データは削除されます。

ポイントは、注文の配送方法にオプションのタイトルの後ろに追加されます。例えば、Jadlog Pickup: に続けてポイントの名前と住所が表示されます。このテキストは、管理画面と購入者のアカウントの注文ページ、注文確認メール、請求書に表示されます。

管理画面の注文ページ（Sales > Orders）には、Jadlog のパネルが表示されます。このパネルには、Jadlog service、Delivery time が表示され、Jadlog Pickup の場合は Pickup point、Pickup point address、Pickup point ID も表示されます。OpenCart 4 では、このパネルは History の上に表示されます。

Jadlog のシステムでの配送の手配はご自身で行ってください。注文には、必要なサービスと受け取りポイント ID が表示されます。

ライセンスキー

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

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

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

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

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

トラブルシューティング

チェックアウトに Jadlog が表示されない: ライセンスが有効であること、Enable Jadlog home delivery（または Enable Jadlog Pickup）がオンであることを確認してください。Geo zone を確認するか、Ignore shipping zones をオンにして Countries を確認してください。拡張機能のページ上部の警告、重量の制限、Minimum order amount、商品の Requires Shipping が Yes に設定されていることを確認してください。購入者がまだ郵便番号（CEP）8 桁を入力していない場合は、固定料金しか使えないため、Price per country の行か Fallback cost を追加してください。

固定料金しか表示されない: Debug log をオンにして、チェックアウトを再読み込みし、拡張機能のページの Log 欄を確認してください。理由が表示されます。CNPJ や当座預金口座がない、発送元の CEP がない、配送先の CEP が不完全、BRL の為替レートがない、または Jadlog のエラーメッセージなどです。

ログに HTTP 401 または 403 がある: Jadlog が API トークンを拒否しました。Jadlog のフランチャイズ先に確認してください。このエラーの後、API は 10 分間一時停止します。設定を保存すると一時停止は解除されるので、すぐに再試行できます。

受け取りポイントが表示されない: Jadlog Pickup のオプションには、Enable Jadlog Pickup、API トークン、ブラジル国内の郵便番号（CEP）8 桁の完全な入力が必要です。CEP の近くに Jadlog の有効なポイントがない場合、オプションは非表示になります。理由はログで確認してください。

料金が自分の通貨ではなくレアルで表示される: BRL exchange rate（1 BRL がストアの既定通貨でいくらになるか）を入力してください。

料金が低すぎる、または高すぎるように見える: 商品の重量と寸法を入力してください。重量のないカートは 0.1 kg として見積もられ、容積重量には寸法が必要です。

Jadlog の料金に税が加算される: Tax class を No tax に設定してください。

変更後も料金が古く見える: 拡張機能のページで Save をクリックしてください。キャッシュされた Jadlog の料金と受け取りポイントの一覧が消去されます。

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

アンインストール

Extensions > Extensions に進み、種類で Shipping を選択し、VibeFox Jadlog の横にある Uninstall（赤色の − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは常に削除されます。OpenCart は、拡張機能の状態、Sort order、Tax class、Geo zone を常にリセットします。キャッシュされた料金と受け取りポイントの一覧は常に削除されます。Remove data on uninstall がオンの場合は、Jadlog の設定とログも削除されます。オフの場合、その他の設定は保持され、拡張機能を再インストールしたときに再び使用されます。注文に保存された Jadlog のサービス、配送日数、受け取りポイントは常に保持され、既存の注文は配送方法と料金をそのまま保持します。

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

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