VibeFox The Courier Guy for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Ключ API ShipLogic (для тарифов в реальном времени и постаматов): The Courier Guy работает на платформе ShipLogic. Создайте ключ API в курьерском портале The Courier Guy в разделе Settings > API Keys (бизнес-аккаунт). Без ключа используется только таблица цен, и перевозчик-постамат не предлагается.

Доставка в ЮАР: тарифы в реальном времени и постаматы — только для адресов в ЮАР. ЮАР должна быть активной страной магазина (International > Locations > Countries).

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

Установка

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

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

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

4. Введите API key ShipLogic. Для тарифов в реальном времени заполните адрес отправителя (улица, город, провинция, почтовый индекс) и, если валюта вашего магазина не ZAR, — ZAR conversion rate.

5. Заполните таблицу цен и/или резервную стоимость и нажмите Save.

6. Для тарифов курьера в реальном времени нажмите Add South African provinces в разделе Advanced, если страница сообщает, что у адресов ЮАР нет провинции.

При установке модуль создаёт два перевозчика: The Courier Guy (текст срока доставки The Courier Guy courier delivery to your door) и The Courier Guy locker (Delivery to a TCG locker of your choice). Оба активны, привязаны к зоне ЮАР и ко всем группам клиентов. Зоны, группы клиентов, срок доставки, логотип и ограничения по размеру можно изменить в Shipping > Carriers. Цены там не задавайте: цена всегда берётся из модуля.

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox The Courier Guy > Configure. У каждого раздела своя кнопка Save, которая сохраняет всю страницу. Каждое сохранение очищает кэш тарифов и постаматов и последнюю ошибку ShipLogic. Предупреждения вверху страницы сообщают, если ЮАР не является активной страной магазина, нет ключа API, курса ZAR или адреса отправителя, не задана ни таблица цен, ни резервная стоимость, у адресов ЮАР нет провинции, модуль не знает единицу веса или размеров магазина, либо последний запрос к ShipLogic завершился ошибкой (с датой и текстом ошибки). Некорректное число (например, отрицательное) не сохраняется: страница называет поле и оставляет прежнее значение.

Общие

Courier to the door: включает или выключает курьерского перевозчика. Это тот же переключатель, что и статус перевозчика в Shipping > Carriers.

Courier carrier name: название курьерского перевозчика на этапе оформления заказа. По умолчанию: The Courier Guy. Обязательно.

TCG locker: включает или выключает перевозчика-постамат. Покупатель выбирает постамат при оформлении заказа. Он предлагается только для адресов в ЮАР и только при наличии ключа API ShipLogic.

Locker carrier name: название перевозчика-постамата на этапе оформления заказа. По умолчанию: The Courier Guy locker. Обязательно.

Tax status: налоговое правило обоих перевозчиков. Taxable: <tax rule>: тарифы в реальном времени берутся без НДС, а PrestaShop добавляет налог на доставку по выбранному правилу. None: тарифы в реальном времени берутся с НДС.

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

API key: ваш ключ API ShipLogic из портала The Courier Guy. Он никогда не показывается покупателям и не записывается в журнал. После сохранения поле остаётся пустым и показывает Saved - leave empty to keep it. Вводите новое значение, только если хотите его изменить. Отметьте Remove the saved API key и сохраните, чтобы удалить ключ.

Account ID: необязательно. Числовой ID аккаунта ShipLogic, только если ваш ключ имеет доступ к нескольким аккаунтам. Значение, которое не является числом, не сохраняется.

Тарифы в реальном времени (для адресов в ЮАР; если тариф в реальном времени недоступен, используется таблица цен)

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

ZAR conversion rate: ShipLogic считает в южноафриканских рандах (ZAR). Если основная валюта вашего магазина не ZAR, укажите, сколько стоит 1 ZAR в вашей валюте, например 0.05. Без этого тарифы в реальном времени не используются и действует таблица цен. Если валюта магазина — ZAR, оставьте поле пустым. Курс не обновляется автоматически.

Адрес отправителя (для тарифов в реальном времени) (откуда The Courier Guy забирает посылки в ЮАР; для тарифов в реальном времени нужны улица, город, провинция и почтовый индекс)

