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

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

PHP: 8.0 или новее.

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

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

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

Установка

Загрузка представляет собой один zip-файл с пакетами для обеих версий OpenCart. Распакуйте его на своём компьютере. Он содержит README.txt, пакет для OpenCart 3 vfd_smsa_express-oc3-(version).ocmod.zip и пакет для OpenCart 4 vfd_smsa_express.ocmod.zip. Устанавливайте только пакет для своей версии OpenCart. Лицензионный ключ один и тот же для обеих версий.

OpenCart 3

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

2. Перейдите в Extensions > Extensions и выберите тип расширения Shipping. Найдите VibeFox SMSA Express и нажмите Install (зелёная кнопка +).

3. Нажмите Edit (кнопка с карандашом), чтобы открыть страницу настроек.

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

5. Введите цены SMSA Express в таблицу цен.

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

7. Включите Enable SMSA Express и нажмите Save.

OpenCart 4

1. В административной части перейдите в Extensions > Installer, нажмите Upload и выберите файл vfd_smsa_express.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.

2. Пакет появляется в списке установленных расширений на той же странице. Нажмите рядом с ним Install (зелёная кнопка +).

3. Перейдите в Extensions > Extensions и выберите тип расширения Shipping. Найдите VibeFox SMSA Express, нажмите Install (зелёная кнопка +), затем Edit (кнопка с карандашом).

4. Введите лицензионный ключ и настройки так же, как в шагах 4–7 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях.

После установки способ выключен, пока вы не включите Enable SMSA Express и не сохраните. Если вы установите расширение заново после удаления, сохранённые настройки SMSA Express будут снова использованы.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Shipping > VibeFox SMSA Express > Edit. Разделы перечислены слева. Одна кнопка Save сохраняет всю страницу без перезагрузки. Каждое сохранение также очищает кэш тарифов SMSA. Неверное название способа, значение, которое не является числом, отрицательное число, курс обмена 0, код валюты не из 3 букв, неверная цена в таблице, Minimum weight (kg) больше Maximum weight (kg) или порядок сортировки, который не является целым числом, отклоняются с ошибкой, и ничего не сохраняется, пока вы не исправите значение. Сохранять настройки могут только администраторы с правом изменения этого расширения.

Когда тарифы в реальном времени включены, предупреждения над настройками сообщают об отсутствующем passKey, городе отправки или курсе обмена, а также о пустой таблице цен. Предупреждение также появляется, если в магазине нет весовой единицы класса kg, а единица веса по умолчанию не известна расширению (вес товаров тогда считается в кг). Добавьте класс веса kg в System > Localisation > Weight Classes.

Общие

Настройки применяются ко всем гео-зонам. Вы можете ограничить способ гео-зоной в Conditions или списком стран с Ignore shipping zones.

Enable SMSA Express: показывает или скрывает SMSA Express на странице оформления заказа. По умолчанию: выключено.

Method title: название способа доставки, которое покупатель видит в корзине и на странице оформления заказа. По умолчанию: SMSA Express. Обязательное поле, не более 64 символов, без символов < > ; = # { }.

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

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

Live charges: получать стоимость доставки от SMSA Express. Когда выключено, при оформлении заказа ничего не отправляется в SMSA. По умолчанию: выключено.

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. Обязателен для тарифов в реальном времени: у OpenCart нет города магазина, поэтому он никогда не берётся из адреса магазина.

Ship-from country: страна, из которой отправляются ваши посылки. Первый вариант, Store country, использует страну вашего магазина из System > Settings > Store > Local. Это значение по умолчанию.

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

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

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

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

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

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

Price applies: как рассчитывается цена.

Веса товаров пересчитываются из их весового класса OpenCart в килограммы.

Условия

Minimum weight (kg): скрывать способ, когда корзина весит меньше. 0 означает без ограничения (по умолчанию).

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

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

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

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

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

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

Обычно способ предлагается для адресов гео-зоны, выбранной в Conditions.

Ignore shipping zones: предлагать SMSA Express для стран, указанных ниже, независимо от гео-зоны. Когда выключено, решает гео-зона, и список стран не используется.

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

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

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

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

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

