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

Требования

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

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

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

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

Установка

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

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

Настройка

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

Если значение неверно, страница показывает ошибку и ничего не сохраняется: числовое поле или цена в Country prices, которая не является числом не меньше 0 (например, -1 или 12abc), курс CAD, равный 0, Min cart weight (kg) больше, чем Max cart weight (kg), Method title длиннее 64 символов или содержащий символы < > ; = # { }, Sort order, который не является целым числом, или неизвестный налоговый класс или геозона. Если в магазине нет весового класса с единицей «kg» или линейного класса с единицей «cm», страница предупреждает, что веса и габариты пересчитываются по названию единицы их класса (kg, g, lb, oz; cm, mm, m, in), а остальные единицы читаются как кг или см.

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

Общие

Настройки применяются ко всем геозонам. Цена всегда берётся из этого расширения: живой тариф Canada Post или фиксированные цены по странам.

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

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

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

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

API Canada Post (живые тарифы)

Если заполнены имя пользователя и пароль API, цена берётся из Canada Post Rating API. Если 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 API 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: сервис для канадских адресов: самый дешёвый доступный, Regular Parcel (DOM.RP, по умолчанию), Expedited Parcel (DOM.EP), Xpresspost (DOM.XP) или Priority (DOM.PC).

Service to the USA: самый дешёвый доступный (по умолчанию), 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: самый дешёвый доступный (по умолчанию), 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 включает эти налоги. Включите, когда OpenCart сам добавляет налог на доставку (Tax class выше), чтобы налог не начислялся дважды.

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

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

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

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

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

Условия

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

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

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

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

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

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

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

Обычно способ доставки предлагается в геозоне, выбранной в Conditions.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Заказы

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

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

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

В OpenCart 4 блок показывается над History. Оформление заказа сохраняет одну запись на заказ: когда покупатель повторно подтверждает заказ, сохранённые сервис и источник цены заменяются, а если покупатель выбрал другой способ доставки, они удаляются.

Сервис не добавляется в письма о заказе и на страницу заказов покупателя; там показываются название способа доставки и стоимость доставки, как для любого другого способа доставки OpenCart.

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

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

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

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

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

Canada Post не появляется при оформлении заказа: проверьте, что лицензия активна и включено Enable Canada Post. Проверьте Geo zone или то, что включено Ignore shipping zones и страна разрешена. Проверьте ограничения по весу и Minimum order amount, а также что у товаров Requires Shipping установлено в Yes. Тариф должен существовать: с учётными данными 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 class в No tax.

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

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

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

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

Удаление

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

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

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