VibeFox Canada Post for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Canada Post Developer Program (только для актуальных тарифов): актуальные тарифы используют Rating API Canada Post. Зарегистрируйтесь в Canada Post Developer Program на сайте Canada Post и скопируйте ключ API и номер клиента. Ключ API имеет вид username:password; Canada Post выдаёт отдельные ключи для тестовой среды (sandbox) и для рабочей среды. Также нужен канадский почтовый индекс, с которого вы отправляете. Если вы используете только фиксированные цены, ключи API не нужны.

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

Установка

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

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

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

4. Для актуальных тарифов введите имя пользователя и пароль API, номер клиента и почтовый индекс отправки. Если валюта вашего магазина по умолчанию не CAD, введите курс CAD. Заполните Country prices, если нужны фиксированные цены или запасной вариант (см. раздел «Настройка»). Нажмите Save.

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

Настройка

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

Если значение неверно, страница показывает ошибку и ничего не сохраняется: числовое поле или цена в Country prices, которые не являются числом 0 или больше (например, -1 или 12abc), курс CAD, равный 0, Min cart weight (kg) больше, чем Max cart weight (kg), или Method title длиннее 64 символов. Если единица веса или размеров вашего магазина неизвестна модулю, страница предупреждает, что веса читаются в кг (размеры в см). Укажите kg, g, lb или oz (cm, mm, m или in) в International > Localization, раздел Local units.

После сохранения страница показывает предупреждение, если настройки не могут работать как задумано: заполнено только одно из полей API username и API password, почтовый индекс отправки не является канадским (формат A1A 1A1), курс CAD не указан для магазина в другой валюте, или нет ни учётных данных API, ни фиксированных цен. Предупреждение также сообщает, что происходит в это время: используются фиксированные цены по странам или перевозчик скрывается при оформлении заказа, если таблица Country prices пуста.

Общие

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

Method title: название перевозчика, которое видит покупатель при оформлении заказа. По умолчанию: Canada Post, также если поле оставлено пустым. До 64 символов, без символов, которые PrestaShop не допускает в названиях перевозчиков.

Tax: налоговое правило, которое PrestaShop добавляет к стоимости доставки, или No tax (не облагается налогом).

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

Если заполнены имя пользователя и пароль API, цена берётся из Rating API Canada Post. Если API не возвращает тариф (API недоступен, неверный почтовый индекс, сервис недоступен), используется фиксированная цена из Country prices, или перевозчик скрывается, если её нет. Раздел содержит ссылку на Canada Post Developer Program, где вы найдёте ключи API и номер клиента. Подробности ошибок попадают в журнал и никогда не показываются покупателю.

API username: часть ключа API до двоеточия. Используйте ключ для разработки с Sandbox, а ключ для рабочей среды — на действующем магазине.

API password: часть ключа API после двоеточия. После сохранения поле остаётся пустым и показывает A password is saved. Leave empty to keep it; clear the username and save to remove both. Вводите новое значение, только если хотите его изменить. Пароль сохраняется ровно так, как введён, и никогда не записывается в журнал.

Customer number: с номером клиента Canada Post возвращает коммерческие (со скидкой) тарифы вашей учётной записи. Оставьте поле пустым для розничных (кассовых) тарифов. Пробелы удаляются.

Contract number: необязательное поле для клиентов с договором. Используется только вместе с номером клиента.

Sandbox: использует тестовую среду Canada Post для проверки с ключом API для разработки. Цены — тестовые данные. Выключите на действующем магазине.

Ship-from postal code: канадский почтовый индекс, с которого отправляются посылки, например K1A 0B1. Без него актуальные тарифы не работают.

Service in Canada: сервис для канадских адресов: Cheapest available, Regular Parcel (DOM.RP, по умолчанию), Expedited Parcel (DOM.EP), Xpresspost (DOM.XP) или Priority (DOM.PC).

Service to the USA: Cheapest available (по умолчанию), Expedited Parcel USA (USA.EP), Tracked Packet USA (USA.TP), Small Packet USA Air (USA.SP.AIR), Xpresspost USA (USA.XP) или Priority Worldwide parcel USA (USA.PW.PARCEL).

International service: Cheapest available (по умолчанию), International Parcel Surface (INT.IP.SURF), International Parcel Air (INT.IP.AIR), Tracked Packet International (INT.TP), Small Packet International Surface (INT.SP.SURF), Small Packet International Air (INT.SP.AIR), Xpresspost International (INT.XP) или Priority Worldwide parcel International (INT.PW.PARCEL).

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

