VibeFox Andreani for PrestaShop — Допомога

Вимоги

PrestaShop: від 8.0 до 9.x.

PHP: 8.0 або новіша версія. Модуль не встановлюється на старіших версіях PHP.

Обліковий запис Andreani (лише для актуальних тарифів): актуальні тарифи використовують API котирувань Andreani. Andreani видає бізнес-клієнтам облікові дані API, код клієнта та номери договорів, зазвичай від приблизно 300 відправлень на місяць. Див. developers.andreani.com або напишіть на ventapyme@andreani.com. Вам потрібні ім'я користувача й пароль API, код клієнта та номер договору. Andreani видає окремий договір для кожної послуги (доставка додому, самовивіз з відділення). Без доступу до API використовуйте фіксовані ціни. Вибір відділення працює без облікових даних.

VibeFox license key: купується на vibefox.net. Один ключ працює на одному домені.

Встановлення

1. В адмінпанелі перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

2. Коли завантаження завершиться, натисніть Configure або пізніше знайдіть VibeFox Andreani у списку модулів і натисніть Configure.

3. Введіть ваш ліцензійний ключ VibeFox у поле License key у блоці ліцензії у верхній частині сторінки Configure і натисніть Activate (див. розділ «Ліцензійний ключ»).

4. Вкажіть назву, джерело тарифів, ціни за країнами (наприклад AR=5000) і, для актуальних тарифів, облікові дані API, код клієнта та номер договору (див. розділ «Конфігурація»). Натисніть Save.

Під час встановлення модуль створює двох перевізників:

Обидва перевізники прив'язані до зони Аргентини та до всіх груп клієнтів. Зони, групи клієнтів, строк доставки, логотип і обмеження розмірів можна змінити в Shipping > Carriers. Ціни там не задавайте: ціна завжди береться з модуля.

Конфігурація

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox Andreani > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Після збереження ви побачите Settings saved. Cached token, branches and rates were cleared. Попередження про відсутні налаштування (облікові дані API, номер договору, курс ARS, немає ціни для Аргентини, видалений перевізник) відображаються у верхній частині сторінки. Попередження також з'являється, якщо модуль не розпізнає одиницю ваги або розмірів магазину (тоді вага читається як кг, а розміри як см). Під час збереження назва довша за 64 символи або Min weight (kg), більше за Max weight (kg), відхиляються, і нічого не зберігається. Значення, яке не є числом, від'ємне число або ARS exchange rate 0 чи менше, не зберігається, а попередження вказує на поле.

General

Enable/Disable: вмикає або вимикає доставку Andreani. Це той самий перемикач, що й статус основного перевізника в Shipping > Carriers. Другий варіант має власний перемикач.

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: ваше ім'я користувача API Andreani.

API password: ваш пароль API Andreani. Після збереження поле залишається порожнім і показує Saved - leave empty to keep it. Clearing the API username removes it too. Вводьте нове значення, лише якщо хочете його змінити.

Client code: код клієнта (código de cliente), наданий Andreani, наприклад CL0000000.

Contract number: договір послуги, яка використовується для тарифів, наприклад доставка додому. Другий варіант може використовувати інший договір, наприклад для самовивозу з відділення.

Origin branch code: необов'язкове відділення відправлення (sucursalOrigen) для котирувань. Залиште порожнім, щоб використовувати відділення, вказане у вашому договорі.

Доставка та тарифи

Delivery modality: спосіб доставки основного перевізника. Перша частина показує, звідки Andreani забирає посилку (ваша адреса або відділення, куди ви її здаєте). Друга частина показує, де її отримує покупець.

Rate source: як розраховується ціна.

Country prices: фіксована ціна для кожної країни призначення у валюті за замовчуванням вашого магазину, без податків, один рядок на країну у форматі CC=PRICE, наприклад AR=5000. Використовується у фіксованому режимі та як запасний варіант, якщо API не працює. Країни без рядка не мають фіксованої ціни. Рядки в іншому форматі ігноруються, а попередження перелічує їх під час збереження.

ARS exchange rate: Andreani формує котирування в аргентинських песо. Потрібно лише тоді, коли валюта за замовчуванням вашого магазину не ARS: ціна 1 ARS у валюті вашого магазину, наприклад 0.001. Без нього тарифи API не використовуються.

