VibeFox Envioclick for OpenCart — Помощь

Требования

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

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

Учётная запись Envioclick (только для актуальных тарифов): учётная запись Envioclick в Мексике или Колумбии с доступом к API. Ключ API находится в вашей учётной записи Envioclick: Mi cuenta (вверху справа) > Información del API. Если вы используете только фиксированные тарифы, учётная запись Envioclick не нужна.

User-Agent (только Мексика): Envioclick Мексика требует значение User-Agent в каждом запросе к API. Запросите его у службы поддержки Envioclick (soporte.tecnico@envioclick.com).

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

Установка

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

OpenCart 3

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

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

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

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

5. Введите ключ API, выберите страну API, введите User-Agent (Мексика), почтовый индекс отправителя или код DANE и адрес отправителя. Если валюта магазина по умолчанию не MXN и не COP, введите курс конвертации валюты. По желанию добавьте фиксированные тарифы по странам и стоимость по умолчанию. Включите Enable Envioclick и нажмите Save.

OpenCart 4

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

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

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

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

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

Настройка

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

Раздел General показывает предупреждения, если актуальные тарифы не могут работать с сохранёнными настройками: нет курса конвертации для валюты магазина, отличной от MXN или COP, нет User-Agent для Мексики, нет почтового индекса или кода DANE отправителя, либо нет адреса отправителя для Колумбии. Также выводится предупреждение, если единица веса или длины магазина не распознана; тогда добавьте класс веса с единицей kg в разделе System > Localisation > Weight Classes или класс длины с единицей cm в разделе System > Localisation > Length Classes. При сохранении расширение проверяет, что Method title содержит от 1 до 64 символов, что числовые поля содержат неотрицательные числа, что Currency conversion rate больше 0, что Minimum weight (kg) не больше Maximum weight (kg), что код отправителя содержит 5 цифр для Мексики или 8 цифр (либо 5-значный код муниципалитета) для Колумбии, что в каждой строке Price per country указаны корректная страна и цена, и что Sort order является целым числом. Если проверка не проходит, ничего не сохраняется, а страница перечисляет ошибки.

Общие

Покупатель видит один тариф Envioclick — самого дешёвого или самого быстрого перевозчика. Способ можно ограничить гео-зоной или странами в разделе Availability.

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

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

Carrier in the title: добавляет в название перевозчика Envioclick и расчётный срок доставки для актуального тарифа, например «Envioclick Shipping (Estafeta Express, 1 day)». OpenCart сохраняет это название вместе с заказом, поэтому оно также отображается в письмах о заказе и на страницах заказов. Перевозчик в любом случае сохраняется в заказе. По умолчанию: включено.

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

API Envioclick (актуальные тарифы)

Необязательно. Без ключа API используются только фиксированные тарифы. Раздел содержит ссылку на документацию API Envioclick для Мексики и Колумбии. Актуальные тарифы запрашиваются только для направлений внутри страны API. Доставка в другие страны использует фиксированные тарифы.

API key: ваш ключ API Envioclick из раздела Mi cuenta > Información del API. Он передаётся в заголовке «Authorization» и никогда не показывается покупателям и не записывается в журнал. После сохранения поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Remove the saved API key: включите эту опцию и сохраните настройки, чтобы удалить сохранённый ключ; тогда используются только фиксированные тарифы. Ключ, введённый в поле API key, заменяет сохранённый. Переключатель выключается сам после сохранения.

API country: страна вашей учётной записи Envioclick.

User-Agent (Mexico): значение, выданное службой поддержки Envioclick (soporte.tecnico@envioclick.com), например EcUserAgent-2/123456. Обязательно для Мексики; без него актуальные тарифы для Мексики не запрашиваются. Для Колумбии необязательно.

Carrier choice: Cheapest (по умолчанию) или Fastest (then cheapest). Envioclick возвращает расчёты от нескольких перевозчиков, а покупатель получает один тариф.

Branch pickup rates: также учитывать тарифы «Ocurre», при которых покупатель забирает посылку в отделении перевозчика. Когда опция выключена, используются только тарифы доставки на дом. Услуги наложенного платежа (COD) никогда не используются. По умолчанию: выключено.

Currency conversion rate: Envioclick рассчитывает тарифы в MXN (Мексика) или COP (Колумбия). Если валюта магазина по умолчанию другая, введите стоимость 1 MXN или 1 COP в валюте вашего магазина, например 0.05. Заявленная стоимость посылки пересчитывается так же. Оставьте поле пустым, если валюта магазина MXN или COP. Без курса актуальные тарифы в другой валюте не используются.

Отправка из

Используется для актуальных тарифов. OpenCart не хранит почтовый индекс, город или улицу магазина, поэтому укажите их здесь.

Origin postcode / DANE code: Мексика: 5-значный почтовый индекс. Колумбия: 8-значный код DANE муниципалитета, например 11001000 для Боготы; 5-значный код муниципалитета (11001) дополняется до 000.

Origin address: улица и номер адреса, по которому производится забор отправлений. Обязательно для Колумбии, необязательно для Мексики.

