VibeFox Estafeta for OpenCart — Помощь

Требования

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

PHP: 8.0 или новее с расширением cURL.

Аккаунт DrEnvio (только для тарифов в реальном времени): тарифы Estafeta в реальном времени поступают от DrEnvio, партнёра Estafeta в Мексике. Создайте аккаунт на drenvio.com, включите Estafeta, укажите там адрес забора отправлений и скопируйте ключ API из панели DrEnvio. Это тот же ключ, который использует официальный плагин DrEnvio. Если вы используете только свои цены, аккаунт DrEnvio не нужен.

Товары: для тарифов в реальном времени товарам нужен вес.

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

Установка

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

OpenCart 3

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

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

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

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

5. Введите DrEnvio API key и, при необходимости, Origin postcode. Если валюта магазина по умолчанию не MXN, введите MXN exchange rate. Задайте цену для страны MX или Fallback cost, если способ доставки должен оставаться видимым, когда DrEnvio не возвращает тариф. Включите Enable/Disable и нажмите Save.

OpenCart 4

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

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

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

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

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Shipping > VibeFox Estafeta > Edit. Разделы перечислены слева. Одна кнопка Save внизу сохраняет всю страницу без перезагрузки. Каждое сохранение также очищает кэш тарифов DrEnvio. Сохранять настройки могут только администраторы с правом изменения для этого расширения.

В верхней части страницы расширение показывает предупреждения: не указан ключ API DrEnvio, валюта магазина по умолчанию отличается от MXN и нет курса обмена, не задана цена для страны MX и нет запасной стоимости (тогда способ доставки скрыт, если тарифа в реальном времени нет, или не показывается без ключа API), либо нет класса веса в килограммах (вес товаров тогда пересчитывается по названию единицы их класса веса, а неизвестные единицы считаются килограммами; добавьте класс kg в разделе System > Localisation > Weight Classes). Числовые поля принимают точку или запятую как десятичный разделитель. При сохранении неверное значение сообщается, а затем очищается или сбрасывается, как описано у каждого поля; форма показывает сохранённое значение, а остальные настройки всё равно сохраняются (The other settings were saved.).

Основные

Способ доставки предлагается для геозоны ниже (или для любого адреса) либо для стран из Availability without shipping zones.

Enable/Disable: включает или выключает доставку Estafeta. По умолчанию: выключено.

Name: название способа доставки, которое видит покупатель при оформлении заказа. По умолчанию: Estafeta. Обязательное поле: от 1 до 64 символов, без < > ; = # { }. Недопустимое название сообщается, и сохраняется прежнее.

Tax class: класс налога, который добавляется к стоимости доставки, либо No tax (по умолчанию). Включает ли тариф DrEnvio IVA, зависит от вашего аккаунта DrEnvio. Если IVA уже включён, выберите No tax.

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

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

Тарифы в реальном времени (API DrEnvio)

В разделе объясняется, где взять ключ. Предлагается самая дешёвая услуга Estafeta для адреса. Без ключа используются цены из раздела Prices without a live rate.

DrEnvio API key: ключ API из панели DrEnvio. После сохранения поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Remove the saved API key: отображается только тогда, когда ключ сохранён. Включите и сохраните, чтобы удалить ключ. После этого используются только Country prices и Fallback cost. Ключ, введённый в поле выше, заменяет сохранённый.

Origin country: двухбуквенный код страны адреса забора отправлений. По умолчанию: MX. Отправляется только вместе с почтовым индексом отправителя. Неверный код сообщается и сбрасывается на MX.

Origin postcode: пятизначный почтовый индекс адреса забора отправлений. Оставьте поле пустым, чтобы использовать адрес отправления, сохранённый в вашем аккаунте DrEnvio. Индекс, в котором не 5 цифр, при сохранении очищается и сообщается.

MXN exchange rate: DrEnvio рассчитывает стоимость в мексиканских песо. Нужен, только если валюта магазина по умолчанию не MXN: стоимость 1 MXN в валюте магазина по умолчанию, например 0.05. Без него тарифы в реальном времени не используются. Значение должно быть больше 0. Если валюта магазина MXN, оставьте поле пустым.

Цены без тарифа в реальном времени

Используются, когда нет ключа API или DrEnvio не возвращает тариф Estafeta (API недоступен, неизвестный почтовый индекс, индекс ещё не введён). Цены указаны в валюте магазина по умолчанию, без налога.

Country prices: одна страна назначения в строке в формате CC:ЦЕНА, например MX:150. Используйте точку или запятую как десятичный разделитель, без разделителя разрядов. Части в другом формате игнорируются и сообщаются при сохранении.

Fallback cost: цена, когда нет ни тарифа в реальном времени, ни цены для страны. Оставьте поле пустым, чтобы скрыть способ доставки; 0 означает бесплатную доставку.

Calculation type: Per order (по умолчанию) берёт цену один раз. Per item (price x number of items) умножает её на количество товаров в корзине. Это относится к Country prices и Fallback cost. Тариф DrEnvio в реальном времени всегда является ценой всей посылки.

