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

Вимоги

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

PHP: 8.0 або новіша версія.

Обліковий запис Envioclick (лише для актуальних тарифів): обліковий запис Envioclick у Мексиці або Колумбії з доступом до API. Ключ API знаходиться у вашому обліковому записі Envioclick: Mi cuenta (угорі праворуч) > Información del API. Якщо ви використовуєте лише фіксовані тарифи, обліковий запис Envioclick не потрібен.

User-Agent (лише Мексика): Envioclick Мексика вимагає значення User-Agent у кожному запиті до API. Запитайте його у служби підтримки Envioclick (soporte.tecnico@envioclick.com).

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

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

Завантаження — це один zip-файл із пакетами для обох версій OpenCart. Розпакуйте його на комп'ютері. Він містить README.txt, пакет для OpenCart 3 vfd_envioclick-oc3-(version).ocmod.zip і пакет для OpenCart 4 vfd_envioclick.ocmod.zip. Встановлюйте лише пакет для вашої версії OpenCart. Ліцензійний ключ однаковий для обох версій.

OpenCart 3

1. В адмін-панелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл vfd_envioclick-oc3-(version).ocmod.zip. Розширення не додає модифікацій OCMOD, тож оновлювати Extensions > Modifications не потрібно. Замість інсталятора можна скопіювати вміст папки upload цього пакета в кореневу папку вашого магазину.

2. Перейдіть до Extensions > Extensions і виберіть тип розширень Shipping. Знайдіть VibeFox Envioclick і натисніть Install (зелена кнопка +).

3. Натисніть Edit (кнопка з олівцем), щоб відкрити сторінку налаштувань.

4. Введіть ліцензійний ключ VibeFox у поле License key у блоці ліцензії вгорі сторінки Edit і натисніть Activate (див. Ліцензійний ключ).

5. Введіть ключ API, оберіть країну API, введіть User-Agent (Мексика), поштовий індекс або код DANE відправлення та адресу відправлення. Якщо валюта за замовчуванням вашого магазину не MXN і не COP, введіть курс конвертації. За бажанням додайте фіксовані тарифи за країнами та вартість за замовчуванням. Увімкніть Enable Envioclick і натисніть Save.

OpenCart 4

1. В адмін-панелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл vfd_envioclick.ocmod.zip. Не перейменовуйте файл: OpenCart 4 бере код розширення з назви файлу, і перейменований пакет не працює.

2. Пакет з'явиться у списку встановлених розширень на тій самій сторінці. Натисніть поруч Install (зелена кнопка +).

3. Перейдіть до Extensions > Extensions і виберіть тип розширень Shipping. Знайдіть VibeFox Envioclick, натисніть Install (зелена кнопка +), потім Edit (кнопка з олівцем).

4. Введіть ліцензійний ключ і налаштування так само, як у кроках 4 і 5 для OpenCart 3. Сторінка налаштувань і її поля однакові в обох версіях.

Після встановлення спосіб вимкнений, доки ви не увімкнете Enable Envioclick і не збережете налаштування. Якщо ви встановите розширення повторно після видалення, будуть використані збережені налаштування Envioclick.

Налаштування

Усі налаштування містяться на сторінці розширення: Extensions > Extensions > Shipping > VibeFox Envioclick > Edit. Розділи перелічено ліворуч. Одна кнопка Save внизу зберігає всю сторінку без перезавантаження. Кожне збереження також очищає закешовані розрахунки Envioclick. Числові поля приймають як крапку, так і кому як десятковий роздільник. Зберігати налаштування можуть лише адміністратори з правом змінювати це розширення.

