VibeFox SMSA Express for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Прайс-лист SMSA Express: цены для таблицы берутся из вашей учётной записи SMSA или у отдела продаж SMSA. Вводите их в валюте магазина по умолчанию. Если прайс-лист в SAR, AED или другой валюте, сначала пересчитайте его.

passKey SMSA (только для тарифов в реальном времени): тарифы в реальном времени используют веб-службу SMSA (SECOM, операция getShipCharges). SMSA выдаёт passKey по запросу: обратитесь к своему менеджеру по учётной записи SMSA или напишите на info@smsaexpress.com и попросите доступ к веб-службе SMSA, указав номер вашей учётной записи. passKey может отличаться от API-ключа портала электронной коммерции SMSA. У SMSA нет тестового сервера (sandbox) для этой службы.

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

Установка

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

2. По окончании загрузки нажмите Configure или позже найдите VibeFox SMSA Express в списке модулей и нажмите Configure.

3. Введите лицензионный ключ VibeFox в поле License key в блоке лицензии вверху страницы настроек и нажмите Activate (см. Лицензионный ключ).

4. Введите цены SMSA Express в таблицу цен и нажмите Save.

5. По желанию: в разделе Live rates (API) включите Live charges, введите passKey SMSA, город и страну отправления и, если валюта магазина по умолчанию не SAR, курс обмена.

При установке модуль создаёт перевозчика SMSA Express с текстом срока доставки SMSA Express courier. Перевозчик назначается всем зонам и всем группам клиентов. Зоны, группы клиентов, срок доставки, логотип и ограничения по размеру можно изменить в Shipping > Carriers. Цены там не задавайте: цена всегда берётся из модуля.

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox SMSA Express > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Каждое сохранение также очищает кэш тарифов SMSA. Значение, которое не является числом, отрицательное число, курс обмена 0, код валюты не из 3 букв или Minimum weight больше Maximum weight отклоняются с ошибкой, и ничего не сохраняется, пока вы не исправите значение.

Когда тарифы в реальном времени включены, предупреждения над настройками сообщают об отсутствующем passKey, городе отправления или курсе обмена либо о пустой таблице цен. Также появляется предупреждение, если модуль не знает единицу веса магазина (тогда веса товаров читаются как кг). Укажите kg, g, lb или oz в International > Localization (Local units).

Общие

Enable SMSA Express: включает или выключает перевозчика во всех зонах сразу. Это тот же переключатель, что и статус перевозчика в Shipping > Carriers.

Method title: название перевозчика, которое показывается в корзине и при оформлении заказа. По умолчанию: SMSA Express. Обязательно, до 64 символов.

Tax: налоговое правило перевозчика или No tax. Выберите No tax, если ваши цены (таблица и тарифы SMSA) уже включают налог, например НДС Саудовской Аравии.

Тарифы в реальном времени (API) (необязательно; если SMSA не возвращает стоимость, используется таблица цен)

Live charges: получать стоимость доставки от SMSA Express. По умолчанию: выключено.

SMSA passKey: ключ веб-службы SMSA (SECOM). После сохранения поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить. Отметьте Remove the saved passKey, чтобы удалить его. Если в журнале появляется "Invalid Passkey", этот сервис не принимает ключ. Запросите у SMSA passKey для веб-службы.

Ship-from city: город, из которого отправляются ваши посылки, написанный так, как его пишет SMSA, например Riyadh, Jeddah или Dammam. Оставьте поле пустым, чтобы использовать город магазина из Shop Parameters > Contact > Stores.

Ship-from country: страна, из которой отправляются ваши посылки. По умолчанию это страна вашего магазина.

Shipment type: передаётся в SMSA как тип отправления. DLV (по умолчанию) — стандартная доставка. Меняйте его, только если SMSA сообщил вам другой код.

Currency of SMSA charges: SMSA возвращает каждую стоимость с кодом валюты, обычно SAR (по умолчанию). Стоимость в любой валюте, кроме этой и валюты магазина по умолчанию, не используется.

