VibeFox Andreani for OpenCart — ヘルプ

動作要件

OpenCart: 3.0.x（3.0.5.0 で検証済み）または 4.0.2 以降（4.1.0.3 で検証済み）、標準テーマ使用時。

PHP: 8.0 以降。

Andreani アカウント（リアルタイム料金のみ必要）: リアルタイム料金は Andreani の見積り API を使用します。Andreani はビジネス顧客に API 認証情報、顧客コード、契約番号を発行します。通常は月におよそ 300 件の出荷から利用できます。developers.andreani.com を参照するか、ventapyme@andreani.com に問い合わせてください。API のユーザー名とパスワード、顧客コード（código de cliente）、契約番号が必要です。Andreani は、サービスごと（自宅配送、支店受け取り）に別々の契約を発行します。API アクセスがない場合は固定料金を使用してください。支店セレクターは認証情報がなくても動作します。

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

インストール

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

OpenCart 3

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

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

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

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

5. 名前、料金のソース、国ごとの料金（例：AR=5000）を設定します。リアルタイム料金を使う場合は、API 認証情報、顧客コード、契約番号も設定します（設定を参照）。Save をクリックします。

OpenCart 4

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

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

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

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

インストール直後は、Enable/Disable と Enable second option がオフのままで、いずれかのオプションをオンにして Save をクリックするまで、チェックアウトに Andreani は表示されません。アンインストール後に再インストールした場合は、保持されていた Andreani の設定が再び使用されますが、両方のオプションはオフになっています。オンにして Save をクリックしてください。

設定

すべての設定は拡張機能のページにあります：Extensions > Extensions > Shipping > VibeFox Andreani > Edit。セクションは左側に表示されます。Save ボタンを 1 回押すと、ページを再読み込みせずにページ全体が保存されます。保存後には Settings saved. Cached token, branches and rates were cleared. と表示されます。この拡張機能を変更する権限を持つ管理者ユーザーのみが設定を保存できます。

ページの上部には、不足している設定に関する警告が表示されます。API 認証情報（ユーザー名とパスワード）がないか、契約番号がないのに API 料金が選ばれている場合、ストアの通貨が ARS なのに ARS exchange rate が設定されていない場合、または Country prices にアルゼンチンの料金がない場合です。ストアの重量単位または長さ単位を拡張機能が認識できない場合にも警告が表示されます（その場合、重量は kg、寸法は cm として扱われます）。

保存時には、空の名前、64 文字を超える名前、または文字 < > ; = # { } のいずれかを含む名前、Max weight (kg) より大きい Min weight (kg)、整数ではない Sort order は拒否され、何も保存されません。数値ではない値、負の数、または 0 以下の ARS exchange rate は保存されず、警告がそのフィールドを示します。

一般

Andreani には、チェックアウトで 2 つのオプションがあります。ここと Andreani API、Delivery and rates で設定するメインオプションと、Second option です。どちらも配送方法の手順で Andreani の見出しの下に表示されます。

Enable/Disable: Andreani のメインオプションのオンとオフを切り替えます。既定値：オフ。2 つ目のオプションには専用のスイッチがあります。

Name: チェックアウトで購入者に表示されるメインオプションの名前。既定値：Andreani。必須。

Tax status: None (the API rate is taken with IVA)（既定値）、またはご自身の税クラスのいずれか。税クラスを選ぶと、OpenCart は送料に税金を加算するため、API 料金は IVA を含まずに取得されます。None の場合、API 料金は IVA を含めて取得されます。両方のオプションで使用されます。

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

Andreani API（リアルタイム料金に必要）

Environment: Sandbox / QA (apisqa.andreani.com)（既定値）または Production (apis.andreani.com)。認証情報が属する環境を使用してください。

API username: Andreani API のユーザー名。

API password: Andreani API のパスワード。保存後、このフィールドは空欄になり、Saved - leave empty to keep it. Clearing the API username removes it too. と表示されます。変更する場合にのみ新しい値を入力してください。

Client code: Andreani が提供する顧客コード（código de cliente）。例：CL0000000。

Contract number: 料金計算に使うサービスの契約。例：自宅配送。2 つ目のオプションは、支店受け取りなど別の契約を使用できます。

Origin branch code: 料金の見積りに使う、任意の発送元支店（sucursalOrigen）。空欄にすると、契約で設定された支店が使われます。

配送と料金

Delivery modality: メインオプションの配送方式。前半は Andreani が荷物を引き取る場所（ご自身の住所、またはご自身が荷物を持ち込む支店）を示します。後半は購入者が荷物を受け取る場所を示します。

