VibeFox Chilexpress for OpenCart — Помощь

Требования

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

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

Ключи API Chilexpress (только для актуальных тарифов): создайте учётную запись на портале разработчиков Chilexpress (developers.wschilexpress.com) и оформите подписку на два продукта: Rating (Cotizador) и Coverage (Coberturas / Georreferencia). У каждого продукта свой ключ подписки. Тестовые ключи работают только в тестовой среде; рабочие ключи выдаются корпоративным клиентам Chilexpress по договору. Также нужен код коммуны Chilexpress (county code) коммуны, из которой вы отправляете, например STGO. Если вы используете только фиксированные цены, ключи API не нужны.

Регионы Чили (только для актуальных тарифов): для актуальных тарифов нужен регион (зона) адреса доставки. OpenCart 3.0.5.0 содержит 15 из 16 регионов Чили; расширение может добавить недостающие (см. Chilean regions ниже). Страна Chile должна существовать в магазине.

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

Установка

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

OpenCart 3

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

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

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

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

5. Заполните таблицу Country prices. Для актуальных тарифов введите оба ключа подписки, код коммуны отправления и, если валюта магазина не CLP, курс CLP. Нажмите Add Chilean regions, если страница показывает недостающие регионы, и затем выберите источник тарифов (см. раздел «Настройка»). Включите Enable/Disable и нажмите Save.

OpenCart 4

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

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

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

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

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Shipping > VibeFox Chilexpress > Edit. Разделы перечислены слева. Одна кнопка Save внизу сохраняет всю страницу без перезагрузки. После сохранения вы увидите Settings saved. Cached Chilexpress rates and comuna lists were cleared. Сохранять настройки, очищать журнал или добавлять регионы могут только администраторы с правом изменения этого расширения.

Вверху страницы выводятся проблемы: выбраны тарифы API, но ключ Rating API пуст; ключ Coverage API пуст; код коммуны отправления пуст или некорректен; валюта магазина не CLP, и курс CLP не задан; в Country prices нет строки для Чили или для значения по умолчанию; у Чили нет зон в магазине; единица веса или длины магазина не известна расширению (тогда веса читаются как кг, а размеры как см; используйте kg, g, lb или oz и cm, mm, m или in в System > Localisation). Числа можно вводить с точкой или с запятой. Ничего не сохраняется, и страница выводит ошибки, если поле Name пустое, содержит один из символов < > ; = # { } или длиннее 64 символов, число некорректно или отрицательно, CLP exchange rate равен 0, Min weight (kg) больше Max weight (kg), Origin county code не является кодом коммуны или Sort order не является целым числом.

Общие

Один способ доставки «Chilexpress» для каждой гео-зоны или для гео-зоны, выбранной в разделе Доступность.

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

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

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

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

Тарифы

Rate source: откуда берётся цена.

Актуальные тарифы доступны только для направлений в Чили. Для других стран всегда используются фиксированные цены.

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

Calculation type: Per order (по умолчанию) взимает фиксированную цену один раз. Per item (fixed price x number of items) умножает её на количество товаров в корзине. Тариф API Chilexpress всегда назначается на всю посылку.

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

Раздел начинается со ссылок на портал разработчиков и страницы подписки на Rating и Coverage.

Test environment: использует тестовую среду Chilexpress (qaservices.wschilexpress.com). Используйте её с тестовыми ключами и выключайте в рабочем магазине. По умолчанию: выключено.

Rating API key: ключ подписки продукта Rating (Cotizador).

Coverage API key: ключ подписки продукта Coverage (Coberturas / Georreferencia). Он нужен, чтобы найти код коммуны Chilexpress для коммуны покупателя (поле City адреса вместе с его регионом).

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

Remove the saved Rating API key и Remove the saved Coverage API key: включите один из них и нажмите Save, чтобы удалить этот ключ.

Origin county code: код коммуны Chilexpress, из которой вы отправляете, 2–5 букв, например STGO (Santiago Centro), PROV (Providencia) или VALP (Valparaíso). После установки поле пустое. Значение, которое не является кодом коммуны, отклоняется с ошибкой.

Service: сервис Chilexpress, используемый для тарифа. Если он не предлагается для направления, используется самый дешёвый из предлагаемых сервисов.

