VibeFox 99Minutos for OpenCart — Помощь

Требования

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

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

Ключ API 99minutos (только для проверки обслуживания): получите его у своего менеджера по работе с клиентами 99minutos или на портале разработчиков 99minutos (developers.99minutos.com). Тестовый и рабочий ключи различаются. Если вы используете только матрицу цен, ключ API не нужен.

Страны: 99minutos доставляет в Мексику, Колумбию, Чили и Перу. Страны, в которые вы отправляете, должны быть включены в разделе System > Localisation > Countries.

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

Установка

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

OpenCart 3

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

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

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

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

5. Заполните Price matrix (хотя бы одну строку, например «* Default») и при необходимости ключ API и режим проверки обслуживания (см. Конфигурация). Включите Enable 99Minutos и нажмите Save.

OpenCart 4

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

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

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

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

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

Конфигурация

Все настройки находятся на странице расширения: Extensions > Extensions > Shipping > VibeFox 99Minutos > Edit. Разделы перечислены слева. Одна кнопка Save сохраняет всю страницу без перезагрузки. Каждое сохранение также очищает кэшированные результаты проверки обслуживания. Если значение неверно, ничего не сохраняется, а страница показывает причину, например Enter a method title (1 to 64 characters)., сообщение о том, что поле должно быть числом не меньше 0, или о том, что Min weight (kg) не может быть больше Max weight (kg). После сохранения предупреждения над настройками сообщают, когда способ доставки не может работать с текущими настройками: матрица цен пуста, выбран режим проверки обслуживания без ключа API, в матрице есть строки для стран, которые 99minutos не обслуживает, или в магазине нет весовой единицы «kg», а единица веса не распознаётся расширением (тогда веса считаются в килограммах). Сохранять настройки могут только администраторы с правом изменения этого расширения.

Общие

Настройки действуют для всех географических зон. 99Minutos предлагается только для Мексики, Колумбии, Чили и Перу как стран назначения.

Enable 99Minutos: показывает или скрывает 99Minutos при оформлении заказа. По умолчанию: выключено.

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

Tax class: налоговый класс стоимости доставки или No tax (по умолчанию). С налоговым классом OpenCart добавляет налог к цене из матрицы.

Sort order: положение 99Minutos среди способов доставки при оформлении заказа. Целое число.

API 99minutos (проверка обслуживания) (необязательно)

API используется только для проверки, доставляет ли 99minutos по почтовому индексу покупателя. Цена всегда берётся из матрицы.

Coverage check: нужно ли проверять почтовый индекс и как.

При проверке обслуживания способ доставки появляется только после того, как покупатель введёт почтовый индекс. Результаты кэшируются: обслуживается — 6 часов, не обслуживается — 30 минут, ошибка API — 5 минут, но не дольше срока жизни кэша OpenCart (по умолчанию 1 час). В 99minutos отправляется только почтовый индекс, в верхнем регистре и только из букв и цифр.

API key: ваш ключ API 99minutos, который отправляется как токен Bearer на адрес проверки обслуживания 99minutos. Обязателен, когда проверка обслуживания включена. После сохранения поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить. Ключ сохраняется так, как введён; удаляются только пробелы по краям.

Remove the saved API key: показывается только тогда, когда ключ сохранён. Включите и нажмите Save, чтобы удалить ключ.

Environment: Sandbox (test) (по умолчанию) или Production. Тестовая и рабочая среды используют разные ключи API, поэтому выбирайте среду, которой соответствует ваш ключ.

Тарифы

Цены указываются в валюте магазина по умолчанию, без налога, и используются так, как введены. Итоговая цена показывается в валюте покупателя.

Price matrix: таблица стран назначения и цен. Нажмите Add country, чтобы добавить строку, и кнопку × , чтобы удалить её. В каждой строке есть Country (* Default, Мексика, Колумбия, Чили или Перу), Base price и цены для размеров XS (до 1 кг), S (до 2 кг), M (до 3 кг), L (до 5 кг) и XL (более 5 кг). Пустая или нулевая цена размера заменяется на Base price. Строка * Default применяется к странам без собственной строки. Если у страны несколько строк, используется первая. В качестве десятичного разделителя принимаются и точка, и запятая; пустые, некорректные или отрицательные цены сохраняются как 0. Пока в матрице нет хотя бы одной строки, способ доставки при оформлении заказа не показывается.

Calculation: Per order — size by the total cart weight (по умолчанию) задаёт одну цену по размеру посылки для всей корзины. Per item — each unit priced by its own weight оценивает каждую единицу по размеру её собственного веса и складывает цены.