Rate source: 料金の計算方法。

Country prices: 配送先の国ごとの固定料金を、ストアの既定通貨で、税抜きで指定します。1 行に 1 か国で、CC=PRICE の形式で入力します。例：AR=5000。固定モードと API のフォールバックに使われます。行がない国には固定料金がありません。別の形式の行は無視され、保存時に警告が一覧で表示されます。

ARS exchange rate: Andreani はアルゼンチン・ペソで見積りを出します。ストアの既定通貨が ARS でない場合にのみ必要です。1 ARS がストアの通貨でいくらになるかを入力します。例：0.001。これがないと、API の料金は使われません。

Default product weight (kg): API に料金を問い合わせる際や重量制限を確認する際に、重量のない商品に使われます。空欄の場合は 0.5 kg です。

Calculation type: Per order（既定値）は料金を 1 回だけ請求します。Per item (price x number of items) は、Country prices の固定料金にカート内の商品数を掛けます。Andreani のリアルタイム料金はカート全体に対するものなので、掛け算はされません。

利用可能条件

Min weight (kg): オプションが表示されるためのカートの最小重量。0 は制限なし（既定値）を意味します。

Max weight (kg): カートの最大重量。超えるとオプションは非表示になります。既定値：100。空欄は 100 kg、0 は制限なしを意味します。

Minimum subtotal: カートの小計（配送が必要な商品、クーポン適用後、税抜き、ストアの既定通貨）がこの金額以上の場合にのみオプションを表示します。常に表示する場合は空欄にしてください。

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

Ignore shipping zones: ジオゾーンに関係なく、下記の国に対して Andreani を提供します。既定値：オフ。

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

送料無料

Free shipping: 送料無料のしきい値をオンにします。既定値：オフ。

Free shipping from: カートの小計（ストアの既定通貨）がこの金額以上になると送料が無料になります。Free shipping がオンである必要があります。

2 つ目のオプション

独自の名前、配送方式、契約を持つ 2 つ目の Andreani オプションです。たとえばメインオプションでは「a domicilio」、ここでは「retiro en sucursal」とすると、両方を提供できます。それ以外の設定はすべて共有されます。

Enable second option: チェックアウトで 2 つ目のオプションを提供します。既定値：オフ。

Second option name: チェックアウトでのこのオプションの名前。既定値：Andreani - branch pickup。必須。

Delivery modality: Use global setting、または 4 つの配送方式のいずれか。既定値：Door to branch (Puerta a Sucursal)。

Contract number: Andreani は、サービスごと（自宅配送、支店受け取り）に別々の契約を発行します。空欄の場合は、全体の契約が使われます。

支店セレクター（Door to branch と Branch to branch で表示）

Province select width: 都道府県リストの CSS の幅。例：100% または 300px。既定値：100%。

Branch select width: 支店リストの CSS の幅。例：100% または 400px。既定値：100%。

詳細

Debug log: API のリクエストと料金計算を storage/logs/vfd_andr_debug.log.php に記録します。このファイルは Web から読み取ることはできません。エラーは常に記録されます。認証情報とトークンがログに記録されることはありません。ファイルが 5 MB に達すると、vfd_andr_debug.old.log.php に移動され、新しいログが開始されます。

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

Remove data on uninstall: オンの場合、拡張機能をアンインストールすると、すべての Andreani の設定とログが削除されます。オフの場合（既定値）は、再インストール用に保持されます。注文に保存された支店データは、常に保持されます。

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

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

Import: 以前にエクスポートした JSON を貼り付け、Import をクリックすると、設定が復元されます（例：別のストアでの利用）。値は通常の保存時と同様にチェックされます。保存済みの API パスワードは保持されます。

チェックアウトでの動作

OpenCart が配送方法を表示するとき、拡張機能に、有効な Andreani オプションごとの料金を問い合わせます。Geo zone が設定されていて、Ignore shipping zones がオフの場合、ジオゾーンの外の住所には Andreani は提供されません。Requires Shipping が Yes に設定された商品のみが計算に含まれます。それ以外の商品は重量を加算せず、小計にも含まれません。続いて拡張機能は、国（Ignore shipping zones がオンの場合）、カートの重量（商品の重量は kg に換算され、重量のない商品は Default product weight (kg) を使用）、Minimum subtotal を確認します。小計は、配送が必要な商品の価格で、クーポン割引後、税抜きの金額です。

