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

Требования

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

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

Аккаунт Blue Express (только для живых тарифов): живым тарифам нужен аккаунт электронной коммерции Blue Express и его ключ API (x-api-key). Запросить его можно у Blue Express: developers.bluex.cl или gpo.integraciones@bx.cl. Услуга, которую вы используете (EX, PY или MD), должна быть включена в вашем договоре с Blue Express. Если вы используете только фиксированные цены, ключ API не нужен.

Регионы Чили: для живого тарифа адрес доставки должен содержать регион Чили. Если в вашем магазине нет регионов Чили, расширение может добавить их за вас (см. Настройка).

Пункты выдачи: карта Blue Express загружается в браузере покупателя с widget-pudo.blue.cl.

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

Установка

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

OpenCart 3

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

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

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

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

5. Введите ключ API, услугу, код района отправки (например SCL), курс CLP, если валюта вашего магазина не CLP, и фиксированные цены (например CL=4500). Включите Enable/Disable для доставки на дом и Pickup point option, если хотите предлагать самовывоз в пунктах Blue Express. Нажмите Save. См. раздел Настройка.

OpenCart 4

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

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

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

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

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

Настройка

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

Недопустимые значения отклоняются с ошибкой, и ничего не сохраняется: пустое название или название с символами < > ; = # { }, название длиннее 64 символов, отрицательное или некорректное число, Min weight (kg) больше Max weight (kg), Sort order, которое не является целым числом, или неизвестный налоговый класс или геозона.

Предупреждения о настройках, которые скрыли бы варианты или живой тариф, показываются вверху страницы: нет ключа API, валюта магазина не CLP без курса обмена, пустая таблица фиксированных цен, нет зон для Чили, а также магазин без весовой единицы «килограмм» или единицы длины «сантиметр», единицу по умолчанию которых расширение не распознаёт (тогда веса читаются как кг, а размеры как см).

Общие

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

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

Tax class: налоговый класс стоимости доставки или None (no tax on shipping) (по умолчанию). Цены Blue Express включают НДС (IVA). Выберите None, если OpenCart не должен добавлять налог сверху. Действует для обоих вариантов.

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

Самовывоз в пунктах Blue Express (PUDO)

Pickup point option: предлагает доставку в пункт Blue Express, выбранный покупателем, как второй вариант рядом с доставкой на дом. По умолчанию выключено.

Pickup point name: название способа доставки, которое видит покупатель на оформлении для самовывоза в пункте Blue Express. По умолчанию: Blue Express pickup point. Обязательное поле, не больше 64 символов.

API Blue Express (нужен для живых тарифов)

API key: ваш ключ API Blue Express (заголовок x-api-key). Без него используются только фиксированные цены. После сохранения поле остаётся пустым и показывает A key is saved - leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Remove the saved API key: включите и сохраните, чтобы удалить сохранённый ключ.

Service: услуга Blue Express для тарифа: Express (EX) (по умолчанию), Prioritario (PY) или SameDay (MD). Она должна быть включена в вашем договоре с Blue Express.

Origin district code: код района Blue Express того места, откуда вы отправляете, например SCL для Сантьяго (по умолчанию). Если не уверены, уточните у Blue Express.

CLP per 1 (your currency): надпись показывает основную валюту вашего магазина, например CLP per 1 EUR. Цены Blue Express указаны в чилийских песо (CLP). Введите, сколько CLP стоит одна единица основной валюты вашего магазина, например 1050. Без этого живые тарифы не используются. Игнорируется, если валюта магазина — CLP.

Цена

Rate source: как рассчитывается цена. Живой тариф требует чилийский адрес с регионом и коммуной (городом). Ошибки записываются в журнал и никогда не показываются покупателю.

Fixed prices: одна строка на страну в формате КОД_СТРАНЫ=ЦЕНА, в основной валюте магазина, без налога, например CL=4500 в магазине в CLP или CL=4.50 в магазине в EUR. В качестве десятичного разделителя принимаются запятая и точка. Некорректные строки игнорируются и перечисляются в предупреждении при сохранении. Страна без строки не имеет фиксированной цены, поэтому варианты для неё скрываются, когда нужна фиксированная цена. Фиксированные цены можно использовать для любой страны.

