VibeFox Sameday Easybox for PrestaShop — Допомога

Вимоги

PrestaShop: 8.0–9.x.

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

Ім'я користувача та пароль API Sameday: доступ до API входить до бізнес-облікового запису Sameday у Румунії, Угорщині або Болгарії. Запитайте свого менеджера облікового запису Sameday або команду інтеграції Sameday. Зазвичай дані такі самі, як для порталу eAWB (eawb.sameday.ro, .hu або .bg). Для демо-API Sameday надає окремі тестові дані. Без імені користувача та пароля API перевізник не пропонується, бо покупець не зможе обрати локер.

Округи у формі адреси: для розрахунку Sameday потрібен округ адреси доставки. За замовчуванням у PrestaShop немає округів для Румунії, Угорщини та Болгарії. Модуль може додати їх за вас (див. розділ Lockers easybox нижче). Без них ціни беруться з вашої таблиці або запасної вартості.

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

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

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

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

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

4. Введіть API username і API password Sameday, оберіть Sameday country і натисніть Save. Сторінка має показувати «Підключено до Sameday ... локери easybox». Pickup point і Easybox service заповнюються з вашого облікового запису.

5. Встановіть ціни: Exchange rate of the estimate, якщо валюта вашого магазину відрізняється від валюти Sameday, і рядок Country prices (наприклад * Default) або Fallback cost.

6. Якщо сторінка повідомляє, що в магазині немає округів для вашої країни Sameday, натисніть Add counties у розділі Lockers easybox.

Під час встановлення модуль створює перевізника Sameday easybox із текстом строку доставки Delivery to a Sameday easybox locker. Його призначено всім групам клієнтів і зоні Румунії. Зони, групи клієнтів, строк доставки та логотип можна змінити в Shipping > Carriers. Не встановлюйте там ціни: ціна завжди береться з модуля.

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

Усі налаштування розміщені на сторінці Configure модуля, у шести розділах. Кнопка Save будь-якого розділу зберігає всю сторінку.

Над налаштуваннями сторінка показує стан підключення: хост Sameday, кількість локерів easybox і коли оновлено список, або що Sameday відхилив ім'я користувача чи пароль. Також перелічено проблеми конфігурації, наприклад відсутність облікових даних, ціни, курсу для розрахунку, округів, одиниці ваги магазину, яку модуль не знає, або що перевізника не знайдено.

Усі ціни та обмеження приймають кому або крапку як десятковий роздільник (4,99 або 4.99). Некоректне чи від'ємне число не зберігається: попередження називає поле, і залишається попереднє значення.

Загальні

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

Name: назва способу доставки, яку бачить покупець (назва перевізника). За замовчуванням: Sameday easybox.

Tax status: None означає, що ціна остаточна. Taxable з податковим правилом змушує PrestaShop додати до ціни податок на доставку.

Обліковий запис Sameday (API)

Під час збереження модуль входить до Sameday і завантажує ваші послуги, пункти приймання та список локерів easybox. Список оновлюється щодня.

API username: ваше ім'я користувача API Sameday.

API password: ваш пароль API Sameday. Його більше не показують: залиште поле порожнім, щоб зберегти поточний. Очищення імені користувача також видаляє пароль. Якщо Sameday його відхиляє, повторна спроба не робиться 10 хвилин.

Sameday country: країна вашого облікового запису Sameday: Romania (api.sameday.ro) (за замовчуванням), Hungary (api.sameday.hu) або Bulgaria (api.sameday.bg). Її локери пропонуються, а перевізник показується лише для цієї країни призначення. Під час зміни країни перевізник також прив'язується до зони нової країни.

Test mode: використовує демо-API Sameday (sameday-api.demo.zitec.com) з демо-обліковими даними.

Ціни

Порядок застосування: спочатку розрахунок Sameday (якщо задано Pickup point і Easybox service), потім таблиця цін за країнами, потім запасна вартість. Ціни таблиці вводяться у валюті магазину за замовчуванням. Покупці, які платять в іншій валюті, бачать перераховану ціну.

Pickup point: ваш пункт приймання Sameday, звідки Sameday забирає посилки. Після успішного входу це список пунктів приймання вашого облікового запису, і пункт за замовчуванням обирається автоматично. Потрібен для розрахунку Sameday. Оберіть - not set (price table only) -, щоб використовувати лише таблицю цін.