Default product weight (kg): використовується для товарів без ваги під час запитів тарифів API та перевірки обмежень за вагою. Якщо поле порожнє, це 0,5 кг.

Calculation type: Per order стягує ціну один раз. Per item (price x number of items) множить фіксовану ціну з Country prices на кількість товарів у кошику. Актуальний тариф Andreani вже розрахований на весь кошик і не множиться.

Доступність

Min weight (kg): мінімальна вага кошика, за якої з'являється перевізник. 0 означає без обмеження.

Max weight (kg): максимальна вага кошика. Якщо її перевищено, перевізника приховано. Порожнє поле означає 100 кг, 0 означає без обмеження.

Minimum subtotal: показувати перевізника лише тоді, коли проміжна сума кошика (товари, що потребують доставки, після знижок, без податків) становить щонайменше цю суму. Залиште порожнім, щоб показувати його завжди.

Ignore shipping zones: пропонувати Andreani для країн, зазначених нижче, без налаштування зон. Коли це увімкнено, обидва перевізники прив'язуються до всіх зон, а зона, створена пізніше, прив'язується одразу. Коли це вимкнено, перевізники повертають свої попередні зони.

Countries: країни призначення для цього режиму. Залиште порожнім, щоб дозволити всі країни. Використовується лише тоді, коли Ignore shipping zones увімкнено.

Безкоштовна доставка

Free shipping: вмикає поріг безкоштовної доставки.

Free shipping from: проміжна сума кошика, починаючи з якої доставка безкоштовна. Потребує, щоб Free shipping було увімкнено.

Другий варіант

Другий перевізник Andreani з власною назвою, способом доставки та договором, наприклад "a domicilio" у основного перевізника і "retiro en sucursal" тут, щоб пропонувати обидва. Усі інші налаштування спільні.

Enable second option: вмикає або вимикає другого перевізника. Це той самий перемикач, що й його статус у Shipping > Carriers. За замовчуванням: вимкнено.

Second option name: назва цього варіанта під час оформлення замовлення. За замовчуванням: Andreani - branch pickup. Обов'язкове поле.

Delivery modality: Use global setting або один із чотирьох способів. За замовчуванням: 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 у папці модуля. Файл не можна відкрити з веб-браузера. Помилки записуються завжди. Облікові дані та токени ніколи не записуються.

Log: показує розмір і останні записи журналу. Натисніть Clear log, щоб очистити його.

Remove data on uninstall: якщо увімкнено, під час видалення модуля видаляються всі його налаштування та перевізники. Якщо вимкнено, під час видалення перевізники лише вимикаються. Дані про відділення, збережені в замовленнях, завжди зберігаються.

Як це працює під час оформлення замовлення

На кроці доставки PrestaShop запитує в модуля ціну кожного перевізника Andreani. Враховуються лише фізичні товари: віртуальні товари не додають ваги й не входять до проміжної суми. Модуль перевіряє країни (коли Ignore shipping zones увімкнено), вагу кошика (ваги товарів переводяться в кг, а товари без ваги використовують Default product weight (kg)) та Minimum subtotal.

У фіксованому режимі ціна береться з Country prices. У режимах актуальних тарифів модуль входить в API Andreani і запитує котирування з поштовим індексом призначення, договором, кодом клієнта, вагою в кг, об'ємом за розмірами товарів і оголошеною вартістю (проміжна сума кошика в ARS). Актуальний тариф запитується лише для коректного аргентинського поштового індексу. Сума в ARS конвертується за ARS exchange rate, якщо валюта вашого магазину не ARS. Ціна розраховується у валюті за замовчуванням вашого магазину, а потім показується у валюті кошика покупця.

Токен входу кешується на 23 години і автоматично оновлюється, коли Andreani його відхиляє. Котирування кешуються на 1 годину. Невдалий запит до API не повторюється протягом 5 хвилин. Помилки API ніколи не показуються покупцеві: перевізника приховано або в режимі запасного варіанта використовується фіксована ціна. Причина записується в журнал.

Якщо Free shipping увімкнено і проміжна сума кошика досягає Free shipping from, ціна становить 0. Безкоштовна доставка застосовується лише там, де перевізник має ціну: якщо API Andreani не повертає тариф і немає фіксованої ціни для запасного варіанта, перевізника не показано.