Sender company: название вашей компании.

Sender street address: например, 12 My Road.

Sender suburb: район адреса отправителя.

Sender city: город адреса отправителя.

Sender province: выберите провинцию ЮАР из списка.

Sender postal code: почтовый индекс адреса отправителя.

Таблица цен (ваши цены в основной валюте магазина, без налогов: используется с Price table only, вне ЮАР и всякий раз, когда тариф в реальном времени недоступен; допускаются десятичная запятая или точка)

Calculation type: относится только к таблице цен. Тариф в реальном времени всегда считается на весь заказ.

Prices by weight: таблица стран с колонкой Price и весовыми категориями XS (до 1 кг), S (до 2 кг), M (до 3 кг), L (до 5 кг) и XL (более 5 кг). Нажмите Add row, чтобы добавить строку (новая строка начинается с ЮАР), и значок корзины, чтобы удалить строку. Пустая или нулевая категория использует колонку Price. Цена 0 означает бесплатную доставку. Строка * Any country применяется к странам без собственной строки и к строке страны без цены. Цена, которая не является числом, очищается, и страница перечисляет такие цены.

Fallback cost: используется, когда нет ни тарифа в реальном времени, ни цены из таблицы. Оставьте поле пустым, чтобы в этом случае скрывать перевозчиков.

Условия (оба перевозчика)

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

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

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

Free shipping from: сумма корзины, начиная с которой доставка бесплатна. Оставьте поле пустым, чтобы никогда не предлагать бесплатную доставку. Когда сумма достигает этого значения, перевозчики показываются с ценой 0, и запрос к ShipLogic за тарифом не отправляется.

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

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

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

Delivery type without zones: Courier to the door или TCG locker (customer chooses a locker). Используется только вместе с Ignore shipping zones.

Countries: страны назначения для этого режима. Оставьте пустым, чтобы разрешить все страны. Постаматы предлагаются только в ЮАР.

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

South African provinces: в PrestaShop нет провинций ЮАР, но тариф курьера в реальном времени требует провинцию адреса. Add South African provinces добавляет 9 провинций (EC, FS, GP, KZN, LP, MP, NC, NW, WC) как регионы ЮАР и показывает поле региона в адресах ЮАР. Уже существующие провинции повторно не добавляются. До этого курьер получает цену из таблицы.

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

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

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

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

На шаге доставки PrestaShop запрашивает у модуля цену каждого перевозчика. Учитываются только физические товары: виртуальные товары не добавляют вес и не входят в сумму заказа. Модуль сначала проверяет условия: вес корзины и минимальную сумму заказа. Если действует бесплатная доставка, цена равна 0.

Courier to the door: модуль запрашивает у ShipLogic самый дешёвый сервис от адреса вашего отправителя до адреса покупателя. В адресе должны быть улица, город, провинция и почтовый индекс. До тех пор используется таблица цен.

TCG locker: тариф в реальном времени — самый дешёвый сервис «от двери до постамата» до постамата, ближайшего к городу покупателя. Он не пересчитывается для постамата, который выбрал покупатель. Перевозчик-постамат появляется только для адресов в ЮАР и только при наличии ключа API.

Весь заказ рассчитывается как одна посылка: общий вес, наибольшие длина и ширина и суммарная высота. Товары без размеров считаются кубами 10 см. Вес и размеры переводятся из единиц измерения вашего магазина. Сумма в рандах пересчитывается в основную валюту магазина, а затем показывается в валюте корзины покупателя.

Запросы к ShipLogic прерываются через 12 секунд. Тарифы кэшируются на 1 час, постаматы на 6 часов, ошибки на 10 минут, чтобы медленный API не замедлял каждое обновление оформления заказа. Если тарифа в реальном времени нет, цена берётся из таблицы, затем из Fallback cost. Если ни одно из этих значений не применимо, перевозчик скрывается. Ошибки API никогда не показываются покупателю.

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

Модуль не создаёт отправления, накладные или этикетки и не обновляет отслеживание автоматически. Карты постаматов нет: постаматы выбираются из списка. Тарифы в реальном времени и постаматы — только для ЮАР. Для других стран используется таблица цен. Для каждого перевозчика показывается только один тариф (самый дешёвый уровень сервиса), без выбора уровней сервиса, страховки или дополнительных услуг при оформлении заказа.