Exchange rate: цена 1 единицы валюты SMSA в валюте магазина по умолчанию, например 0.27. Не нужен, если обе валюты совпадают. Без него стоимость в другой валюте не используется, и применяется таблица цен. Разделителем дробной части принимаются и точка, и запятая.

Цены (ваш прайс-лист SMSA Express в валюте магазина по умолчанию; используется, когда тарифы в реальном времени выключены, и как запасной вариант, когда SMSA не возвращает стоимость)

Price table: одна строка на страну назначения. Нажмите Add country, чтобы добавить строку, и значок корзины, чтобы удалить её. Строка * Default (all other countries) применяется к странам без собственной строки. Каждая строка содержит базовую цену и колонки веса: XS до 1 кг, S до 2 кг, M до 3 кг, L до 5 кг и XL свыше 5 кг. Пустая или нулевая колонка веса использует базовую цену. Базовая цена 0 означает бесплатную доставку. Строки без единой цены не сохраняются. Если у страны две строки, используется первая. Принимаются оба варианта: "9.99" и "9,99".

Price for countries not in the table: используется, когда в таблице нет строки для страны назначения (и строки *) или в строке нет цены для этого веса. Оставьте поле пустым, чтобы в этом случае скрыть перевозчика.

Price applies: способ расчёта цены.

Веса товаров пересчитываются из единицы измерения вашего магазина в килограммы.

Условия

Minimum weight: скрыть перевозчика, когда корзина весит меньше, в кг. 0 — без ограничения.

Maximum weight: скрыть перевозчика, когда корзина весит больше, в кг. По умолчанию: 30. 0 или пустое поле — без ограничения.

Minimum order amount: показывать перевозчика, только когда промежуточная сумма корзины (после скидок, без налогов) достигает этой суммы. Оставьте поле пустым, чтобы показывать его всегда.

Free shipping from: промежуточная сумма корзины (после скидок, без налогов), начиная с которой доставка SMSA Express бесплатна. Когда корзина её достигает, цена равна 0 и запрос в SMSA не отправляется. Оставьте поле пустым, чтобы никогда не предлагать бесплатную доставку.

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

Обычно перевозчик предлагается в зонах, к которым он привязан в Shipping > Carriers.

Ignore shipping zones: предлагать SMSA Express для стран ниже, независимо от подходящей зоны. Пока это включено, перевозчик добавляется во все зоны, в том числе созданные позже. Выключение удаляет добавленные таким образом зоны.

Countries: страны назначения для этого режима. Оставьте поле пустым, чтобы использовать все активные страны магазина. Это поле используется только при включённом Ignore shipping zones.

Дополнительно

Debug log: записывает расчёты тарифов в logs/vfd_smsa_debug.log.php в папке модуля. Файл нельзя открыть через веб. Адреса клиентов и ключи не записываются. Ошибки тарифов в реальном времени всегда записываются, даже если эта опция выключена. Выключите журнал, когда закончите.

Log: показывает размер и последние записи журнала отладки. Нажмите Clear log, чтобы очистить его.

Remove data on uninstall: если включено, при удалении модуля удаляются настройки SMSA Express, перевозчик и журнал. Если выключено, всё сохраняется для повторной установки. Кэшированные тарифы всегда удаляются.

Как это работает при оформлении заказа

На шаге доставки PrestaShop запрашивает у модуля цену SMSA Express. Учитываются только физические товары: виртуальные товары не добавляют вес и не входят в сумму заказа. Модуль сначала проверяет условия: страны из Ignore shipping zones (если включено), вес корзины и минимальную сумму заказа. Если действует бесплатная доставка, цена равна 0 и запрос в SMSA не отправляется.

При включённых тарифах в реальном времени модуль отправляет в SMSA ваш город и страну отправления, город и страну покупателя, тип отправления, вес посылки в кг и сумму наложенного платежа 0. SMSA отвечает стоимостью и её валютой. Модуль пересчитывает её в валюту магазина по умолчанию, а затем цена показывается в валюте корзины покупателя. Тариф в реальном времени запрашивается только после того, как покупатель указал адрес доставки с городом.

