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

Вимоги

OpenCart: 3.0.x (перевірено на 3.0.5.0) або 4.0.2 і новіші (перевірено на 4.1.0.3), стандартна тема.

PHP: 8.0 або новіша.

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

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

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

Архів для завантаження — це один zip-файл із пакетами для обох версій OpenCart. Розпакуйте його на своєму комп’ютері. Він містить 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. Введіть ваш ліцензійний ключ VibeFox у поле License key блоку ліцензії у верхній частині сторінки Edit і натисніть 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. Введіть ліцензійний ключ і налаштування так само, як у кроках 4 і 5 для OpenCart 3. Сторінка налаштувань і її поля однакові в обох версіях.

Після встановлення Enable/Disable і Enable second option вимкнені, і Andreani не пропонується під час оформлення замовлення, доки ви не увімкнете опцію та не натиснете Save. Якщо ви встановите розширення знову після видалення, збережені налаштування Andreani будуть використані знову, але обидві опції вимкнені: увімкніть їх і натисніть Save.

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

Усі налаштування розміщені на сторінці розширення: Extensions > Extensions > Shipping > VibeFox Andreani > Edit. Розділи перелічено ліворуч. Одна кнопка Save зберігає всю сторінку без перезавантаження. Після збереження ви бачите Settings saved. Cached token, branches and rates were cleared. Зберігати налаштування можуть лише адміністратори з правом змінювати це розширення.

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

Під час збереження відхиляється порожня назва, назва довша за 64 символи або з одним із символів < > ; = # { }, Min weight (kg) більша за Max weight (kg), або Sort order, яке не є цілим числом; при цьому нічого не зберігається. Значення, що не є числом, від'ємне число або ARS exchange rate 0 чи менше не зберігаються, і попередження називає поле.

Загальні

У оформленні замовлення Andreani пропонує дві опції: основну, яка налаштовується тут і в розділах Andreani API та Delivery and rates, і Second option. Обидві відображаються під заголовком Andreani на кроці способу доставки.

Enable/Disable: вмикає або вимикає основну опцію Andreani. За замовчуванням: вимкнено. Друга опція має власний перемикач.

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: ваше ім'я користувача в 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=ЦІНА, наприклад 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. Порожнє значення означає 100 кг, 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.

Друга опція

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

Enable second option: пропонує другу опцію під час оформлення замовлення. За замовчуванням: вимкнено.

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 та розрахунки тарифів до storage/logs/vfd_andr_debug.log.php. Файл недоступний для читання з веб. Помилки записуються завжди. Облікові дані й токени ніколи не записуються в журнал. Коли файл досягає 5 МБ, його переносять до 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), вагу кошика (ваги товарів переводяться в кг, товари без ваги використовують Default product weight (kg)) та Minimum subtotal. Проміжна сума — це ціна товарів, які потрібно доставити, після знижки за купоном і без податку.

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

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

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

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

На OpenCart 4 покупець натискає Choose у блоці способу доставки на сторінці оформлення і обирає опцію Andreani у вікні Shipping method options. Опції працюють так само, як на OpenCart 3; вибір відділення описано в розділі Пункти видачі.

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

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

Відділення, обране під однією опцією Andreani, не належить до замовлення, оформленого з іншою опцією або іншим способом доставки.

Вибір розрахований на оформлення замовлення в одну сторінку стандартної теми OpenCart 3 і для оформлення стандартної теми OpenCart 4. Тема з іншою структурою кроку доставки може потребувати змін у скрипті вибору.

Замовлення

Замовлення зберігає спосіб доставки і, для способів із відділенням, обране відділення.

Shipping method of the order: відділення додається до тексту способу доставки, наприклад Andreani - branch pickup: і назва відділення. Якщо назва опції не згадує відділення, перед назвою відділення додається текст Pickup branch: (або Andreani pickup branch:, коли в назві немає Andreani), наприклад 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 з vibefox.net. Блок ліцензії License — VibeFox Andreani є першим блоком на сторінці Extensions > Extensions > Shipping > VibeFox Andreani > Edit, над налаштуваннями. Введіть ключ у поле License key і натисніть Activate. Після цього блок показує ключ прихованим, статус (наприклад, дату, до якої ліцензія активна, і ваш домен) та кнопки Check now — перевірити статус ще раз, Change key — ввести інший ключ і Remove key — видалити ключ із цього магазину. Нижче є рядок Product: opencart-shipping-andreani і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише адміністратори з правом Modify для цього розширення. Тексти блоку відповідають мові адмінпанелі (включено англійську та російську).

Якщо ключ не приймається, блок показує причину, наприклад Key not found, This key belongs to another product, Domain limit reached або License expired on з датою. Після зміни адреси магазину або після звільнення слота домену в обліковому записі натисніть Check now. Якщо сервер ліцензій недоступний, розширення продовжує працювати за останнім відомим статусом.

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

Без активного ключа опції доставки Andreani не показуються покупцям під час оформлення замовлення, і тариф не розраховується. Адміністратор, який увійшов в адмінпанель в тому самому браузері, усе ще бачить спосіб доставки в магазині з позначкою (unlicensed — visible to admins only), тож ви можете налаштувати й перевірити розширення до купівлі ключа. На OpenCart 4 цей попередній перегляд недоступний: магазин не бачить входу адміністратора, тож без активного ключа спосіб доставки приховано для всіх. Після того як ви один раз відкрили сторінку Edit, на сторінці Dashboard адмінпанелі з’являється нагадування. Закрийте його кнопкою ×, щоб приховати на 7 днів. Наявні замовлення не змінюються.

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

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

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

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

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

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

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

Попередньо вибрано неправильну область: область визначається за регіоном адреси доставки. Покупець завжди може вибрати іншу область.

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

Сторінка пише «Warning: You do not have permission to modify VibeFox Andreani!»: можливо, ваша група адміністраторів може лише переглядати налаштування. Надайте групі право змінювати extension/shipping/vfd_andreani (OpenCart 3) або extension/vfd_andreani/shipping/vfd_andreani (OpenCart 4) у System > Users > User Groups.

Для розробників: адреси API Andreani можна замінити налаштуванням vfd_andr_api_url (для тестів); на сторінці налаштувань для нього немає поля.

Видалення

Перейдіть до Extensions > Extensions, оберіть тип Shipping і натисніть Uninstall (червона кнопка −) поруч із VibeFox Andreani. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди скидає статус, Sort order, Tax status і Geo zone. Розширення завжди видаляє свої обробники сторінок оформлення та замовлення, а також кешовані токен, список відділень і тарифи. Якщо Remove data on uninstall увімкнено, також видаляються всі налаштування Andreani і журнал налагодження. Якщо вимкнено, решта налаштувань зберігається і знову використовується під час повторного встановлення розширення. Дані про відділення, збережені в замовленнях, ніколи не видаляються, а наявні замовлення зберігають свій спосіб доставки та вартість.

На OpenCart 4, щоб видалити також файли розширення, після видалення перейдіть до Extensions > Installer і натисніть Uninstall (помаранчева кнопка −) поруч із VibeFox Andreani у списку встановлених розширень, а потім Delete (червона кнопка з кошиком), щоб видалити завантажений пакет.

Andreani — торговельна марка її власника. Це розширення не пов'язане з Andreani і не схвалене нею.