Fixed price per: Order (по умолчанию) взимает цену один раз. Item (price x quantity) умножает её на количество товаров в корзине. Это относится только к фиксированной цене. Цена API всегда рассчитывается на всё отправление.

Условия

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

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

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

Бесплатная доставка

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

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

Доступность

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

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

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

Регионы Чили (показывается, только если в вашем магазине нет регионов Чили)

Blue Express требует регион чилийского адреса (RM, VS и т. д.) для живого тарифа. Регион берётся из зоны адреса по её коду или названию. В этом разделе показано, сколько зон Чили есть в вашем магазине и каких регионов не хватает (в стандартном магазине OpenCart 3.0.5 есть 15 из 16, без Ñuble). Нажмите Add Chilean regions, чтобы добавить недостающие регионы как зоны Чили с кодами, которые использует Blue Express. Регионы, которые у вас уже есть (по коду или названию), не добавляются повторно. Ничего не меняется, пока вы не нажмёте кнопку. Вы также можете добавить их вручную в System > Localisation > Zones.

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

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

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

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

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

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

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

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

Когда OpenCart показывает способы доставки, он запрашивает у расширения цену каждого включённого варианта. Если задана Geo zone (и Ignore shipping zones выключено) и адрес вне неё, Blue Express не предлагается. При Ignore shipping zones решает список Countries. Учитываются только товары с Requires Shipping = Yes: остальные товары не добавляют вес и не входят в подытог. Расширение проверяет вес корзины и Minimum order subtotal. Подытог — это цена товаров, требующих доставки, после скидки по купону и до налога. Подарочные сертификаты, бонусные баллы и кредит магазина не учитываются. Если действует бесплатная доставка, цена равна 0 и запрос в Blue Express не отправляется.

Для живого тарифа адрес должен быть в Чили, с регионом и городом (коммуной). Расширение сначала просит Blue Express распознать коммуну, затем запрашивает цену за услугу, район отправки, пункт назначения и посылки. Каждый товар отправляется с весом и габаритами, переведёнными в кг и см из его весового и линейного классов. Товары без веса или размера отправляются как 0,01 кг, 10 x 10 x 10 см. Объявленная стоимость отправляется в CLP. Цена в CLP пересчитывается в основную валюту магазина, округляется до его знаков после запятой и показывается покупателю в его валюте с налогом выбранного Tax class.

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

Расширение не создаёт отправлений и этикеток в Blue Express, не присваивает номера отслеживания и не показывает обновления отслеживания. Создайте отправление в своём аккаунте Blue Express. Региональных тарифных таблиц по коммунам нет: используйте тариф API Blue Express или фиксированную цену за страну. Живые тарифы работают только для Чили.

На OpenCart 4 покупатель нажимает Choose в блоке способов доставки на странице оформления и выбирает Blue Express или Blue Express pickup point в окне Shipping method options. Варианты работают так же, как в OpenCart 3; блок пункта выдачи описан в разделе Пункты выдачи.

Пункты выдачи

Когда опция пункта выдачи включена, под способом Blue Express pickup point на шаге Delivery Method оформления заказа OpenCart появляется блок с кнопкой Choose pickup point. Кнопка открывает официальную карту Blue Express, где покупатель выбирает пункт. Выбранный пункт показывается с названием и адресом, а кнопка меняется на Change pickup point. Пункт сохраняется для сеанса оформления, и тариф пересчитывается по цене самовывоза (PUDO) Blue Express. Если цена меняется, вариант показывает новую цену. Если вариант больше не предлагается для этого пункта, шаг доставки перезагружается. Пока пункт не выбран, вариант показывает цену доставки на дом.

Покупатель не может продолжить без пункта: Continue на шаге доставки отклоняется с сообщением Please choose a Blue Express pickup point. Это проверяется в браузере и повторно магазином. Некорректный код пункта отклоняется с сообщением The selected Blue Express pickup point is not valid. Please choose it again on the map., и предыдущий выбор сохраняется. Если сохранение не удалось, покупатель видит The pickup point could not be saved. Please try again.