Пункты выдачи

Когда покупатель выбирает перевозчика-постамат, под ним появляется селектор постаматов. Он показывает постаматы, которые ShipLogic возвращает для города адреса доставки, сначала ближайшие. Покупатель может ввести другой город, район или почтовый индекс и нажать Search. Постамат нужно выбрать до того, как покупатель сможет продолжить: иначе на шаге доставки появится сообщение Please choose a The Courier Guy locker.

Постамат повторно проверяется на сервере по списку ShipLogic, в том числе при оформлении заказа. Его название и поставщик берутся из ShipLogic, никогда из браузера. Выбор сохраняется для корзины и сбрасывается при изменении адреса доставки.

Если ShipLogic недоступен, селектор сообщает, что постаматы не удалось загрузить, и что магазин свяжется с покупателем по поводу постамата. Заказ тогда можно оформить без постамата. Такой заказ помечается на странице заказа в админке: Not chosen - ShipLogic was unavailable at checkout. Agree the locker with the customer.

Заказы

Выбранный постамат (название, ID и поставщик) сохраняется вместе с заказом. Он показывается в блоке The Courier Guy на странице заказа в админке, на странице подтверждения заказа, в деталях заказа покупателя и в письме с подтверждением заказа. Письмо магазина о новом заказе (модуль Mail alerts) тоже показывает ID постамата или сообщает, что постамат не выбран, потому что ShipLogic был недоступен.

Номер отслеживания The Courier Guy: оформите посылку в личном кабинете The Courier Guy и укажите референс как номер отслеживания отправления в блоке Shipping заказа (Edit). Блок The Courier Guy показывает его. Покупатель видит его в деталях заказа и получает письмо PrestaShop «в пути».

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

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

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

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

Без активного ключа ни один из перевозчиков The Courier Guy (courier to the door или TCG locker) не показывается покупателям при оформлении заказа, и тариф не рассчитывается. Витрина PrestaShop не знает, что вы вошли в back office, поэтому перевозчики скрыты и для вас: модуль можно настроить до покупки ключа, но проверить его на этапе оформления заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются.

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

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

The Courier Guy не появляется при оформлении заказа: проверьте, что лицензия активна и перевозчик включён (Courier to the door или TCG locker). В Shipping > Carriers проверьте, что перевозчик охватывает зону страны покупателя и группу покупателя (или что включён Ignore shipping zones и страна разрешена). Проверьте ограничения по весу и Minimum order amount. Убедитесь, что в таблице или в Fallback cost есть цена. Перевозчик-постамат появляется только для адресов в ЮАР и при наличии ключа API. Кроме того, на странице товара товары могут быть ограничены определёнными перевозчиками.

Покупатели не видят список постаматов: для постаматов нужны ключ API, включённый перевозчик TCG locker и адрес доставки в ЮАР. На странице настроек показана последняя ошибка ShipLogic, если она есть, например отклонённый ключ.

Цена всегда из таблицы: проверьте предупреждения на странице настроек. Тариф в реальном времени требует ключ API, полный адрес отправителя и для магазинов не в рандах — курс ZAR. Для доставки курьером адрес покупателя должен содержать улицу, город, провинцию и почтовый индекс: добавьте провинции ЮАР в разделе Advanced. Для постаматов ShipLogic должен найти постамат рядом с городом покупателя. Включите Debug log, обновите оформление заказа и посмотрите поле Log на странице модуля.

ShipLogic недоступен: показывается цена из таблицы или резервная стоимость. Заказы с постаматом можно оформить без постамата, и они помечаются в заказе.

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

Страница сообщает, что перевозчик The Courier Guy не найден: перевозчик был удалён в Shipping > Carriers. Сбросьте модуль в Modules > Module Manager, чтобы создать его заново. Сброс сохраняет ваши настройки и статус включения существующих перевозчиков.

Удаление

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

The Courier Guy и ShipLogic являются торговыми марками их владельцев. Этот модуль не связан с The Courier Guy или ShipLogic и не одобрен ими.