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

Вимоги

PrestaShop: 8.0–9.x.

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

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

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

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

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

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

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

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

4. Введіть ключ API, виберіть країну API, введіть User-Agent (Мексика), поштовий індекс або код DANE відправлення та адресу відправлення. Якщо валюта за замовчуванням вашого магазину не MXN і не COP, введіть курс конвертації валют. Для Колумбії натисніть Add Colombian departments, якщо сторінка це пропонує.

5. За потреби додайте фіксовані ціни за країнами та запасну вартість, а потім натисніть Save.

Під час встановлення модуль створює перевізника Envioclick Shipping з текстом терміну доставки Courier delivery by the best Envioclick carrier. Перевізник призначається всім зонам і всім групам клієнтів. Зони, групи клієнтів, термін доставки, логотип і обмеження розміру можна змінити в Shipping > Carriers. Ціни там не встановлюйте: ціна завжди береться з модуля.

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

Усі параметри розташовані на сторінці модуля: Modules > Module Manager > VibeFox Envioclick > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Кожне збереження також очищає кешовані тарифи Envioclick. Числові поля приймають як крапку, так і кому як десятковий роздільник.

Коли задано ключ API, на початку сторінки з'являються попередження, якщо тарифи в реальному часі не можуть працювати: немає курсу конвертації для валюти магазину, відмінної від MXN або COP, немає User-Agent для Мексики, немає поштового індексу чи коду DANE відправлення або немає адреси відправлення для Колумбії. Сторінка також попереджає, якщо одиниця ваги або розмірів вашого магазину не розпізнається; встановіть kg, g, lb або oz та cm, mm, m або in в International > Localization (Local units). Під час збереження модуль перевіряє, що Method title є коректною назвою перевізника, що числові поля містять невід'ємні числа, що Currency conversion rate більше 0, що Minimum weight не більше за Maximum weight, і що код відправлення має 5 цифр для Мексики або 8 цифр (чи 5-значний код муніципалітету) для Колумбії. Якщо перевірка не пройдена, показується помилка і нічого не зберігається.

Загальні

Зони, групи клієнтів і обмеження розміру перевізника задаються в Shipping > Carriers (або використовуйте Ignore shipping zones нижче). Налаштування цієї сторінки застосовуються до всіх зон.

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

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

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

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: показується лише тоді, коли ключ збережено. Виберіть Yes і збережіть, щоб видалити ключ; тоді використовуються лише фіксовані ціни. Ключ, введений у поле API key, замінює збережений.

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

Colombian departments: лише для Колумбії. PrestaShop за замовчуванням не містить колумбійських департаментів. Без них розпізнаються лише назви міст, які є унікальними в Колумбії; департамент дозволяє розрізняти муніципалітети з однаковими назвами. Кнопка Add Colombian departments додає 33 департаменти як регіони Колумбії (коди ISO ANT, DC тощо), вмикає «Contains states» для Колумбії та додає поле департаменту до колумбійської форми адреси. Департаменти, які вже існують, повторно не додаються. Коли все готово, поле показує, скільки департаментів мають колумбійські адреси.

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

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

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

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

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

Використовується для тарифів у реальному часі. Порожні поля беруться з адреси магазину в Shop Parameters > Contact > Stores, якщо магазин знаходиться в країні API.

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

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

Фіксовані ціни

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

Price per country: таблиця з 2-літерних кодів країн і цін у валюті магазину за замовчуванням, без податків. Натисніть Add row, щоб додати країну, і значок кошика, щоб видалити її. Використовуйте * як код країни для всіх країн без власного рядка.

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

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

Умови

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

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

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

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

Tax: правило податку перевізника або No tax. Тарифи Envioclick уже містять податки перевізників, тому виберіть No tax, щоб не стягувати податок із доставки двічі.

Доступність без зон доставки

Зазвичай перевізник пропонується в зонах, призначених йому в Shipping > Carriers.

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

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

Додатково

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

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

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

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

На кроці доставки PrestaShop запитує в модуля ціну Envioclick. Враховуються лише фізичні товари: віртуальні товари не додають ваги і не входять до суми замовлення. Модуль спершу перевіряє умови: країни з Ignore shipping zones, вагу кошика та мінімальну суму замовлення. Якщо діє безкоштовна доставка, ціна дорівнює 0 і запит до Envioclick не надсилається.

Якщо ключ API задано і напрямок знаходиться в країні API, модуль запитує тарифи в Envioclick. У Мексиці запит надсилається, коли покупець ввів 5-значний поштовий індекс. У Колумбії — коли розпізнано департамент і муніципалітет (наголоси та регістр не мають значення). Модуль обирає найдешевший або найшвидший тариф, який не є накладеним платежем, і перераховує його у валюту магазину за замовчуванням. Потім ціна показується у валюті кошика покупця.

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

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

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

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

Замовлення

Коли замовлення оформлюється з перевізником Envioclick, тариф, розрахований для його кошика, зберігається разом із замовленням і більше не змінюється. На сторінці замовлення в адмін-панелі показується блок 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). Для тарифу в реальному часі на сторінці замовлення покупця показується Shipping carrier. Накладну створіть у своєму обліковому записі Envioclick.

У замовлень із фіксованою ціною немає перевізника Envioclick.

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

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

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

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

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

Envioclick не з'являється під час оформлення: перевірте, що ліцензія активна і ввімкнено Enable Envioclick. У Shipping > Carriers перевірте, що перевізник охоплює зону країни покупця та групу покупця, або ввімкніть Ignore shipping zones і перевірте Countries. Перевірте обмеження ваги та Minimum order amount. Без тарифу в реальному часі перевізнику потрібна фіксована ціна для країни, рядок * або Fallback cost. Товари також можуть бути обмежені певними перевізниками на сторінці товару.

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

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

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

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

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

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

Видалення

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

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