VibeFox Purolator for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более старых версиях PHP. Расширение PHP SOAP не требуется.

Purolator E-Ship Web Services (только для тарифов в реальном времени): зарегистрируйтесь в E-Ship Web Services в Purolator E-Ship Resource Centre на сайте Purolator. Purolator выдаёт отдельные ключи и пароли для окружений разработки и производства. Также понадобятся номер вашей расчётной учётной записи Purolator и канадский почтовый индекс, с которого вы отправляете. Если вы используете только фиксированные цены, ключи API не нужны.

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

Установка

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

2. По окончании загрузки нажмите Configure или позже найдите VibeFox Purolator в списке модулей и нажмите Configure.

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

4. Для тарифов в реальном времени заполните раздел Purolator API (live rates). Для тестирования включите Development environment и укажите ключ разработки. Заполните Country prices или Fallback price, если нужны фиксированные цены или запасная цена (см. Настройка). Нажмите Save.

При установке модуль создаёт перевозчика Purolator с текстом срока доставки Purolator courier. Перевозчик назначается всем зонам и всем группам клиентов. Зоны, группы клиентов, срок доставки, логотип и ограничения размеров можно изменить в Shipping > Carriers. Не задавайте там цены: цена всегда берётся из модуля.

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Purolator > Configure. У каждого раздела своя кнопка Save, которая сохраняет всю страницу. Каждое сохранение также очищает кэш тарифов Purolator.

Если тарифы в реальном времени не могут работать с сохранёнными значениями (нет ключа, пароля или расчётной учётной записи, нет канадского почтового индекса отправления, нет курса CAD) или не задано ни учётных данных API, ни фиксированных цен, над настройками появляется предупреждение. Предупреждение появляется и тогда, когда единица измерения веса магазина не входит в число известных модулю (kg, g, lb, oz и подобные). Тогда вес товаров считается в килограммах. Задайте единицу веса в International > Localization (Local units).

Поле с числом, которое не равно 0 или больше, не сохраняется. Предупреждение называет поле и значение. Поле остаётся пустым или, для полей веса, получает значение по умолчанию. Неверное значение в Country prices сохраняется как 0, а предупреждение указывает страну и колонку. Если Min cart weight больше Max cart weight, ничего не сохраняется и выводится ошибка.

Общие

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

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

Tax: налоговое правило перевозчика или No tax. Оно определяет, добавляет ли магазин налог к стоимости доставки. Для канадских адресов итог Purolator уже включает GST/HST/PST/QST. См. Canadian sales taxes ниже.

API Purolator (тарифы в реальном времени)

Когда заполнены ключ API, пароль и расчётная учётная запись, цена берётся из веб-сервиса Purolator E-Ship Estimating. Если Purolator не возвращает тариф, используется фиксированная цена, или перевозчик скрывается, если её нет. В разделе есть ссылка на Purolator E-Ship Resource Centre, где вы регистрируетесь и получаете ключи.

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

API password: пароль, соответствующий ключу. Как и ключ, после сохранения он больше не показывается.

Billing account number: номер вашей учётной записи Purolator. Оценки используют тарифы этой учётной записи. Окружение разработки принимает тестовую учётную запись из документации Purolator. Очистка этого поля также удаляет сохранённые ключ и пароль API.

Development environment: использует окружение разработки Purolator (devwebservices.purolator.com) с ключом разработки. Цены — тестовые данные. Выключите его на рабочем магазине.

Ship-from postal code: канадский почтовый индекс, с которого отправляются посылки, например L4W 5M8.

Service in Canada: Cheapest available (по умолчанию), Purolator Ground, Purolator Ground 9AM, Purolator Ground 10:30AM, Purolator Ground Evening, Purolator Express, Purolator Express 9AM, Purolator Express 10:30AM, Purolator Express 12PM или Purolator Express Evening.

Service to the USA: Cheapest available (по умолчанию), Purolator Ground U.S., Purolator Express U.S., Purolator Express U.S. 9AM, Purolator Express U.S. 10:30AM или Purolator Express U.S. 12:00.

International service: Cheapest available (по умолчанию), Purolator Express International, Purolator Express International 9AM, Purolator Express International 10:30AM или Purolator Express International 12:00.

Если выбранная служба не предлагается для адреса, используется самая дешёвая доступная.

Canadian sales taxes: использовать цены Purolator без GST/HST/PST/QST. Для канадских адресов итог Purolator включает эти налоги. Включите, когда у перевозчика есть налоговое правило в Tax, чтобы налог не начислялся дважды.

CAD → (shop currency) rate: цены Purolator указаны в CAD. Если валюта магазина по умолчанию не CAD, укажите, сколько единиц вашей валюты стоит один CAD, например 0.68. Без этого значения тарифы в реальном времени не используются. Если валюта по умолчанию — CAD, оставьте поле пустым.

