VibeFox Andreani for PrestaShop — ヘルプ
要件
PrestaShop: 8.0 から 9.x。
PHP: 8.0 以降。モジュールは古い PHP バージョンではインストールできません。
Andreani アカウント（リアルタイム料金のみ必要）:リアルタイム料金は Andreani の見積り API を使用します。Andreani は法人顧客に API 認証情報、顧客コード、契約番号を発行します。通常は月におよそ 300 件の発送から利用できます。developers.andreani.com をご覧になるか、ventapyme@andreani.com までお問い合わせください。API のユーザー名とパスワード、顧客コード、契約番号が必要です。Andreani はサービスごと（自宅配送、営業所受け取り）に別の契約を発行します。API アクセスがない場合は、固定料金をご利用ください。営業所セレクターは認証情報がなくても動作します。
VibeFox license key: vibefox.net で購入します。1 つのキーは 1 つのドメインで動作します。
インストール
1. 管理画面で Modules > Module Manager に進み、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックするか、後でモジュール一覧から VibeFox Andreani を探して Configure をクリックします。
3. Configure ページ上部のライセンスブロックの License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。
4. 名前、料金のソース、国ごとの料金（例: AR=5000）を設定し、リアルタイム料金を使う場合は API 認証情報、顧客コード、契約番号も設定します（設定を参照）。Save をクリックします。
インストール時に、モジュールは 2 つの配送業者を作成します。
両方の配送業者は、アルゼンチンのゾーンとすべての顧客グループに割り当てられます。ゾーン、顧客グループ、配送時間、ロゴ、サイズ制限は Shipping > Carriers で変更できます。ここで料金を設定しないでください。料金は常にモジュールから取得されます。
設定
すべての設定はモジュールのページにあります: Modules > Module Manager > VibeFox Andreani > Configure。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。保存後には Settings saved. Cached token, branches and rates were cleared. と表示されます。未設定項目（API 認証情報、契約番号、ARS 為替レート、アルゼンチンの料金がない、配送業者が削除された）に関する警告は、ページの上部に表示されます。モジュールがショップの重量または寸法の単位を認識できない場合も警告が表示されます（その場合、重量は kg、寸法は cm として扱われます）。保存時、64 文字を超える名前や、Max weight (kg) より大きい Min weight (kg) は拒否され、何も保存されません。数値でない値、負の数、または 0 以下の ARS exchange rate は保存されず、警告で該当フィールドが示されます。
General
Enable/Disable: Andreani の配送を有効または無効にします。Shipping > Carriers のメイン配送業者のステータスと同じスイッチです。2 つ目のオプションには独自のスイッチがあります。
Name: 購入者がチェックアウトで見る配送業者の名前。既定値: Andreani。必須。
Tax status: None、または税ルールのいずれかを選んだ Taxable。税ルールを使うと、ショップは配送料に税を加算するため、API の料金は IVA を含まない額が使われます。None の場合、API の料金は IVA 込みの額が使われます。この設定は両方の 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 kg、0 は制限なしを意味します。
Minimum subtotal: カートの小計（配送が必要な商品、割引後、税抜き）がこの金額以上の場合にのみ配送業者を表示します。空欄の場合は常に表示します。
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 つ目の配送業者を有効または無効にします。Shipping > Carriers でのステータスと同じスイッチです。既定: 無効。
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 のリクエストと料金計算を、モジュールフォルダー内の logs/vfd_andr_debug.log.php に記録します。このファイルは Web から開くことはできません。エラーは常に記録されます。認証情報やトークンは記録されません。
Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると空になります。
Remove data on uninstall: 有効にすると、モジュールのアンインストール時にすべてのモジュール設定と配送業者が削除されます。無効の場合、アンインストールでは配送業者を無効にするだけです。注文に保存された営業所のデータは常に保持されます。
チェックアウトでの動作
配送ステップで PrestaShop は、各 Andreani 配送業者の料金をモジュールに問い合わせます。対象となるのは実物の商品のみです。仮想商品は重量に加算されず、小計にも含まれません。モジュールは、国（Ignore shipping zones が有効な場合）、カートの重量（商品の重量は kg に換算され、重量のない商品は Default product weight (kg) を使用）、Minimum subtotal を確認します。
固定モードでは、料金は Country prices から取得されます。リアルタイムモードでは、モジュールは Andreani API にログインし、配送先の郵便番号、契約、顧客コード、kg 単位の重量、商品の寸法から求めた容積、申告価値（ARS 建てのカート小計）を使って見積りを要求します。リアルタイム料金は、有効なアルゼンチンの郵便番号に対してのみ要求されます。ショップの通貨が ARS でない場合、ARS 建ての金額は ARS exchange rate で換算されます。料金はショップの既定通貨で計算され、その後、購入者のカート通貨で表示されます。
ログイン用のトークンは 23 時間キャッシュされ、Andreani に拒否された場合は自動的に更新されます。見積りは 1 時間キャッシュされます。API 呼び出しに失敗した場合は 5 分間再試行されません。API のエラーは購入者に表示されません。配送業者は非表示になるか、フォールバックモードでは固定料金が使われます。理由はログに記録されます。
Free shipping が有効で、カート小計が Free shipping from に達すると、料金は 0 になります。送料無料は、配送業者に料金がある場合にのみ適用されます。Andreani API が料金を返さず、フォールバック用の固定料金もない場合、配送業者は表示されません。
注文がある配送業者を Shipping > Carriers で編集すると、PrestaShop はそれを新しい配送業者のバージョンとして保存します。モジュールは新しいバージョンに自動的に従います。
モジュールは Andreani の配送データの作成、ラベルの印刷、荷物の追跡は行いません。これらには Andreani の Web ポータルをご利用ください。
受け取り拠点
Door to branch または Branch to branch の配送業者を選択すると、配送ステップではその下に都道府県リストと営業所リストが表示されます。都道府県は配送先住所から事前に選択されます。営業所リストは Andreani の公開営業所 API から取得され、12 時間キャッシュされます。荷物の引き渡しを行わない営業所は表示されません。利用可能な営業所がない場合、購入者には 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. と表示されます。
購入者が別の配送業者に切り替える前に Andreani で選択した営業所は、注文には含まれません。
注文
注文には配送モードが保存され、営業所を使うモードの場合は選択された営業所も保存されます。
Admin order page: Andreani ブロックに、配送モードと営業所（名前、ID、都道府県）が表示されます。Edit をクリックし、別の都道府県と営業所を選択して Save をクリックすると変更できます。Branch updated. と表示されます。保存できるのは Andreani のリストにある営業所のみです。リストが利用できない場合は、営業所を変更できません。
購入者:営業所は、注文確認ページと注文詳細ページに Andreani pickup branch: として表示されます。
メール:注文確認メールと、ショップに届く新規注文メール（Mail alerts モジュール）では、配送業者の名前に営業所が追加されます。ショップ宛のメールには営業所の ID も表示されます。
既存の注文は、営業所のデータをそのまま保持します。
ライセンスキー
このモジュールは、vibefox.net で入手した VibeFox ライセンスキーで動作します。License — VibeFox Andreani ライセンスブロックは、Modules > Module Manager > VibeFox Andreani > Configure ページで設定より上にある最初のブロックです。キーを License key に貼り付けて Activate をクリックします。その後、ブロックにはキーがマスク表示され、ステータス（ライセンスの有効期限の日付やドメインなど）が表示されます。また、ステータスを再確認する Check now、別のキーを入力する Change key、このショップからキーを削除する Remove key のボタンがあります。その下には Product: presta-shipping-andreani の行と、Manage licenses and domains in your account のリンクがあり、vibefox.net のアカウントが開きます。キーを変更できるのは、モジュールの Configure 権限を持つ従業員のみです。ブロックの表示テキストは管理画面の言語に従います（英語とロシア語が含まれています）。
キーが受け付けられない場合、ブロックに理由が表示されます。例: Key not found、This key belongs to another product、Domain limit reached、または License expired on と日付。ショップのアドレスを変更した後、またはアカウントでドメインの枠を解放した後に、Check now をクリックしてください。ライセンスサーバーに接続できない場合、モジュールは最後に確認されたステータスで動作を続けます。
1 つのキーは 1 つのドメインで動作します。これはメインショップのドメインで、マルチストア構成でも同様です。ショップからキーを削除しても、ドメインの枠は解放されません。枠は vibefox.net のアカウントで解放してください。
有効なキーがないと、Andreani の配送業者はチェックアウトで購入者に表示されず、料金も計算されません。PrestaShop のストアフロントは、管理画面にログインしていることを認識しないため、配送業者はあなたにも表示されません。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。
ライセンスの有効期限が切れた場合も、モジュールは動作し続けますが、アップデートとサポートには更新が必要です。ステータスは管理画面での作業中に自動的に再確認されます。キー入力後の最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
チェックアウトに Andreani が表示されない:ライセンスが有効であること、Enable/Disable が有効であることを確認してください（2 つ目の配送業者の場合は Enable second option も）。Shipping > Carriers で、配送業者が購入者の国のゾーンと顧客グループを対象にしているか確認するか、Ignore shipping zones を有効にして Countries を確認してください。Country prices にその国の行があるか（固定料金またはフォールバックとして）、重量制限と Minimum subtotal を確認してください。Configure ページ上部の警告も確認してください。また、商品ページで特定の配送業者に制限されている場合もあります。
リアルタイム料金が表示されない:Debug log を有効にし、チェックアウトを再読み込みして、モジュールのページにある Log 欄を確認してください。原因が表示されます: 認証情報や契約番号の欠落、ログインの失敗（ユーザー名、パスワード、環境の誤り）、有効なアルゼンチンの郵便番号がまだない、為替レートがない、または Andreani の HTTP エラー。Andreani API, fixed price if the API fails を使用していれば、問題を修正している間も、購入者は固定料金を受け取れます。
ショップがアルゼンチン・ペソではない:ARS exchange rate に、1 ARS のショップ既定通貨での価値を設定してください。
配送の税が正しくないように見える:Tax status で税ルールを使うと、IVA を含まない Andreani の料金が使われ、PrestaShop が独自に税を加算します。None の場合は IVA を含む料金が使われ、税は加算されません。税機能が有効で、アルゼンチン向けの税ルールが設定されていることを確認してください。
リストに営業所がない:Andreani の営業所 API が応答しませんでした。失敗したリクエストは 5 分後に再試行されます。ログを確認してください。
変更後に料金が古いように見える:モジュールのページで Save をクリックしてください。キャッシュされたトークン、営業所リスト、料金がクリアされます。
Andreani の配送業者が見つからないと表示される:配送業者が Shipping > Carriers で削除されています。Modules > Module Manager でモジュールをリセットすると再作成されます。
アンインストール
Modules > Module Manager に進み、VibeFox Andreani の横のメニューを開いて Uninstall を選択します。ライセンスキーとライセンスステータスは常に削除されます。キャッシュされたトークン、営業所リスト、料金も常に削除されます。Remove data on uninstall が有効な場合、配送業者は削除されます（注文は履歴を保持します）。また、設定、ログ、注文のないカートの営業所選択も削除されます。無効な場合、配送業者は無効になるだけで、すべての設定は保持されます。モジュールを再インストールするか、モジュールを Reset すると、両方の配送業者は以前のステータスに戻ります。注文に保存された営業所のデータは削除されません。
Andreani は各所有者の商標です。本モジュールは Andreani と提携しておらず、Andreani による推奨も受けていません。