Каждый тариф кэшируется на час, поэтому та же корзина не вызывает новый запрос. Неудачный запрос кэшируется на 5 минут. После тайм-аута или ошибки сервера SMSA не запрашивается ещё 2 минуты. После отклонённого ключа — ещё 5 минут. Так оформление заказа никогда не ждёт неработающую службу при каждом обновлении. Тайм-аут запроса — 12 секунд.

Если SMSA не возвращает пригодной стоимости (нет passKey, город ещё не введён, нет веса товаров, неверный ключ, тайм-аут, ошибка, нет обслуживания в город или неизвестная валюта), используется таблица цен. Если таблица и Price for countries not in the table не дают цену, перевозчик скрывается. Покупатель никогда не видит ошибку. Причина записывается в журнал.

Если вы редактируете перевозчика в Shipping > Carriers после того, как у него появились заказы, PrestaShop сохраняет его как новую версию перевозчика. Модуль автоматически переходит на новую версию.

Модуль только рассчитывает стоимость доставки. Он не создаёт отправления SMSA, не печатает этикетки AWB, не оформляет возвраты и не отслеживает посылки. Наложенный платёж и его комиссия не входят в тариф в реальном времени. Выбора пункта выдачи SMSA нет: перевозчик доставляет до двери.

Лицензионный ключ

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

Без действующего ключа перевозчик SMSA Express не показывается покупателям при оформлении заказа и тариф не рассчитывается. Витрина PrestaShop не знает, что вы вошли в бэк-офис, поэтому перевозчик скрыт и для вас: вы можете настроить модуль до покупки ключа, но не можете проверить его при оформлении заказа. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются.

Когда лицензия истекает, модуль продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется снова, пока вы работаете в бэк-офисе: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Cron-задача не нужна. Удаление или сброс модуля всегда удаляет лицензионный ключ и статус лицензии.

Устранение неполадок

SMSA Express не появляется при оформлении заказа: проверьте, что лицензия активна и Enable SMSA Express включено. В Shipping > Carriers проверьте, что перевозчик охватывает зону страны покупателя и группу покупателя (или что Ignore shipping zones включено и страна разрешена). Проверьте ограничения по весу и Minimum order amount. Убедитесь, что у страны или * есть цена, или что задано Price for countries not in the table. Кроме того, товары могут быть ограничены определёнными перевозчиками на странице товара.

Покупатели видят цену из таблицы вместо тарифа SMSA: SMSA нужен город покупателя, поэтому до его ввода показывается цена из таблицы. Таблица также используется, когда SMSA не отвечает, отклоняет ключ или город либо возвращает стоимость в валюте без курса обмена. Причину смотрите в поле Log на странице модуля.

"Invalid Passkey" в журнале: ключ не принимается веб-службой SMSA. Запросите у SMSA passKey для веб-службы.

Город покупателя не принимается: SMSA использует собственное написание городов. Проверьте город в адресе доставки и Ship-from city.

Настройки не сохраняются, и появляется ошибка: в числовом поле текст или отрицательное значение, курс обмена равен 0, код валюты не из 3 букв или Minimum weight больше Maximum weight. Исправьте значение, указанное в сообщении, и снова нажмите Save.

Налог на доставку взимается дважды: ваш прайс-лист или тарифы SMSA могут уже включать НДС. Установите Tax в No tax.

Тарифы выглядят устаревшими после изменения: нажмите Save на странице модуля. Это очистит кэш тарифов SMSA.

На странице написано, что перевозчик SMSA Express не найден: перевозчик был удалён в Shipping > Carriers. Сбросьте модуль в Modules > Module Manager, чтобы создать его снова.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox SMSA Express и выберите Uninstall. Лицензионный ключ и статус лицензии всегда удаляются. Кэшированные тарифы всегда удаляются. Если Remove data on uninstall включено, перевозчик удаляется (заказы сохраняют свою историю), а настройки и журнал удаляются. Если выключено, перевозчик только отключается, и все настройки сохраняются. При повторной установке модуля или сбросе перевозчик возвращает тот статус, который был до этого.

SMSA Express — товарный знак его владельца. Этот модуль не аффилирован с SMSA Express и не одобрен ею.