固定モードでは、料金は Country prices から取得されます。リアルタイム料金のモードでは、拡張機能は Andreani API にログインし、配送先の郵便番号、契約、顧客コード、kg 単位の重量、商品の寸法から求めた容積、申告額（ARS 建てのカート小計）を指定して見積りを要求します。リアルタイム料金は、有効なアルゼンチンの郵便番号（4 桁、または C1425ABC のような CPA）の場合にのみ要求されます。ストアの通貨が ARS でない場合は、ARS exchange rate で ARS の金額を換算します。料金はストアの既定通貨で計算され、その小数点以下の桁数に丸められ、選択された Tax status の税金を加えて、購入者の通貨で表示されます。

ログイントークンは最長 23 時間保持され、Andreani が拒否した場合は自動的に更新されます。見積りは 1 時間キャッシュされます。失敗した API 呼び出しは 5 分間繰り返されません。これらはすべて OpenCart のキャッシュに保存されるため、エントリーが OpenCart のキャッシュ有効期間（既定では 1 時間）を超えて保持されることはなく、期限が切れると再度問い合わせが行われます。API のエラーが購入者に表示されることはありません。オプションは非表示になるか、フォールバックモードでは固定料金が使われます。理由はログに記録されます。

Free shipping がオンで、カートの小計が Free shipping from に達した場合、料金は 0 になります。送料無料は、そのオプションに料金がある場合にのみ適用されます。Andreani API が料金を返さず、フォールバックとなる固定料金もない場合、オプションは表示されません。

この拡張機能は、Andreani の出荷を作成したり、伝票を印刷したり、荷物を追跡したりしません。これらには Andreani のウェブポータルを使用してください。

OpenCart 4 では、購入者はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options のウィンドウで Andreani のオプションを選択します。オプションは OpenCart 3 と同じように動作します。支店の選択は「受け取り場所」で説明します。

受け取り場所

Door to branch または Branch to branch のオプションが提供されると、配送方法の手順でそのすぐ下に、都道府県の一覧と支店の一覧が表示されます。都道府県は、配送先住所の地域から自動選択されます。支店の一覧は Andreani の公開支店 API から取得され、最長 12 時間キャッシュされます（OpenCart のキャッシュ有効期間内）。荷物を受け取らない支店は表示されません。配送の手順そのものが Andreani を待つことはありません。一覧がまだキャッシュにない場合は、バックグラウンドで読み込まれ、購入者には一時的に Loading Andreani branches... と表示されます。利用可能な支店がない場合、購入者には No Andreani branches available right now. Please try again later or choose another shipping method. と表示されます。

選択は、購入者が選んだ時点で保存されます。受け付けられるのは、Andreani の現在の一覧にある支店のみです。支店がないと、配送の手順の Continue は進まず、購入者には Please select an Andreani pickup branch. と表示されます。購入者が続行すると、サーバーは支店を再度確認します。支店が一覧から消えている場合、購入者には The selected Andreani branch is not available. Please choose another one. と表示されます。

OpenCart 4 では、都道府県の一覧と支店の一覧が Shipping method options のウィンドウに、Andreani の支店オプションのすぐ下に、同じ文言と確認とともに表示されます。支店を選ばずにウィンドウで Continue を押すと、オプションの下に Please select an Andreani pickup branch. と表示され、先に進めません。購入者が続行したときにストアが支店を受け付けない場合、そのメッセージはチェックアウトページの上部に表示され、ウィンドウは開いたままになります。OpenCart 4 はチェックアウトの注文を 1 つ保持し、確認のたびに更新します。注文の支店も一緒に更新され、購入者が注文を別の配送方法に変更すると削除されます。

ある Andreani オプションの下で選んだ支店は、別のオプションや別の配送方法で行われた注文には属しません。

セレクターは、OpenCart 3 の標準テーマのワンページチェックアウトと、OpenCart 4 の標準テーマのチェックアウト向けに作られています。配送の手順のレイアウトが異なるテーマでは、セレクターのスクリプトを変更する必要があるかもしれません。

注文

注文には、配送方式と、支店を使う配送方式の場合は選択された支店が保存されます。

Shipping method of the order: 支店は配送方法のテキストに追加されます。例：Andreani - branch pickup: と支店名。オプション名に支店が含まれていない場合は、支店名の前に Pickup branch:（名前に Andreani が含まれていない場合は Andreani pickup branch:）が追加されます。例：Andreani - Pickup branch: と支店名。このテキストは、購入者とストアへの注文メール、購入者の注文履歴、請求書、管理画面の注文ページに表示されます。OpenCart はテキストを 128 文字に制限しますが、支店の完全なデータは拡張機能が保持します。OpenCart の注文成功ページには配送方法は表示されません。

