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

Вимоги

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

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

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

Країна та округи: країна вашого облікового запису Sameday має бути ввімкнена в System > Localisation > Countries. Для розрахунку Sameday потрібен округ адреси доставки (поле Region / State). В OpenCart 3 є округи Румунії та Болгарії, але немає округів Угорщини (в OpenCart 4.1 вони є). Розширення може додати їх за вас (див. постамати easybox нижче). Без них ціни беруться з вашої таблиці або запасної вартості.

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

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

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

OpenCart 3

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

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

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

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

5. Введіть API username та API password Sameday, оберіть Sameday country, увімкніть Enable/Disable і натисніть Save. Сторінка має показати "Connected to Sameday ... easybox lockers". Pickup point і Easybox service заповнюються з вашого облікового запису.

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

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

OpenCart 4

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

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

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

4. Введіть ліцензійний ключ і налаштування так само, як у кроках 4–7 для OpenCart 3. Сторінка налаштувань і її поля однакові в обох версіях. Лише URL cron відрізняється (див. постамати easybox).

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

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

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

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

Деякі помилки зупиняють збереження, і тоді нічого не зберігається: Enter a valid name (1-64 characters, without < > ; = # { })., Sort order must be a whole number., недійсний податковий клас або геозона. Інші проблеми стосуються лише одного значення: усі ціни та обмеження приймають кому або крапку як десятковий роздільник (4,99 або 4.99), а недійсне чи від'ємне число не зберігається. Попередження вказує поле, і залишається попереднє значення.

Загальні

Enable/Disable: показує або приховує спосіб доставки під час оформлення замовлення. Це статус розширення в Extensions > Extensions > Shipping. За замовчуванням: вимкнено.

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

Tax class: --- None --- (за замовчуванням) означає, що ціна остаточна. З податковим класом OpenCart додає податок цього класу до ціни.

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

Обліковий запис 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 забирає посилки. Після успішного входу це список пунктів відправлення вашого облікового запису, і пункт за замовчуванням обирається автоматично. До цього це поле для ID. Потрібне для розрахунку 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. Без нього розрахунок не використовується, і діє таблиця цін. Лев та євро автоматично перераховуються за фіксованим курсом.

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, що означає безкоштовну доставку. Оберіть країну та введіть ціни перед збереженням або видаліть рядок. Якщо та сама країна є в двох рядках, під час збереження лишається лише перша, і з'являється попередження про це. Якщо комірка не є числом 0 або більше, таблиця не зберігається.

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

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

Доступність

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

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

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

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

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

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

Постамати easybox

Locker list: показує, скільки постаматів easybox у скількох містах завантажено і коли. Refresh the locker list now завантажує список знову. Список оновлюється під час збереження налаштувань, а якщо він старший за добу, то після запиту оформлення замовлення (не частіше ніж раз на годину). Для фіксованого щоденного оновлення викликайте раз на день URL, який показано тут, через задачу cron вашого сервера. В OpenCart 3 він виглядає як https://your-store/index.php?route=extension/shipping/vfd_sameday_easybox/cron&token=(token), в OpenCart 4 як https://your-store/index.php?route=extension/vfd_sameday_easybox/shipping/vfd_sameday_easybox.cron&token=(token). Скопіюйте URL точно так, як його показують налаштування. URL містить секретний токен. Без правильного токена він відповідає помилкою і не звертається до Sameday. Він також нічого не робить, поки спосіб вимкнено.

Counties: показує, скільки округів має OpenCart для вашої країни Sameday. Якщо немає жодного, натисніть Add counties. Розширення додасть округи цієї країни до System > Localisation > Zones, і поле Region / State форми адреси почне їх пропонувати. Округи, які вже існують, повторно не додаються. В OpenCart 4.1 округи всіх трьох країн уже є, тому кнопка там не потрібна.

Додатково

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

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

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

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

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

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

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

Коли OpenCart показує способи доставки, він запитує у розширення ціну доставки easybox від Sameday. Розширення перевіряє геозону (або країни з Ignore shipping zones), країну доставки вашого облікового запису Sameday, облікові дані API та придатний список постаматів, вагу кошика і мінімальну суму кошика. Враховуються лише товари з Requires Shipping, встановленим у Yes. Сума кошика — це ціна таких товарів без податку, після знижки за купоном. Якщо застосовується безкоштовна доставка, покупець бачить спосіб без вартості.

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

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

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

На OpenCart 4 покупець натискає Choose у блоці способу доставки на сторінці оформлення і вибирає Sameday easybox у вікні Shipping method options. Ціни такі самі, як в OpenCart 3.

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

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

Постамат обов'язковий. Без нього покупець не може продовжити і бачить "Please choose a Sameday easybox locker.". Коли покупець натискає Continue, сервер перевіряє, що обраний постамат є у списку. Підроблений або видалений ID постамата відхиляється з повідомленням "The selected easybox locker is not available any more. Please choose another easybox locker.". Якщо список не вдалося завантажити, покупець бачить "The easybox lockers could not be loaded. Please try again in a moment or choose another shipping method.". Назва та адреса, що зберігаються із замовленням, беруться зі списку, а не з браузера.

Сторінки замовлення, листи та рахунок-фактура: постамат додається до способу доставки замовлення, наприклад «Sameday easybox: назва - адреса» (спочатку назва способу, потім постамат). Покупець бачить це в підтвердженні замовлення, в історії замовлень і в листах про замовлення, а ви бачите це в рахунку-фактурі.

Сторінка замовлення в адмінці: в Sales > Orders на сторінці замовлення є панель Sameday easybox locker з назвою, адресою та Locker ID для AWB Sameday. Якщо в замовленні easybox немає постамата, панель повідомляє "No easybox locker was selected for this order.". Панель показується і тоді, коли спосіб вимкнено.

На OpenCart 4 блок easybox locker з'являється у вікні Shipping method options, під варіантом Sameday easybox. Список міст щоразу завантажується знову, коли вікно відкривається, бо адреса може змінитися під час оформлення замовлення на одній сторінці. Кнопка Continue у вікні не переходить далі без дійсного постамата, з тими самими повідомленнями. OpenCart 4 зберігає одне замовлення для оформлення і оновлює його щоразу, коли покупець підтверджує знову, і постамат замовлення оновлюється разом із ним. Панель на сторінці замовлення в адмінці показується над розділом History.

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

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

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

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

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

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

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

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

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

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

Обмеження ваги або стовпці ваги не збігаються: якщо сторінка попереджає, що немає вагового класу з одиницею "kg", додайте клас ваги в кілограмах у System > Localisation > Weight Classes.

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

Видалення

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

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

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