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. Без него расчёт не используется и применяется таблица цен. Лев и евро пересчитываются по фиксированному курсу автоматически.

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-задачи вашего сервера Cron URL, которая показана здесь. 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.