Free shipping: включает бесплатную доставку от суммы заказа.

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

Ограничения

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

Max weight (kg): скрывает способ доставки, если корзина тяжелее. По умолчанию: 25. 0 означает без ограничения; пустое поле означает 25 кг.

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

Geo zone: предлагает 99Minutos только для адресов в этой географической зоне. All zones (по умолчанию) означает без ограничения. Географические зоны настраиваются в System > Localisation > Geo Zones.

Restrict countries: предлагает способ доставки только для стран, указанных ниже. Это дополнительный фильтр к Geo zone.

Countries: список стран 99minutos (Мексика, Колумбия, Чили, Перу). Используется только при включённом Restrict countries. Оставьте пустым, чтобы разрешить все страны 99minutos.

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

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

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

Remove data on uninstall: если включено, при удалении расширения удаляются настройки 99minutos, кэш проверки обслуживания и журнал. Если выключено (по умолчанию), они сохраняются для повторной установки. Заказы в любом случае сохраняются.

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

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

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

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

Когда OpenCart показывает способы доставки, он запрашивает у расширения цену 99Minutos. Если задана Geo zone и адрес находится вне её, 99Minutos не предлагается. Учитываются только товары с Requires Shipping = Yes: остальные не добавляют веса и не входят в сумму заказа. Способ предлагается только при стране доставки Мексика, Колумбия, Чили или Перу (и если она есть в списке Countries, когда включён Restrict countries). Затем расширение проверяет ограничения по весу и Minimum subtotal. Сумма заказа — это цена товаров, которые нужно доставить, после скидки по купону и без налога. Подарочные сертификаты, бонусные баллы и store credit не учитываются.

Если включена проверка обслуживания, расширение запрашивает у API 99minutos, обслуживается ли почтовый индекс. Тайм-аут запроса — 10 секунд, ответ кэшируется, поэтому тот же почтовый индекс не вызывает новый запрос. Ошибки API никогда не показываются покупателю: в режиме Strict способ доставки скрывается, в режиме Soft используется цена из матрицы. Бесплатная доставка не отменяет проверку обслуживания.

Цена берётся из строки матрицы для страны доставки или из строки * Default. Если нет ни той, ни другой, способ доставки скрывается. Если Free shipping включено и сумма заказа достигает Free shipping from, тариф равен 0. Цена рассчитывается в валюте магазина по умолчанию, округляется до её знаков после запятой и показывается покупателю в его валюте с налогом выбранного Tax class.

Расширение не получает тарифы в реальном времени от 99minutos: цены всегда берутся из вашей матрицы. Оно не создаёт отправления или заказы в 99minutos, не печатает ярлыки (guides), не отслеживает посылки, не предлагает пункты выдачи Punto99 и не поддерживает наложенный платёж. Оно ничего не добавляет к заказам: в заказе отображаются название способа доставки и стоимость доставки, как у любого другого способа OpenCart. Создавайте отправления в своей учётной записи 99minutos как обычно.

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

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

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

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

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

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

99Minutos не появляется при оформлении заказа: проверьте, что лицензия активна и включено Enable 99Minutos. Страна доставки должна быть Мексика, Колумбия, Чили или Перу и быть включена в System > Localisation > Countries. Проверьте Geo zone и Restrict countries. Проверьте, есть ли в Price matrix строка для этой страны или строка * Default, а также ограничения по весу и Minimum subtotal. Проверьте, что у товаров Requires Shipping = Yes. Предупреждения, которые появляются после Save, указывают на настройки, скрывающие способ доставки.

Способ доставки появляется только после ввода почтового индекса: это ожидаемо при проверке обслуживания. В режиме Strict он появляется, только если API подтверждает обслуживание.

В режиме Strict способ доставки всегда скрыт: включите Debug log, обновите оформление заказа и посмотрите поле Log на странице расширения. Ошибка HTTP 401 или 403 означает, что API отклонил ключ: проверьте ключ и соответствие Environment (тестовые и рабочие ключи различаются). Используйте режим Soft, если покупатели должны получать цену из матрицы, пока API недоступен.

Цена не такая, как ожидалось: проверьте Calculation (за заказ или за товар), а также веса товаров и весовые классы. Пустая или нулевая цена размера заменяется на Base price. С Tax class налог добавляется к цене из матрицы.

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

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

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

Удаление

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

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

99minutos — торговая марка её правообладателя. Это расширение не связано с 99minutos и не одобрено ею.