VibeFox Chilexpress for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

PHP: 8.0 или новее, с расширением cURL для актуальных тарифов. Модуль не устанавливается на более старых версиях PHP.

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

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

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

Установка

1. В бэк-офисе перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox Chilexpress в списке модулей и нажмите Configure.

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

4. Заполните таблицу Country prices. Для актуальных тарифов введите оба ключа подписки, код county отправления и, если валюта магазина не CLP, курс обмена CLP; нажмите Add Chilean regions, если страница об этом попросит; затем выберите источник тарифов (см. Настройка) и нажмите Save.

При установке модуль создаёт перевозчика Chilexpress с текстом срока доставки Chilexpress courier. Перевозчик привязан к зоне Chile и ко всем группам покупателей. Зоны, группы покупателей, срок доставки, логотип и ограничения по размеру можно изменить в Shipping > Carriers. Цены там не задавайте: цена всегда берётся из модуля. Чтобы предлагать Chilexpress в других зонах, добавьте их к перевозчику на этой странице или включите Ignore shipping zones.

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Chilexpress > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Каждое сохранение также очищает кешированные тарифы Chilexpress и списки коммун. Для изменений нужно разрешение «configure» для модуля; без него страница показывает You do not have permission to configure this module.

Страница показывает проблемы в верхней части: выбраны тарифы API, но не заполнены ключ, код county отправления или курс обмена CLP; в таблице цен нет строки для Чили или значения по умолчанию; в магазине нет регионов Чили или в адресной форме для Чили нет поля региона; единица веса или размеров магазина модулю не известна (тогда она считается килограммами или сантиметрами; задайте её в International > Localization, Local units); перевозчик был удалён. Числа можно вводить с точкой или запятой, как принято в языке вашего бэк-офиса. Неверное или отрицательное число, CLP exchange rate, равный 0, Min weight (kg) больше Max weight (kg) или Name длиннее 64 символов — это ошибки, и ничего не сохраняется, пока вы их не исправите.

Общие

Enable/Disable: включает или выключает доставку через Chilexpress. Это тот же переключатель, что и статус перевозчика в Shipping > Carriers.

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

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

Тарифы

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Chilean regions: коммуны Чили ищутся по регионам, поэтому актуальным тарифам нужен регион адреса. Если в магазине нет регионов Чили, поле показывает кнопку Add Chilean regions. Она добавляет 16 регионов как штаты Chile (ISO-коды RM, VS…), включает «Contains states» для Chile и добавляет поле региона в адресную форму для Чили. Регионы, которые уже есть (по коду или по названию), не добавляются повторно. Когда всё настроено, поле показывает Chilean addresses have a region с количеством регионов.

Доступность

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

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

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

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

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

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

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

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

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

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

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

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

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

На шаге доставки PrestaShop запрашивает у модуля цену Chilexpress. Учитываются только товары, требующие доставки: виртуальные товары не добавляют вес и не входят в промежуточную сумму. Промежуточная сумма берётся после правил корзины (купоны), без налогов, в валюте магазина по умолчанию. Модуль сначала проверяет условия: разрешённые страны (с Ignore shipping zones), вес корзины и минимальную сумму. Если применяется бесплатная доставка, цена равна 0 и запрос к Chilexpress не отправляется.

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

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

Если вы редактируете перевозчика в Shipping > Carriers после того, как у него появились заказы, PrestaShop сохраняет его как новую версию перевозчика. Модуль автоматически переходит на новую версию.

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

Заказы

Когда заказ оформляется с перевозчиком Chilexpress, модуль сохраняет, как была рассчитана его цена. На странице заказа в бэк-офисе показывается блок Chilexpress с Chilexpress service (для актуального тарифа — услуга, которую назначил Chilexpress, например Express) и Price source: Live rate (Chilexpress Rating API), Fixed price или Free shipping.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Chilexpress — первый блок на странице Modules > Module Manager > VibeFox Chilexpress > Configure, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в маскированном виде, статус (например, дату, до которой лицензия активна, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key, чтобы удалить ключ из этого магазина. Ниже них находятся строка Product: presta-shipping-chilexpress и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт на vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока соответствуют языку бэк-офиса (включены английский и русский).

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

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

Без активного ключа перевозчик Chilexpress не показывается покупателям при оформлении заказа, и тариф не рассчитывается. Витрина PrestaShop не знает, что вы вошли в бэк-офис, поэтому перевозчик скрыт и для вас: модуль можно настроить до покупки ключа, но проверить его при оформлении заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются.

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

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

Chilexpress не появляется при оформлении заказа: проверьте, что лицензия активна и включён Enable/Disable. В Shipping > Carriers проверьте, что перевозчик покрывает зону страны покупателя и его группу (или что включён Ignore shipping zones и страна указана в Countries). Проверьте ограничения по весу и Minimum subtotal. При фиксированных ценах проверьте, что для страны или * Default есть строка. Товары также могут быть ограничены определёнными перевозчиками на странице товара.

Доставка в Чили бесплатна, хотя не должна быть: строка для Чили (или * Default) в 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 в No tax.

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

На странице написано «The Chilexpress carrier was not found»: перевозчик был удалён в Shipping > Carriers. Сбросьте модуль в Modules > Module Manager, чтобы создать его заново.

На странице написано «The country Chile does not exist in this shop»: добавьте или включите Chile в International > Locations > Countries, затем используйте Add Chilean regions.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox Chilexpress и выберите Uninstall. Лицензионный ключ и статус лицензии всегда удаляются. Кешированные тарифы и списки коммун всегда удаляются. Если Remove data on uninstall включено, перевозчик удаляется (заказы сохраняют свою историю), а настройки, журнал и услуги, сохранённые с заказами, удаляются. Если выключено, перевозчик только отключается, и все настройки сохраняются. Повторная установка модуля восстанавливает сохранённого перевозчика с его прежним статусом. Регионы Чили, добавленные через Add Chilean regions, остаются в магазине.

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