Easybox service: послуга Sameday для доставки в easybox, зазвичай «Locker NextDay» (код LN), яка обирається автоматично. Потрібна для розрахунку Sameday.

Exchange rate of the estimate: Sameday рахує у валюті вашої країни Sameday: RON, HUF або BGN (EUR для болгарських магазинів, що продають в євро). Якщо ваш магазин продає в іншій валюті, введіть вартість 1 одиниці валюти Sameday у валюті магазину, наприклад 0.20. Курс має бути більшим за 0. Без нього розрахунок Sameday не використовується, і застосовується таблиця цін. Лев і євро автоматично перераховуються за фіксованим курсом.

Table price: Per order стягує ціну один раз. Per item (price x quantity) множить її на кількість товарів. Це стосується ціни таблиці та запасної вартості. Розрахунок Sameday завжди на всю посилку.

Country prices: ціна для кожної країни призначення та ваги посилки. Натисніть + Add country, щоб додати рядок, і значок кошика, щоб його видалити. Кожен рядок має стовпець Price і стовпці ваги: XS до 1 кг, S 1–2 кг, M 2–3 кг, L 3–5 кг і XL понад 5 кг. Стовпець ваги, що залишився 0, використовує стовпець Price. Рядок * Default використовується для країн без власного рядка. Новий рядок створюється як * Default із усіма цінами 0, що означає безкоштовну доставку. Оберіть країну та введіть ціни перед збереженням або видаліть рядок. Якщо одна країна вказана у двох рядках, під час збереження лишається лише перший, і про це виводиться попередження. Якщо клітинка — не число, таблиця не зберігається.

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

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

Доступність

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

Maximum weight (kg): посилки важчі за це не отримують доставку в easybox. За замовчуванням: 30. Перевірте обмеження вашого договору з Sameday і розміри осередків easybox. Порожнє або 0 означає без обмеження. Мінімальна вага більша за максимальну не зберігається: попередження про це виводиться, і залишаються попередні значення.

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

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

Countries (ignore zones mode): країни призначення для цього режиму. Країни, відмінні від країни Sameday, пропускаються, і сторінка попереджає про них. Це поле використовується лише коли Ignore shipping zones увімкнено.

Lockers easybox

Locker list: показує, скільки локерів easybox у скількох містах завантажено і коли. Refresh the locker list now завантажує список знову. Список оновлюється під час збереження налаштувань і, якщо він старший за добу, після запиту оформлення замовлення. Для сталого щоденного оновлення викликайте раз на день Cron URL, який показано тут, із cron-завдання вашого сервера. URL містить секретний токен. Без токена він відповідає помилкою і не звертається до Sameday.

Counties: для розрахунку Sameday потрібен округ адреси. Якщо в PrestaShop немає округів (states) для вашої країни Sameday, натисніть Add counties. Модуль додасть округи Румунії, Угорщини чи Болгарії та поле округу до форми адреси цієї країни. Округи, які вже є, не додаються повторно. Коли вони на місці, сторінка показує їх кількість.

Додатково

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

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

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

Коли магазин розраховує доставку для кошика, PrestaShop запитує у модуля ціну перевізника Sameday easybox. Модуль перевіряє умови: країна доставки вашого облікового запису Sameday, дані API та придатний список локерів, країни з Ignore shipping zones, вага кошика та мінімальна сума кошика. Товари, що не потребують доставки (віртуальні товари), не враховуються. Якщо застосовується безкоштовна доставка, покупець бачить перевізника без вартості.

Інакше модуль запитує у Sameday розрахунок, коли покупець указав місто та округ. Він надсилає ваш пункт приймання та послугу, вагу посилки, а також вулицю, місто, округ і поштовий індекс покупця. Ім'я, e-mail і телефон не надсилаються. Бухарест надсилається як «Sector 1», як в офіційному плагіні Sameday. Розрахунок перераховується у валюту магазину. Якщо розрахунку немає (не налаштовано, ще немає міста чи округу, помилка, немає курсу), ціна береться з таблиці країни, потім запасна вартість. Якщо ціни немає, перевізник приховується.