Розділ General показує попередження, якщо актуальні тарифи не можуть працювати із збереженими налаштуваннями: немає курсу конвертації для валюти магазину, відмінної від MXN або COP; немає User-Agent для Мексики; немає поштового індексу або коду DANE відправлення; або немає адреси відправлення для Колумбії. Також попереджає, якщо одиницю ваги чи довжини магазину не розпізнано; тоді додайте клас ваги з одиницею kg у System > Localisation > Weight Classes або клас довжини з одиницею cm у System > Localisation > Length Classes. Під час збереження розширення перевіряє, що Method title містить від 1 до 64 символів, що числові поля містять невід'ємні числа, що Currency conversion rate більший за 0, що Minimum weight (kg) не більший за Maximum weight (kg), що код відправлення має 5 цифр для Мексики або 8 цифр (чи 5-значний код муніципалітету) для Колумбії, що кожен рядок Price per country має дійсну країну та ціну, і що Sort order є цілим числом. Якщо перевірка не проходить, нічого не зберігається, а сторінка перелічує помилки.

Загальні

Покупець бачить один тариф Envioclick — найдешевшого або найшвидшого перевізника. Спосіб можна обмежити геозоною або країнами в розділі Availability.

Enable Envioclick: показує або приховує Envioclick під час оформлення замовлення. За замовчуванням: вимкнено.

Method title: назва способу доставки, яку бачить покупець у кошику та під час оформлення замовлення, до 64 символів. За замовчуванням: Envioclick Shipping. Обов'язкове поле.

Carrier in the title: додає до назви перевізника Envioclick і орієнтовний строк доставки актуального тарифу, наприклад «Envioclick Shipping (Estafeta Express, 1 day)». OpenCart зберігає цю назву разом із замовленням, тож вона також з'являється в листах про замовлення та на сторінках замовлень. Перевізник у будь-якому разі зберігається в замовленні. За замовчуванням: увімкнено.

Sort order: позиція Envioclick серед способів доставки під час оформлення замовлення. Ціле число.

API Envioclick (актуальні тарифи)

Необов'язково. Без ключа API використовуються лише фіксовані тарифи. Розділ містить посилання на документацію API Envioclick для Мексики та Колумбії. Актуальні тарифи запитуються лише для напрямків у країні API. Доставка в інші країни використовує фіксовані тарифи.

API key: ваш ключ API Envioclick з розділу Mi cuenta > Información del API. Він передається в заголовку «Authorization» і ніколи не показується покупцям та не записується в журнал. Після збереження поле лишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Remove the saved API key: увімкніть цю опцію і збережіть налаштування, щоб видалити збережений ключ; тоді використовуються лише фіксовані тарифи. Ключ, введений у поле API key, замінює збережений. Перемикач вимикається сам після збереження.

API country: країна вашого облікового запису Envioclick.

User-Agent (Mexico): значення, яке видає служба підтримки Envioclick (soporte.tecnico@envioclick.com), наприклад EcUserAgent-2/123456. Обов'язкове для Мексики; без нього актуальні тарифи для Мексики не запитуються. Для Колумбії необов'язкове.

Carrier choice: Cheapest (за замовчуванням) або Fastest (then cheapest). Envioclick повертає розрахунки від кількох перевізників, а покупець отримує один тариф.

Branch pickup rates: також враховувати тарифи «Ocurre», за яких покупець забирає посилку у відділенні перевізника. Коли вимкнено, використовуються лише тарифи доставки до дверей. Послуги накладеного платежу (COD) ніколи не використовуються. За замовчуванням: вимкнено.

Currency conversion rate: Envioclick розраховує тарифи в MXN (Мексика) або COP (Колумбія). Якщо валюта за замовчуванням вашого магазину інша, введіть значення 1 MXN або 1 COP у валюті вашого магазину, наприклад 0.05. Оголошена вартість посилки конвертується так само. Залиште поле порожнім, якщо валюта магазину MXN або COP. Без нього актуальні тарифи в іншій валюті не використовуються.

Відправлення з

Використовується для актуальних тарифів. OpenCart не має поштового індексу, міста чи вулиці магазину, тож введіть їх тут.

Origin postcode / DANE code: Мексика: 5-значний поштовий індекс. Колумбія: 8-значний код DANE муніципалітету, наприклад 11001000 для Боготи; 5-значний код муніципалітету (11001) доповнюється до 000.

Origin address: вулиця та номер адреси, за якою здійснюється забір відправлень. Обов'язкове для Колумбії, необов'язкове для Мексики.

Фіксовані тарифи