На OpenCart 4 покупатель нажимает Choose в блоке способов доставки на странице оформления. В окне Shipping method options показан тот же блок с Choose pickup point под Blue Express pickup point, пока выбран этот вариант. Если цена меняется с выбранным пунктом, вариант в окне показывает новую цену, а если вариант самовывоза уже сохранён для оформления, обновляются также поле способа доставки и блок подтверждения заказа. Если вариант больше не предлагается для этого пункта, окно закрывается и список способов доставки загружается снова. Continue в окне без пункта блокируется с сообщением Please choose a Blue Express pickup point. в блоке, и магазин проверяет это повторно. OpenCart 4 хранит один заказ для оформления и обновляет его при каждом подтверждении; пункт выдачи заказа обновляется вместе с ним и удаляется, когда заказ переключают на другой способ доставки.

При оформлении заказа пункт сохраняется в заказе с кодом агентства Blue Express, названием, адресом и регионом. Он также добавляется к способу доставки заказа после названия варианта самовывоза, например Blue Express pickup point: Blue Point Providencia, Av. Providencia 1234, чтобы покупатель видел его в письмах о заказе и на страницах заказов своего аккаунта.

На странице заказа в админке (Sales > Orders, View) пункт показан в панели Blue Express pickup point с кодом и регионом. Если у заказа нет пункта, панель показывает Not chosen. Нажмите Edit, чтобы выбрать другой пункт кнопкой Choose on the Blue Express map или ввести вручную Agency code, Name и Address, затем нажмите Save pickup point. Текст способа доставки заказа тоже обновляется, а изменение добавляется в историю заказа без уведомления покупателя (Blue Express pickup point changed: старый код -> новый код). Для изменения пункта нужно только право на изменение заказов, а не доступ к настройкам расширения. Существующие заказы сохраняют данные о пункте выдачи.

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

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Blue Express — первый блок на странице Extensions > Extensions > Shipping > VibeFox Blue Express > Edit, над настройками. Вставьте ключ в License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой лицензия действует, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: opencart-shipping-blue-express и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт vibefox.net. Менять ключ могут только администраторы с правом изменения этого расширения. Тексты блока следуют языку админки (включены английский и русский).

Если ключ не принят, блок указывает причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on с датой. После смены адреса магазина или после освобождения слота домена в аккаунте нажмите Check now. Если сервер лицензий недоступен, расширение продолжает работать по последнему известному статусу.

Один ключ работает на одном домене: адрес магазина из настроек OpenCart. Удаление ключа из магазина не освобождает его слот домена. Освободите слот в своём аккаунте vibefox.net.

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

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

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

Blue Express не появляется при оформлении заказа: проверьте, что лицензия активна и Enable/Disable (или Pickup point option) включено. Прочитайте предупреждения вверху страницы расширения. Проверьте Geo zone (или Ignore shipping zones и Countries), ограничения по весу, Minimum order subtotal, и что в Fixed prices есть строка для страны, если вы используете фиксированные цены или резерв. Проверьте, что у товаров Requires Shipping = Yes.

Живые тарифы не появляются: при Blue Express API only варианты скрываются, если тарифа нет. Включите Debug log, перезагрузите оформление и посмотрите поле Log на странице расширения. Типичные причины: нет ключа API, валюта магазина не CLP без курса обмена, в адресе нет региона или коммуны, коммуна не распознана Blue Express, или ошибка API (например HTTP 401 или 403, если ключ API отклонён). С Blue Express API, fixed price if the API gives no rate покупатели всё равно получают фиксированную цену, пока вы устраняете проблему.

В чилийских адресах нет региона: страница показывает предупреждение о недостающих регионах. Нажмите Add Chilean regions на странице расширения. Покупатели, чьи адреса сохранены без региона, должны изменить адрес и выбрать регион.

Налог добавляется поверх цены Blue Express: цены Blue Express включают НДС (IVA). Установите Tax class в None (no tax on shipping).

Карта не открывается: карта загружается в браузере покупателя с widget-pudo.blue.cl, поэтому этот адрес должен быть доступен и не блокироваться на вашем сайте.

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

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

Для разработчиков: адреса API Blue Express и карты можно заменить настройками vfd_blex_api_url и vfd_blex_widget_url (для тестов); на странице настроек для них нет полей.

Удаление

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

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

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