Условия

Free shipping from: доставка бесплатна, если сумма товаров, требующих доставки (после купона, до налога), достигает этой суммы. В этом случае запрос к DrEnvio не отправляется. Оставьте поле пустым, чтобы никогда не предлагать бесплатную доставку.

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

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

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

Если Min weight больше Max weight, при сохранении появляется ошибка, и оба веса остаются без изменений. Веса товаров переводятся в килограммы по классу веса каждого товара.

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

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

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

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

Debug log: записывает запросы к API и расчёты тарифов в файл storage/logs/vfd_est_debug.log.php (в OpenCart 4 — system/storage/logs/vfd_est_debug.log.php). Файл нельзя открыть из веб-браузера. Ошибки API записываются всегда, даже когда журнал выключен. Ключ API и адреса покупателей никогда не записываются. Выключайте журнал, когда закончите. Когда файл достигает 5 МБ, он переносится в vfd_est_debug.old.log.php, и начинается новый журнал.

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

Remove data on uninstall: если включено, при удалении расширения удаляются все его настройки и журнал. Если выключено (по умолчанию), всё сохраняется для повторной установки. Сохранённые услуги Estafeta в заказах всегда остаются.

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

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

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

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

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

В остальных случаях расширение передаёт DrEnvio страну и почтовый индекс назначения, вес корзины, количество товаров и сумму в MXN, а также почтовый индекс отправления, если вы его задали. Мексиканские почтовые индексы должны содержать 5 цифр; пока покупатель не введёт адрес доставки с таким индексом, запрос не отправляется. DrEnvio возвращает расчёты всех перевозчиков вашего аккаунта. Расширение использует только расчёты Estafeta, пропускает нулевые цены, выбирает самую дешёвую и переводит её в валюту магазина по умолчанию. Цена округляется до знаков этой валюты и показывается покупателю в его валюте с налогом выбранного Tax class.

Каждый ответ кэшируется на 1 час. Неудачный запрос или маршрут без тарифа Estafeta запоминается на 5 минут, чтобы медленный или сломанный API никогда не тормозил каждое обновление оформления заказа. Тайм-аут API составляет 12 секунд. В таких случаях покупатель не видит ошибки: используется цена для страны или запасная стоимость, либо способ доставки скрывается, если ни того ни другого нет. Причина записывается в журнал.

Покупатель видит только название способа доставки и цену. Расширение только рассчитывает тарифы. Оно не создаёт отправления, не печатает накладные (guías) и не отслеживает посылки; создавайте отправление в своём аккаунте DrEnvio или Estafeta. Покупатель не может выбрать конкретную услугу Estafeta или отделение Estafeta, а курсы валют не обновляются автоматически.

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

Заказы

Когда заказ с Estafeta оформлен, расширение сохраняет тариф, показанный покупателю, без нового запроса к DrEnvio. Последующие изменения заказа в админ-панели его не меняют. В OpenCart 4 оформление заказа использует один заказ и обновляет его каждый раз, когда покупатель подтверждает заказ снова, поэтому сохранённый тариф заменяется последним тарифом оформления. Если покупатель переключается на другой способ доставки, панель для этого заказа больше не показывается.

На странице заказа в разделе Sales > Orders отображается панель Estafeta:

Estafeta service: услуга Estafeta из расчёта DrEnvio и её срок доставки. Показывается только для тарифов в реальном времени.

Price source: Live DrEnvio rate, Country price (no live rate), Fallback cost (no live rate) или Free shipping threshold.

Shipping cost: цена доставки, рассчитанная при оформлении заказа, в валюте магазина по умолчанию, без налога.

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

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

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

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

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

Estafeta не отображается при оформлении заказа: проверьте, что лицензия активна и Enable/Disable включено. Проверьте Geo zone или Ignore shipping zones и Countries. Проверьте предупреждения в верхней части страницы расширения, ограничения по весу и Minimum subtotal. Без ключа API или когда DrEnvio не возвращает тариф Estafeta, способу доставки нужна цена для страны назначения или запасная стоимость. Проверьте, что у товаров Requires Shipping установлено в Yes.

Тарифы в реальном времени не появляются: включите Debug log, обновите страницу оформления заказа и посмотрите поле Log на странице расширения. Там указана причина: нет ключа API; нет курса обмена для магазина, валюта которого не MXN; почтовый индекс отсутствует или неверен; ключ API отклонён (HTTP 401 или 403 от DrEnvio, проверьте ключ API); нет тарифа Estafeta для маршрута (в журнале перечислены перевозчики, которые вернул DrEnvio); или тариф в валюте, отличной от MXN.

Цена включает IVA? Это зависит от вашего аккаунта DrEnvio. Если цены DrEnvio уже включают IVA, установите Tax class в No tax.

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

На странице заказа нет панели Estafeta: панель показывается только для заказов, оформленных с Estafeta, пока расширение было установлено и включено.

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

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

Удаление

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

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

Estafeta и DrEnvio являются товарными знаками их владельцев. Это расширение не связано с Estafeta или DrEnvio и не одобрено ими.