Використовуються, коли актуального тарифу немає: немає ключа API, напрямок поза країною API, помилка API або немає перевізника для маршруту.

Price per country: список країн і цін у валюті за замовчуванням вашого магазину, без податку. Натисніть Add country, щоб додати рядок, і кнопку × — щоб видалити. Виберіть * All other countries для ціни, яка застосовується до всіх країн без власного рядка.

Fallback cost: використовується, коли актуального тарифу немає і жоден рядок таблиці не підходить. Залиште поле порожнім, щоб у цьому випадку приховати спосіб.

Fixed price applies: Per order (за замовчуванням) стягує ціну один раз. Per item (price × quantity) множить її на кількість товарів у кошику. Актуальні тарифи Envioclick завжди розраховуються за відправлення.

Умови

Minimum weight (kg): приховує спосіб, якщо вага кошика нижча за це значення. 0 означає відсутність обмеження (за замовчуванням).

Maximum weight (kg): приховує спосіб, якщо вага кошика вища за це значення. За замовчуванням: 25. 0 означає відсутність обмеження.

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

Free shipping from: безкоштовна доставка, коли проміжна сума товарів, що потребують доставки (після купона, до податку), досягає цієї суми. До API в такому разі запит не надсилається. Залиште поле порожнім, щоб ніколи не пропонувати безкоштовну доставку.

Tax class: клас податку на вартість доставки або No tax (за замовчуванням). Розрахунки Envioclick уже включають податки перевізників, тож виберіть No tax, щоб не стягувати податок на доставку двічі.

Доступність

Зазвичай спосіб пропонується для адрес у вибраній геозоні або скрізь.

Geo zone: пропонувати Envioclick лише для адрес у цій геозоні. All zones (за замовчуванням) означає відсутність обмеження. Геозони керуються в System > Localisation > Geo Zones. Не перевіряється, коли увімкнено Ignore shipping zones.

Ignore shipping zones: не перевіряти геозону; вирішує список країн нижче. За замовчуванням: вимкнено.

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

Додатково

Debug log: записує розрахунки тарифів і помилки API у storage/logs/vfd_evc_debug.log.php (в OpenCart 4 system/storage/logs/vfd_evc_debug.log.php). Файл не можна прочитати з веб-браузера. Ключ API та адреси покупців не записуються. Поки журнал вимкнено, нічого не записується, навіть помилки API. Вимкніть його, коли закінчите. Коли файл досягає 5 МБ, його переміщують до vfd_evc_debug.old.log.php і починають новий журнал.

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

Remove data on uninstall: коли увімкнено, видалення розширення стирає налаштування Envioclick, закешовані розрахунки та журнал. Коли вимкнено (за замовчуванням), вони зберігаються для повторного встановлення. Дані Envioclick оформлених замовлень завжди зберігаються.

Імпорт / Експорт

Export: натисніть Download JSON, щоб зберегти налаштування у файл JSON. Ключ API не експортується.

Import: вставте раніше експортований JSON і натисніть Import, щоб відновити налаштування, наприклад в іншому магазині. Значення перевіряються так само, як під час звичайного збереження. Збережений ключ API залишається.

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

Коли OpenCart показує способи доставки, він запитує в розширення ціну Envioclick. Якщо задано Geo zone (і Ignore shipping zones вимкнено), а адреса знаходиться поза нею, Envioclick не пропонується. Враховуються лише товари з Requires Shipping, встановленим на Yes: інші товари не додають ваги і не входять до суми замовлення. Далі розширення перевіряє умови: країни з Ignore shipping zones, вагу кошика та мінімальну суму замовлення. Сума замовлення — це ціна товарів, що потребують доставки, після знижки за купоном і до податку. Подарункові сертифікати, бонусні бали та кредит магазину не враховуються. Якщо діє безкоштовна доставка, ціна дорівнює 0 і запит до Envioclick не надсилається.

