VibeFox Purolator for OpenCart — Помощь

Требования

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

PHP: 8.0 или новее, с расширением cURL. Расширение SOAP для PHP не требуется.

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

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

Установка

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

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

Настройка

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

Если актуальные тарифы не могут работать с сохранёнными значениями (нет ключа, пароля или платёжной учётной записи, нет канадского почтового индекса отправления, нет курса CAD) либо нет ни API-данных, ни фиксированных цен, в разделе General появляется предупреждение. Оно также сообщает, используются ли до этого фиксированные цены или способ скрыт. Предупреждение появляется и тогда, когда единица веса магазина не известна расширению. В этом случае веса товаров считаются в кг; добавьте весовой класс с единицей kg в System > Localisation > Weight Classes.

Числовое поле, которое не содержит число от 0 и выше, не сохраняется. Сообщение после Save называет поле и значение. Поле остаётся пустым или получает значение по умолчанию для полей веса. Неверное значение в Country prices сохраняется как 0, а сообщение называет страну и столбец. Ничего не сохраняется и показывается ошибка, если название способа пустое или длиннее 64 символов, если Min cart weight (kg) больше Max cart weight (kg), если порядок сортировки не является целым числом или если налоговый класс или геозона недопустимы.

Общее

Покупатель видит один тариф Purolator. Настройки действуют для всех геозон. Способ можно ограничить геозоной или странами в Availability.

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

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

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

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

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

Когда API-ключ, пароль и платёжная учётная запись заполнены, цена берётся из веб-службы Purolator E-Ship Estimating (Quick Estimate, по общему весу корзины). Если 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) с ключом для разработки. Цены — тестовые данные. Выключите это на рабочем магазине.

Ship-from postal code: канадский почтовый индекс, с которого отправляются посылки, например L4W 5M8. В OpenCart нет почтового индекса магазина, поэтому он не берётся из адреса магазина: введите его здесь.

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 включает эти налоги. Включайте, когда магазин сам добавляет налог к доставке (налоговый класс в General), чтобы налог не начислялся дважды. По умолчанию: выключено.

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

Default product weight (kg): используется для каждого товара без веса. По умолчанию: 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 x quantity) умножает её на количество товаров в корзине. Это относится только к фиксированным ценам. Актуальные тарифы всегда рассчитываются на всё отправление.

Условия

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

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

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

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

Доступность

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

Ignore shipping zones: предлагает способ для стран, указанных ниже, независимо от выбранной геозоны.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Заказы

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

OpenCart 4 ведёт один заказ на оформление и обновляет его каждый раз, когда покупатель подтверждает заказ снова. Сохранённая служба Purolator обновляется вместе с ним до последнего актуального тарифа. Если заказ переводится на другой способ доставки или на цену без актуального тарифа, сохранённая служба удаляется из заказа.

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

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

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

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

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

Purolator не появляется при оформлении заказа: проверьте, что лицензия активна и включено Enable Purolator. Проверьте Geo zone (или что включён Ignore shipping zones и страна разрешена), ограничения веса и Minimum order amount. Если Purolator не возвращает тариф, способ показывается только при наличии цены по стране, строки * или Fallback price. Проверьте, что у товаров Requires Shipping установлено в Yes.

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

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

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

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

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

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

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

Удаление

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

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

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