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 есть округа Румынии и Болгарии, но в 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 URL выглядит так: 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.