Фиксированные тарифы

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

Price per country: список стран и цен в валюте магазина по умолчанию, без налога. Нажмите Add country, чтобы добавить строку, и кнопку × — чтобы удалить её. Выберите * All other countries для цены, которая применяется ко всем странам, не имеющим собственной строки.

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

Fixed price applies: Per order (по умолчанию) взимает цену один раз. Per item (price × quantity) умножает её на количество товаров в корзине. Актуальные тарифы Envioclick всегда рассчитываются за отправление.

Условия

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

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

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

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

Tax class: класс налога на стоимость доставки или No tax (по умолчанию). Расчёты Envioclick уже включают налоги перевозчиков, поэтому выберите No tax, чтобы не начислять налог на доставку дважды.

Доступность

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

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

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

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

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

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

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

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

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

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

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

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

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

Если ключ API задан и направление находится в стране API, расширение запрашивает расчёты у Envioclick. В Мексике запрос выполняется, когда покупатель ввёл 5-значный почтовый индекс. В Колумбии запрос выполняется, когда муниципалитет распознан по 8-значному коду DANE в поле почтового индекса или по департаменту (региону адреса OpenCart) и городу; название города, уникальное в Колумбии, распознаётся без департамента. Регистр и диакритические знаки не имеют значения. Расширение выбирает самый дешёвый или самый быстрый расчёт, который не является наложенным платежом, и пересчитывает его в валюту магазина по умолчанию. Цена округляется до знаков после запятой этой валюты и показывается покупателю в его валюте с налогом выбранного Tax class.

Посылка всегда одна коробка: общий вес, пересчитанный в кг из классов веса товаров, и размер коробки, рассчитанный по габаритам товаров, пересчитанным в см. Товары без габаритов считаются как 10 × 10 × 10 см. Корзина без веса отправляется как 0,5 кг. Заявленная стоимость — это сумма заказа.

Каждый расчёт кэшируется на 1 час для того же маршрута и той же посылки. Неудачный запрос кэшируется на 10 минут, чтобы недоступность API не замедляла каждое обновление оформления заказа. Если Envioclick возвращает ошибку или для маршрута нет перевозчика, покупатель не видит ошибки: используется фиксированная цена или стоимость по умолчанию, либо способ скрывается. Причина записывается в журнал отладки, если он включён.

Расширение только рассчитывает тарифы. Оно не создаёт накладные и этикетки, не заказывает забор отправлений и не отслеживает и не отменяет отправления. Оно предлагает один тариф, а не выбор между перевозчиками, и не использует услуги наложенного платежа и расчёты для нескольких посылок. Актуальные расчёты действуют только внутри страны.

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

Заказы

Когда заказ оформляется через Envioclick, тариф, рассчитанный при оформлении, сохраняется вместе с заказом и больше не меняется. В разделе Sales > Orders страница заказа показывает панель Envioclick shipping с полями Envioclick carrier, Estimated delivery и Envioclick rate ID (для актуального тарифа), Price source (Envioclick live rate, Fixed price per country, Fallback cost или Free shipping threshold) и Calculated price (excl. tax). Панель показывается даже после выключения способа.

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

Если опция Carrier in the title включена, перевозчик входит в название способа доставки заказа. Если она выключена, в письмо о новом заказе и на страницу заказа в личном кабинете покупателя добавляется строка Shipping carrier: с перевозчиком актуального тарифа, пока расширение включено. Создайте накладную в своей учётной записи Envioclick. У заказов с фиксированной ценой нет перевозчика Envioclick.

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

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

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

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

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

Envioclick не появляется при оформлении заказа: проверьте, что лицензия активна и включён Enable Envioclick. Проверьте Geo zone или Ignore shipping zones и Countries, ограничения по весу и Minimum order amount. Без актуального тарифа способу нужна фиксированная цена для страны, строка * All other countries или Fallback cost. Проверьте, что у товаров Requires Shipping установлено Yes.

Актуальные тарифы не появляются: прочитайте предупреждения в разделе General, затем включите Debug log, перезагрузите оформление заказа и посмотрите поле Log на странице расширения. Частые причины: нет курса конвертации (валюта магазина не MXN и не COP), нет User-Agent (Мексика), нет почтового индекса или кода DANE отправителя, ещё не введён почтовый индекс покупателя (Мексика) или город (Колумбия), направление находится за пределами страны API, либо для маршрута нет перевозчика.

Зачем нужен курс конвертации? Envioclick возвращает цены только в мексиканских или колумбийских песо. Расширение никогда не показывает сумму в песо как сумму в другой валюте.

Колумбия: город не распознаётся: проверьте, что покупатель выбирает департамент как регион адреса и правильно вводит название муниципалитета. Также работает 8-значный код DANE, введённый как почтовый индекс.

Налог на доставку начисляется дважды: расчёты Envioclick уже включают налоги перевозчиков. Установите Tax class в No tax.

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

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

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

Удаление

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

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

Envioclick — товарный знак его владельца. Это расширение не связано с Envioclick и не одобрено компанией Envioclick.