Admin order page: Sales > Orders で注文を開きます。Andreani パネルには Andreani modality と、支店を使う配送方式の場合は Andreani branch（名前、ID、都道府県）が表示されます。変更するには Edit をクリックし、別の都道府県と支店を選んで Save をクリックします。Branch updated. と表示され、注文の配送方法テキストの支店も置き換えられます。保存できるのは Andreani の一覧にある支店のみです。一覧が利用できない場合は、The Andreani branch list is not available right now - the branch cannot be changed. と表示されます。支店を変更するには、sale/order の変更権限と extension/shipping/vfd_andreani（OpenCart 3）または extension/vfd_andreani/shipping/vfd_andreani（OpenCart 4）へのアクセスが必要です。このパネルは、拡張機能が無効になっている間も、すでに Andreani で注文された注文に対して表示されます。

拡張機能がオフの間は、Andreani パネルは表示されません。支店データは保存されたままで、注文の配送方法テキストも変わりません。既存の注文は支店データを保持します。

ライセンスキー

この拡張機能は、vibefox.net で入手できる VibeFox ライセンスキーで動作します。License — VibeFox Andreani のライセンスブロックは、Extensions > Extensions > Shipping > VibeFox Andreani > Edit ページで設定より上にある最初のブロックです。License key にキーを入力して Activate をクリックします。その後、ブロックにはキーが伏せ字で表示され、ステータス（例：ライセンスの有効期限日とドメイン）と、ボタン Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）が表示されます。その下には Product: opencart-shipping-andreani の行と、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 のアカウントで解放してください。

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

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

トラブルシューティング

チェックアウトに Andreani が表示されない：ライセンスが有効であること、Enable/Disable がオンであること（2 つ目のオプションの場合は Enable second option もオン）、インストール後に Save をクリックしたことを確認してください。Geo zone、または Ignore shipping zones と Countries を確認してください。Country prices にその国の行があること（固定料金またはフォールバック用）、重量の制限、Minimum subtotal を確認してください。Edit ページの上部にある警告を読んでください。商品の Requires Shipping が Yes に設定されていることを確認してください。

リアルタイム料金が表示されない：Debug log をオンにし、チェックアウトを再読み込みして、拡張機能のページにある Log の欄を確認してください。理由が表示されます。認証情報または契約番号の不足、ログインの失敗（ユーザー名、パスワード、環境の誤り）、有効なアルゼンチンの郵便番号がまだない、為替レートがない、Andreani の HTTP エラーなど。Andreani API, fixed price if the API fails を使うと、問題を修正している間も、購入者は固定料金を受け取れます。

ストアの通貨が アルゼンチン・ペソではない：ARS exchange rate を、1 ARS がストアの既定通貨でいくらになるかの値に設定してください。

送料の税金がおかしい：Tax status で税クラスを選ぶと、IVA を含まない Andreani の料金が使われ、OpenCart が独自に税金を加算します。None の場合、IVA を含む料金が使われ、税金は加算されません。ストアの設定で税金が有効になっているか、税クラスにアルゼンチン向けの税率があるかを確認してください。

一覧に支店がない：Andreani の支店 API が応答しませんでした。失敗したリクエストは 5 分後に再試行されます。ログを確認してください。

誤った都道府県が選ばれている：都道府県は配送先住所の地域から読み取られます。購入者はいつでも別の都道府県を選べます。

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

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

開発者向け：Andreani の API ホストは、設定 vfd_andr_api_url（テスト用）で置き換えられます。この設定は設定ページにはフィールドがありません。

アンインストール

Extensions > Extensions に進み、Shipping の種類を選択して、VibeFox Andreani の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは常に削除されます。OpenCart は常にステータス、Sort order、Tax status、Geo zone をリセットします。拡張機能は常にチェックアウトと注文ページのハンドラーを削除し、キャッシュされたトークン、支店一覧、料金も削除します。Remove data on uninstall がオンの場合は、すべての Andreani の設定とデバッグログも削除されます。オフの場合は、他の設定が保持され、拡張機能を再インストールしたときに再び使用されます。注文に保存された支店データは決して削除されず、既存の注文は配送方法と送料をそのまま保持します。

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

Andreani は、それぞれの所有者の商標です。この拡張機能は Andreani との提携や承認を受けていません。