Default product weight: в кг, используется для каждого товара без веса. По умолчанию: 0.5. Веса пересчитываются из единицы веса магазина и отправляются в Purolator как общий вес в целых фунтах с округлением вверх.

Фиксированные цены (используются без учётных данных API, а также как запасной вариант, когда API не возвращает тариф)

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

Fallback price: цена для страны, у которой нет строки в Country prices и строки *. Оставьте поле пустым, чтобы скрыть перевозчика для таких стран.

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

Условия

Min cart weight: в кг; скрывает перевозчика, если корзина весит меньше. 0 означает без ограничения.

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

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

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

Для этих условий товары без веса учитываются как 0.

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

Обычно перевозчик предлагается в зонах, к которым он назначен в Shipping > Carriers.

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

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

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

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

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

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

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

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

При наличии учётных данных API модуль отправляет в Purolator запрос Quick Estimate: вашу расчётную учётную запись, почтовый индекс отправления, город, область или штат покупателя, страну и почтовый индекс, а также общий вес корзины в целых фунтах. Для Канады нужен корректный почтовый индекс, для США — корректный ZIP-код; другие страны отправляются с почтовым индексом в том виде, в котором он введён. Габариты (объёмный вес) не отправляются. Purolator отвечает на французском или английском языке в зависимости от языка покупателя. Purolator возвращает цены всех служб; модуль берёт выбранную службу или самую дешёвую, убирает канадские налоги с продаж, если это настроено, и пересчитывает цену из CAD. Цена рассчитывается в валюте магазина по умолчанию, а затем показывается в валюте корзины покупателя.

Каждый ответ кэшируется на 1 час. Неудачный запрос кэшируется на 10 минут, чтобы сбой Purolator не замедлял каждое обновление страницы оформления заказа. Тайм-аут API — 10 секунд.

Если Purolator не возвращает тариф (API недоступен, неверные учётные данные или почтовый индекс, служба недоступна, нет курса CAD), покупатель не видит ошибки. Используется фиксированная цена, или перевозчик скрывается, если фиксированной цены нет. Причина записывается в журнал.

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

Модуль только рассчитывает тарифы. Он не создаёт отправления Purolator, не печатает этикетки, не заказывает курьера, не обрабатывает возвраты и не отслеживает посылки. Он не использует Full Estimate (габариты, несколько мест, опции вроде подписи или опасных грузов), не показывает сроки доставки, не выводит несколько служб как отдельных перевозчиков и не загружает курсы валют автоматически.

Заказы

Когда заказ оформлен с тарифом Purolator в реальном времени, служба сохраняется вместе с заказом. Последующие пересчёты корзины её не меняют. На странице заказа в административной панели (Orders > Orders, откройте заказ) блок Purolator показывает Purolator service (название и код) и Live rate (excl. tax). У заказов с фиксированными ценами или с бесплатной доставкой такого блока нет.

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

Модуль работает с лицензионным ключом VibeFox, полученным на vibefox.net. Блок лицензии License — VibeFox Purolator — первый блок на странице Modules > Module Manager > VibeFox Purolator > Configure, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой лицензия действует, и ваш домен) и кнопки Check now, чтобы снова проверить статус, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить ключ из этого магазина. Ниже находятся строка Product: presta-shipping-purolator и ссылка 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.

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

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

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

Purolator не появляется при оформлении заказа: проверьте, что лицензия действует и включён Enable Purolator. В Shipping > Carriers проверьте, что перевозчик покрывает зону страны покупателя и группу покупателя (или что включён Ignore shipping zones и страна разрешена). Проверьте ограничения веса и Minimum order amount. Если Purolator не возвращает тариф, перевозчик показывается только при наличии цены по стране, строки * или Fallback price. Товары также можно ограничить определёнными перевозчиками на странице товара.

Тарифы в реальном времени не появляются: посмотрите поле Log на странице модуля. Ошибки API всегда там. Включите Debug log и обновите страницу оформления заказа, чтобы увидеть подробности. При использовании ключей API адрес должен содержать корректный почтовый индекс (Канада) или ZIP-код (США). Проверьте также предупреждения над настройками.

HTTP 401 в журнале: ключ или пароль API не соответствует выбранному окружению. Ключи разработки работают только при включённом Development environment, рабочие ключи — только при выключенном.

Тариф отличается от сайта Purolator: Quick Estimate использует тарифы вашей расчётной учётной записи и общий вес, округлённый вверх до целых фунтов, без объёмного веса. Для канадских адресов итог включает налоги с продаж; используйте Canadian sales taxes, если у перевозчика есть налоговое правило. Цены пересчитываются по вашему CAD → (shop currency) rate.

Значение пропало после сохранения: прочитайте предупреждение, которое появляется после Save. Значение не было числом 0 или больше, поэтому не сохранилось. Введите его снова как обычное число.

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

На странице сказано, что перевозчик Purolator не найден: перевозчик был удалён в Shipping > Carriers. Сбросьте модуль в Modules > Module Manager, чтобы создать его снова.

Удаление

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

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