Use Canada Post prices without GST/HST/PST: для канадских адресов цена Canada Post включает эти налоги. Включите, если PrestaShop сам добавляет налог к доставке (Tax выше), чтобы налог не начислялся дважды.

CAD to … rate: в названии поля указана валюта магазина по умолчанию, например CAD to USD rate. Цены Canada Post указаны в CAD. Если валюта магазина по умолчанию не CAD, введите, сколько единиц вашей валюты стоит один CAD, например 0.68. Без этого значения актуальные тарифы не используются. Если валюта магазина по умолчанию — CAD, оставьте поле пустым. Курс должен быть больше 0. В качестве десятичного разделителя принимаются и точка, и запятая.

Default product weight (kg): отправляется в Canada Post для каждого товара без веса. По умолчанию: 0.5. Веса товаров (в единице веса вашего магазина) и размеры пересчитываются, а корзина рассчитывается как одна посылка.

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

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

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

Условия

Min cart weight (kg): скрывает перевозчика при весе корзины ниже этого значения. 0 означает без ограничения.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

С учётными данными API модуль отправляет в Canada Post почтовый индекс отправки, место назначения, вес посылки и, если у каждого товара есть размеры, расчётный размер посылки. Для Канады местом назначения является почтовый индекс, для США — ZIP-код, для всех остальных стран — только страна. Актуальный тариф запрашивается, только если у адреса в Канаде или США есть действительный почтовый индекс или ZIP-код. Canada Post возвращает все сервисы для посылки. Модуль выбирает выбранный сервис для группы назначения или самый дешёвый, удаляет канадские налоги с продаж (GST/HST/PST), если включена опция Use Canada Post prices without GST/HST/PST, и пересчитывает цену в CAD по вашему курсу. Цена рассчитывается в валюте магазина по умолчанию, а затем показывается в валюте корзины покупателя.

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

Если API не возвращает тариф, используется фиксированная цена, или перевозчик скрывается, когда фиксированной цены нет. Покупатель никогда не видит подробностей ошибок API; они попадают в журнал.

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

Модуль только рассчитывает тарифы. Он не создаёт отправления, не печатает этикетки, не создаёт манифесты и возвраты и не отслеживает посылки. Покупатели не могут выбрать почтовое отделение или пункт выдачи. Модуль показывает один тариф Canada Post без дат доставки, опций страховки или подписи. Корзина всегда рассчитывается как одна посылка, а курсы валют автоматически не обновляются.

Заказы

Когда заказ оформлен с перевозчиком Canada Post, модуль сохраняет, как была рассчитана его цена. На странице заказа в панели администратора (Orders > Orders, откройте заказ) блок Canada Post показывает:

Canada Post service: название и код сервиса для актуального тарифа, например Regular Parcel (DOM.RP).

Price source: Live rate (Canada Post Rating API), Fixed price или Free shipping.

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

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

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

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

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

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

Canada Post не появляется при оформлении заказа: проверьте, что лицензия действует и включена опция Enable Canada Post. В Shipping > Carriers проверьте, что перевозчик охватывает зону страны покупателя и группу покупателя (или включена опция Ignore shipping zones и страна разрешена). Проверьте ограничения веса и Minimum order amount. Должен быть тариф: при учётных данных API адрес должен иметь действительный почтовый индекс (Канада) или ZIP-код (США); иначе должна существовать фиксированная цена для страны или для *. Кроме того, товары могут быть ограничены определёнными перевозчиками на странице товара.

Актуальные тарифы не появляются: включите Debug log, обновите оформление заказа и посмотрите панель Log на странице модуля. Там указана причина: отсутствует имя пользователя или пароль API, неверный почтовый индекс отправки или назначения, отсутствует курс CAD, посылка весом более 30 кг или сообщение об ошибке Canada Post. Тем временем покупатели получают фиксированную цену, если она есть.

Тариф отличается от сайта Canada Post: с номером клиента вы получаете коммерческие (со скидкой) тарифы вашей учётной записи; без него — розничные (кассовые) тарифы. Для канадских адресов цена Canada Post включает GST/HST/PST. Цены конвертируются по вашему курсу CAD.

Налог на доставку взимается дважды: включите Use Canada Post prices without GST/HST/PST или установите Tax в No tax.

Проверка цен на действующем магазине: выключите Sandbox и используйте ключ API для рабочей среды.

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

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

У вас нет прав на настройку этого модуля: ваш профиль сотрудника может открыть страницу модуля, но не может её сохранить. Попросите администратора дать вашему профилю право на настройку модуля.

Удаление

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

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