Проблеми Sameday ніколи не зупиняють оформлення замовлення. Розрахунок кешується на 1 годину. Помилка кешується на 10 хвилин. Після тайм-ауту або помилки сервера розрахунок не запитується 5 хвилин. Запити припиняються через 15 секунд. Список локерів під час оформлення читається з вашого сервера, а не з Sameday.

Перевізник працює на етапі доставки в темі Classic (PrestaShop 8) і темі Hummingbird (PrestaShop 9).

Модуль не створює AWB (відправлення), не друкує етикетки, не відстежує посилки й не обробляє накладений платіж. У нього немає кур'єрської доставки додому та віджета карти Sameday. Створіть AWB у порталі Sameday eAWB або в звичному інструменті, вказавши ID локера, який показано в замовленні.

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

Коли покупець обирає перевізника, під ним з'являється блок easybox locker з двома списками: - Select city - і - Select easybox locker -. Місто адреси доставки попередньо обирається, якщо там є локери. Кожен локер показує назву та адресу. Вибір одразу зберігається в кошику, тож він лишається, коли етап доставки оновлюється або сторінка перезавантажується.

Локер обов'язковий. Без нього покупець не може продовжити і бачить «Будь ласка, оберіть локер easybox Sameday.» Коли покупець натискає Continue, сервер перевіряє, що обраний локер є у списку. Підроблений або видалений ID локера відхиляється з повідомленням «Обраний локер easybox більше недоступний. Будь ласка, оберіть інший локер easybox.» Якщо список не вдається завантажити, покупець бачить «Не вдалося завантажити локери easybox. Спробуйте ще раз трохи пізніше або оберіть інший спосіб доставки.» Назва та адреса, що зберігаються із замовленням, беруться зі списку, а не з браузера. Після оформлення замовлення його локер більше не змінюється.

Сторінка замовлення в панелі адміністратора: блок Sameday easybox locker з назвою, адресою та Locker ID для AWB Sameday. Якщо в замовленні easybox немає локера, блок показує «Для цього замовлення локер easybox не вибрано.»

Сторінки підтвердження та історії замовлень: Sameday easybox locker: з назвою та адресою.

Листи про замовлення: назва та адреса локера додаються до перевізника в листі з підтвердженням замовлення. Лист про нове замовлення магазину (модуль Mail alerts) також містить Locker ID.

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

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

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

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

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

Sameday easybox не з'являється під час оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, ім'я користувача та пароль API введено, сторінка налаштувань показує «Підключено до Sameday», а країна призначення — це країна вашого облікового запису Sameday. Перевірте, що доступна ціна (розрахунок Sameday, рядок країни, рядок * Default або Fallback cost), а також обмеження за вагою та сумою. У Shipping > Carriers перевірте, що перевізник охоплює зону країни покупця та його групу, або увімкніть Ignore shipping zones. Товари також можуть бути обмежені певними перевізниками на сторінці товару. Увімкніть Debug log, щоб побачити причину в полі Log.

Sameday відхилив ім'я користувача або пароль API: перевірте їх і збережіть знову. Демо-дані працюють лише з увімкненим Test mode, робочі — лише з вимкненим. До того часу пропонується збережений список локерів, якщо він є, а розрахунок Sameday не використовується.

Ціна береться з моєї таблиці, а не з Sameday: для розрахунку потрібні Pickup point, Easybox service, округи у формі адреси та, якщо валюта магазину відрізняється від валюти Sameday, Exchange rate of the estimate. Розрахунок запитується лише після того, як покупець указав місто та округ. Коли Sameday недоступний або повертає помилку, використовується таблиця чи запасна вартість; причина — у журналі.

Список локерів застарів або відсутній: натисніть Refresh the locker list now або збережіть налаштування. Якщо оновлення не вдалося, використовується попередній список, і статус це показує. Якщо магазин у режимі обслуговування, cron URL блокується, як і весь магазин, якщо тільки IP сервера cron не дозволено.

Доставка безкоштовна помилково: перевірте Free shipping from і рядки Country prices з Price 0, особливо рядок * Default, доданий через + Add country і не заповнений.

Обмеження ваги або стовпці ваги не збігаються: якщо сторінка попереджає, що одиниця ваги магазину невідома, установіть kg, g, lb або oz в International > Localization (Local units).

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

Видалення

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

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