Импорт / Экспорт

Export: нажмите Download JSON, чтобы сохранить настройки в файл JSON. passKey не экспортируется.

Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки, например в другом магазине. Значения проверяются так же, как при обычном сохранении. Сохранённый passKey остаётся.

Как это работает на странице оформления заказа

Когда OpenCart показывает способы доставки, он запрашивает у расширения цену SMSA Express. Если задана Geo zone (и Ignore shipping zones выключено) и адрес вне неё, SMSA Express не предлагается. Учитываются только товары с Requires Shipping в значении Yes: остальные не добавляют вес и не входят в сумму заказа. Затем расширение проверяет условия: страны из Ignore shipping zones (если включено), вес корзины и минимальную сумму заказа. Подарочные сертификаты, бонусные баллы и кредит магазина не учитываются. Если применяется бесплатная доставка, цена равна 0, и запрос в SMSA не отправляется.

Когда тарифы в реальном времени включены, расширение отправляет в SMSA город и страну отправки, город и страну покупателя, тип отправления, вес посылки в кг и сумму наложенного платежа 0. SMSA отвечает стоимостью и её валютой. Расширение пересчитывает её в валюту магазина по умолчанию и округляет до его знаков после запятой. Затем цена показывается в валюте покупателя с налогом выбранного Tax class. Тариф в реальном времени запрашивается только после того, как покупатель ввёл адрес доставки с городом.

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

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

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

В OpenCart 4 покупатель нажимает Choose в блоке способов доставки на странице оформления заказа и выбирает SMSA Express в окне Shipping method options. Способ работает так же, как в OpenCart 3.

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

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

Без активного ключа SMSA Express не показывается покупателям на странице оформления заказа, и тарифы не рассчитываются. Администратор, вошедший в административную часть в том же браузере, всё ещё видит способ в магазине с пометкой (unlicensed — visible to admins only), так что вы можете настроить и проверить расширение до покупки ключа. В OpenCart 4 этот предпросмотр недоступен: магазин не видит вход администратора, поэтому без активного ключа способ скрыт для всех. После того как вы один раз откроете страницу Edit, на Dashboard административной части появляется напоминание. Закройте его кнопкой ×, чтобы скрыть на 7 дней. Существующие заказы не затрагиваются.

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

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

SMSA Express не появляется на странице оформления заказа: проверьте, что лицензия активна и включено Enable SMSA Express. Проверьте Geo zone (или, при включённом Ignore shipping zones, Countries), ограничения по весу и Minimum order amount. Проверьте, что для страны или * указана цена, или задано Price for countries not in the table. Проверьте, что у товаров Requires Shipping установлено в Yes.

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

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

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

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

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

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

Страница показывает "Warning: You do not have permission to modify VibeFox SMSA Express!": ваша группа администраторов, возможно, может только просматривать настройки. Дайте группе право изменения для extension/shipping/vfd_smsa_express (OpenCart 3) или extension/vfd_smsa_express/shipping/vfd_smsa_express (OpenCart 4) в System > Users > User Groups.

Для разработчиков: адрес веб-сервиса SMSA можно заменить настройкой vfd_smsa_api_url (для тестов); на странице настроек для неё нет поля.

Удаление

Перейдите в Extensions > Extensions, выберите тип Shipping и нажмите Uninstall (красная кнопка −) рядом с VibeFox SMSA Express. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда сбрасывает Enable SMSA Express, Sort order, Tax class и Geo zone. Кэшированные тарифы всегда удаляются. Если Remove data on uninstall включено, настройки SMSA Express и журнал отладки также удаляются. Если выключено, остальные настройки сохраняются и используются снова при повторной установке расширения. Существующие заказы сохраняют свой способ доставки и стоимость.

Чтобы на OpenCart 4 удалить также файлы расширения, перейдите после удаления в Extensions > Installer, нажмите в списке установленных расширений рядом с VibeFox SMSA Express кнопку Uninstall (оранжевая кнопка −), а затем Delete (красная кнопка с корзиной), чтобы удалить загруженный пакет.

SMSA Express является товарным знаком его владельца. Это расширение не связано с SMSA Express и не одобрено SMSA Express.