CLP exchange rate: Chilexpress назначает тарифы в чилийских песо. Нужно только если валюта магазина по умолчанию не CLP: цена 1 CLP в этой валюте, например 0.001. Без него тарифы API не используются. Если валюта магазина CLP, оставьте поле пустым. Значение должно быть больше 0.

Chilean regions: коммуны Чили ищутся по регионам, поэтому для актуальных тарифов нужен регион (зона) адреса. Поле показывает, сколько зон у Чили и каких регионов не хватает, и содержит кнопку Add Chilean regions. Она добавляет только недостающие регионы как зоны Чили; существующие зоны не меняются, а регион не добавляется дважды. Когда все 16 регионов на месте, поле показывает All 16 Chilean regions are zones of Chile. Если Чили не является страной магазина, поле сообщает об этом: добавьте её в System > Localisation > Countries.

Доступность

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

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

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

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

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

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

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

Free shipping: включает порог бесплатной доставки.

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

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

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

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

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

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

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

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

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

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

Для адреса в Чили и источника тарифов API расширение берёт регион (зону) адреса и коммуну из поля City и ищет код коммуны Chilexpress в списке коммун этого региона (API Coverage). Ударения, пробелы и варианты написания игнорируются, поэтому Ñuñoa и Nunoa совпадают, а Santiago совпадает с Santiago Centro. Код коммуны, введённый в поле City, тоже принимается. Затем расширение отправляет в Rating API коды коммун отправления и назначения, вес корзины (не менее 0,1 кг), размеры посылки (длина и ширина самого большого товара, высоты сложены) и промежуточный итог корзины в CLP как объявленную стоимость. Chilexpress возвращает свои сервисы; расширение использует выбранный или самый дешёвый, переводит сумму в песо в валюту магазина по умолчанию. Цена округляется до знаков этой валюты и затем показывается в валюте покупателя с налогом выбранного Tax class.

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

Расширение только рассчитывает тарифы. Оно не создаёт отправления и транспортные заказы (OT), не печатает этикетки, не бронирует забор посылок и не отслеживает посылки; оформите отправку в своём аккаунте Chilexpress. Покупатели не могут выбрать офис Chilexpress, и селектора коммун нет: покупатель вводит коммуну в стандартное поле City. Международные отправления используют фиксированные цены.

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

Заказы

Когда заказ оформлен с Chilexpress, расширение сохраняет, как была рассчитана его цена. В Sales > Orders на странице заказа отображается панель Chilexpress с Chilexpress service (для актуального тарифа — сервис, названный Chilexpress, например Express; иначе тире) и Price: Live rate (Chilexpress Rating API), Fixed price или Free shipping. Панель показывается и тогда, когда способ выключен. В OpenCart 4 панель Chilexpress показывается над History, и когда заказ повторно подтверждается при оформлении или переводится на другой способ доставки, панель следует за изменением.

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

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

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

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

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

Chilexpress не появляется при оформлении заказа: проверьте, что лицензия активна и включён Enable/Disable. Проверьте Geo zone (или Ignore shipping zones и Countries), ограничения по весу и Minimum subtotal. При фиксированных ценах проверьте, что для страны или * Default (other countries) есть строка. Проверьте, что у товаров Requires Shipping установлено в Yes.

Доставка в Чили бесплатна, хотя не должна быть: строка Country prices для Чили (или строка по умолчанию) содержит 0 в Price и в колонках размеров. Введите цены и нажмите Save.

Актуальный тариф не показывается, используется фиксированная цена: сначала проверьте предупреждения вверху страницы расширения. Если их нет, включите Debug log, перезагрузите оформление заказа и посмотрите поле Log на странице расширения. Типичные причины: у адреса нет региона или у Чили не хватает регионов (используйте Add Chilean regions), коммуна не распознана Chilexpress (проверьте поле City и регион), ключ для другого продукта или среды, или направление без покрытия Chilexpress.

HTTP 401 или 403 в журнале: ключ подписки неверный, неактивен или относится к другому продукту или среде. Тестовые ключи работают только при включённом Test environment.

Тарифы API не используются в магазине с другой валютой: введите CLP exchange rate.

Тарифы API с IVA или без IVA? Они используются точно так, как их назначает Chilexpress. Если магазин добавляет налог к доставке, а тариф уже включает IVA, установите Tax class в No tax.

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

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

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

Удаление

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

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

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