Якщо ви редагуєте перевізника в Shipping > Carriers після того, як у нього з'явилися замовлення, PrestaShop зберігає його як нову версію перевізника. Модуль автоматично слідує за новою версією.

Модуль не створює відправлень Andreani, не друкує етикетки і не відстежує посилки. Для цього скористайтеся веб-порталом Andreani.

Пункти видачі

Коли обрано перевізника з Door to branch або Branch to branch, під ним на кроці доставки з'являються список областей і список відділень. Область попередньо вибирається за адресою доставки. Список відділень береться з публічного API відділень Andreani і кешується на 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 з vibefox.net. Блок ліцензії 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. Якщо сервер ліцензій недоступний, модуль продовжує працювати за останнім відомим статусом.

Один ключ працює на одному домені: домен головного магазину, також у мультимагазинній конфігурації. Видалення ключа з магазину не звільняє слот домену. Звільніть слот у своєму обліковому записі vibefox.net.

Без активного ключа перевізники Andreani не показуються покупцям під час оформлення замовлення, і тариф не розраховується. Вітрина PrestaShop не знає, що ви увійшли в бек-офіс, тому перевізники приховані й для вас: ви можете налаштувати модуль до купівлі ключа, але не можете перевірити його під час оформлення замовлення. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються.

Коли термін ліцензії спливає, модуль продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус автоматично перевіряється під час роботи в бек-офісі: раз на день протягом перших 14 днів після введення ключа, потім раз на тиждень. Cron-завдання не потрібне. Видалення або скидання модуля завжди видаляє ліцензійний ключ і статус ліцензії.

Усунення несправностей

Andreani не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і Enable/Disable увімкнено (для другого перевізника також Enable second option). У Shipping > Carriers перевірте, що перевізник охоплює зону країни покупця та його групу клієнтів, або увімкніть Ignore shipping zones і перевірте Countries. Перевірте, що в Country prices є рядок для країни (для фіксованих цін або як запасний варіант), і перевірте обмеження за вагою та Minimum subtotal. Прочитайте попередження у верхній частині сторінки Configure. Крім того, товари можуть бути обмежені певними перевізниками на сторінці товару.

Актуальні тарифи не з'являються: увімкніть Debug log, перезавантажте оформлення замовлення та перегляньте поле Log на сторінці модуля. Там показано причину: відсутні облікові дані або номер договору, невдалий вхід (неправильні ім'я користувача, пароль чи середовище), поки немає коректного аргентинського поштового індексу, немає курсу обміну або HTTP-помилка Andreani. З Andreani API, fixed price if the API fails покупці все одно отримують фіксовану ціну, поки ви виправляєте проблему.

Мій магазин не в аргентинських песо: встановіть ARS exchange rate як значення 1 ARS у валюті за замовчуванням вашого магазину.

Податок на доставку виглядає неправильно: з податковим правилом у Tax status використовується тариф Andreani без IVA, а PrestaShop додає власний податок. Із None використовується тариф з IVA і податок не додається. Перевірте, що податки увімкнено і податкове правило налаштоване для Аргентини.

У списку немає відділень: API відділень Andreani не відповіло. Невдалий запит повторюється через 5 хвилин. Перевірте журнал.

Тарифи виглядають застарілими після зміни: натисніть Save на сторінці модуля. Це очистить кешований токен, список відділень і тарифи.

Сторінка повідомляє, що перевізник Andreani не знайдено: перевізника видалено в Shipping > Carriers. Скиньте модуль у Modules > Module Manager, щоб створити його знову.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox Andreani і оберіть Uninstall. Ліцензійний ключ і статус ліцензії завжди видаляються. Кешований токен, список відділень і тарифи також завжди видаляються. Якщо Remove data on uninstall увімкнено, перевізники видаляються (замовлення зберігають історію), а налаштування, журнал і вибір відділень у кошиках без замовлення видаляються. Якщо вимкнено, перевізники лише вимикаються, а всі налаштування зберігаються. Повторне встановлення модуля або Reset модуля повертає обом перевізникам їхній попередній статус. Дані про відділення, збережені в замовленнях, ніколи не видаляються.

Andreani є торговою маркою її власника. Цей модуль не афілійований з Andreani і не схвалений Andreani.