Якщо ключ API задано і напрямок знаходиться в країні API, розширення запитує розрахунки в Envioclick. У Мексиці запит надсилається, коли покупець ввів 5-значний поштовий індекс. У Колумбії він надсилається, коли муніципалітет розпізнано за 8-значним кодом DANE в полі поштового індексу або за департаментом (регіоном адреси OpenCart) і містом; назва міста, унікальна в Колумбії, розпізнається без департаменту. Регістр і діакритичні знаки не мають значення. Розширення обирає найдешевший або найшвидший розрахунок, який не є накладеним платежем, і перераховує його у валюту магазину за замовчуванням. Ціна округлюється до знаків після коми цієї валюти і показується покупцеві у його валюті з податком вибраного Tax class.

Посилка завжди одна коробка: загальна вага, переведена в кг із класів ваги товарів, і розмір коробки з габаритів товарів, переведених у см. Товари без габаритів враховуються як 10 × 10 × 10 см. Кошик без жодної ваги надсилається як 0,5 кг. Оголошена вартість — це сума замовлення.

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

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

В OpenCart 4 покупець натискає Choose у блоці способу доставки на сторінці оформлення замовлення і вибирає Envioclick у вікні Shipping method options. Спосіб працює так само, як в OpenCart 3.

Замовлення

Коли замовлення оформлюється через Envioclick, тариф, розрахований під час оформлення, зберігається разом із замовленням і більше не змінюється. У розділі Sales > Orders сторінка замовлення показує панель Envioclick shipping з полями Envioclick carrier, Estimated delivery і Envioclick rate ID (для актуального тарифу), Price source (Envioclick live rate, Fixed price per country, Fallback cost або Free shipping threshold) і Calculated price (excl. tax). Панель показується навіть після вимкнення способу.

В OpenCart 4 оформлення замовлення зберігає одне замовлення і оновлює його щоразу, коли покупець підтверджує знову. Збережений тариф тоді замінюється останнім тарифом оформлення. Якщо покупець переходить до іншого способу доставки, панель для цього замовлення більше не показується. Зміни замовлення в адмін-панелі не змінюють збережений тариф.

Якщо Carrier in the title увімкнено, перевізник є частиною назви способу доставки замовлення. Якщо вимкнено, до листа про нове замовлення та до сторінки замовлення в обліковому записі покупця додається рядок Shipping carrier: з перевізником актуального тарифу, поки розширення увімкнено. Створіть накладну у своєму обліковому записі Envioclick. У замовлень із фіксованою ціною немає перевізника Envioclick.

Ліцензійний ключ

Розширення працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Envioclick — перший блок на сторінці Extensions > Extensions > Shipping > VibeFox Envioclick > Edit, над налаштуваннями. Введіть ключ у поле License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої діє ліцензія, і ваш домен) та кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа і Remove key для видалення ключа з цього магазину. Нижче розташовані рядок Product: opencart-shipping-envioclick і посилання 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.

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

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

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

Envioclick не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і Enable Envioclick увімкнено. Перевірте Geo zone або Ignore shipping zones і Countries, обмеження ваги та Minimum order amount. Без актуального тарифу способу потрібна фіксована ціна для країни, рядок * All other countries або Fallback cost. Перевірте, що товари мають Requires Shipping, встановлений на Yes.

Актуальні тарифи не з'являються: прочитайте попередження в розділі General, потім увімкніть Debug log, перезавантажте оформлення замовлення і подивіться поле Log на сторінці розширення. Типові причини: немає курсу конвертації (валюта магазину не MXN і не COP), немає User-Agent (Мексика), немає поштового індексу або коду DANE відправлення, ще не введено поштовий індекс покупця (Мексика) чи місто (Колумбія), напрямок поза країною API або немає перевізника для маршруту.

Навіщо курс конвертації? Envioclick повертає ціни лише в мексиканських або колумбійських песо. Розширення ніколи не показує суму в песо як суму в іншій валюті.

Колумбія: місто не розпізнається: перевірте, що покупець вибирає департамент як регіон адреси і правильно вводить назву муніципалітету. Також працює 8-значний код DANE, введений як поштовий індекс.

Податок на доставку стягується двічі: розрахунки Envioclick уже включають податки перевізників. Встановіть Tax class на No tax.

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

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

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

Видалення

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

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

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