VibeFox UPS for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Приложение в UPS Developer Portal (только для тарифов в реальном времени): войдите в UPS Developer Portal (developer.ups.com), создайте приложение с продуктом «Rating», привяжите свою учётную запись UPS и скопируйте Client ID и Client Secret. Модуль использует OAuth 2.0. Access Key, имя пользователя и пароль не нужны. Для согласованных тарифов также понадобится ваш 6-значный номер учётной записи UPS. Без учётных данных используются только фиксированные цены.

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

Установка

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

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

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

4. Введите Client ID и Client Secret, номер вашей учётной записи UPS (для согласованных тарифов) и адрес Ship from: почтовый индекс и, для США и Канады, двухбуквенный код штата.

5. Если валюта вашей учётной записи UPS отличается от валюты магазина по умолчанию, введите UPS account currency и Exchange rate.

6. По желанию введите фиксированные цены как запасной вариант и нажмите Save.

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

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox UPS > Configure. Они действуют для всех зон перевозчика. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Каждое сохранение очищает кэш токена и тарифов UPS. Также можно нажать Clear cached UPS token and rates в разделе UPS API.

Предупреждения над настройками сообщают, что заполнено только одно из полей Client ID и Client Secret, что нет ни учётных данных, ни фиксированных цен (тогда перевозчик никогда не показывается), что не указан почтовый индекс или код штата отправителя, что выбраны тарифы по учётной записи без её номера, что нет курса обмена или что модуль не распознаёт единицу веса или размеров магазина. Некорректные числа, неверный размер коробки и Min weight больше Max weight выводятся при сохранении, а старое значение сохраняется.

Общие

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

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

Tax status: правило налогообложения перевозчика или None. Тарифы UPS указываются без налогов. С правилом налогообложения магазин добавляет свой налог на доставку сверху.

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

Test mode: использовать тестовую среду UPS. Тестовые тарифы не являются реальными ценами. Выключите для получения реальных тарифов. По умолчанию: off.

Client ID: Client ID вашего приложения в UPS Developer Portal. Его очистка также удаляет сохранённый Client Secret.

Client Secret: Client Secret того же приложения. После сохранения поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

UPS account number: ваш 6-значный номер отправителя UPS, например A1B2C3. Нужен для тарифов по учётной записи (согласованных), для публичных тарифов необязателен.

Rates: какие цены UPS используются.

Measurement units: единицы, отправляемые в UPS. Веса и размеры магазина пересчитываются.

Residential delivery: рассчитывать адреса покупателей как жилые, с жилищной надбавкой UPS. Выключите, если отправляете в основном организациям. По умолчанию: on.

Box size: необязательные размеры коробки в единице размеров вашего магазина, например 30x20x15. Тогда UPS применяет объёмный вес. Оставьте пустым, чтобы считать только по весу.

UPS account currency: UPS считает в валюте страны учётной записи отправителя, например USD для США, CAD для Канады или EUR для еврозоны. По умолчанию: USD.

Exchange rate: нужен, только если валюта учётной записи UPS отличается от валюты магазина по умолчанию. Введите цену 1 единицы валюты учётной записи в валюте магазина по умолчанию, например 0.92. Без него такие тарифы не используются и действуют фиксированные цены. Курсы обмена автоматически не обновляются.

Адрес отправления (адрес, откуда UPS забирает посылки или куда вы их сдаёте; используется для тарифов в реальном времени)

Country: страна, из которой вы отправляете. По умолчанию — страна вашего магазина.

State / province code: двухбуквенный код, обязательный для США и Канады, например NY, CA или ON.

City: город, из которого вы отправляете.

ZIP / postal code: почтовый индекс, по которому вы отправляете. UPS требует его для расчёта тарифов.

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

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

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

Fixed price is: Per order взимает цену один раз, по весу всей корзины. Per item (each item priced by its own weight x quantity) рассчитывает каждый товар по его собственному весу (вес по умолчанию, если его нет) и умножает на количество. Если у одного товара нет фиксированной цены, перевозчик скрывается. Тарифы UPS в реальном времени всегда рассчитываются по общему весу корзины.

Условия

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

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

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

Max weight: перевозчик скрывается при весе корзины выше этого значения в кг. По умолчанию: 70, ограничение UPS на одно место (70 кг / 150 lbs). 0 означает без ограничения, пустое значение означает 70. Min weight не может быть больше Max weight.

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

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

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

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

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

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

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

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

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

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

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

Модуль получает токен OAuth от UPS и хранит его до истечения срока. Токен, который отклоняет UPS, обновляется автоматически. Затем модуль запрашивает у UPS Rating API все услуги от вашего адреса отправления до адреса покупателя, для корзины как одного места. Для стран с почтовыми индексами запрос ждёт, пока покупатель введёт индекс. Для отправлений из США в Канаду или Пуэрто-Рико передаётся стоимость товаров, как требует UPS.

Покупатель видит один вариант с самой дешёвой услугой UPS. Цена рассчитывается в валюте магазина по умолчанию, затем показывается в валюте корзины покупателя. UPS Access Point Economy не рассчитывается, потому что модуль не собирает адрес Access Point.

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

Если UPS не возвращает тариф (API недоступен, неверные учётные данные, нет услуги, другая валюта без курса обмена), цена берётся из Country prices, затем из Fallback cost. Если ни одно не подходит, перевозчик скрывается. Покупатель никогда не видит текстов ошибок UPS.

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

Модуль только рассчитывает тарифы. Он не предлагает выбор UPS Access Point, не создаёт этикетки и отправления UPS, не заказывает курьера и не отслеживает посылки. Он показывает один вариант, а не несколько услуг UPS. Упаковки в коробки нет: корзина рассчитывается как одно место. Курсы обмена не обновляются автоматически.

Заказы

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

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

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

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

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

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

UPS не появляется при оформлении заказа: проверьте, что лицензия активна и включён Enable UPS shipping. В Shipping > Carriers проверьте, что перевозчик охватывает зону страны покупателя и группу клиентов, или включите Ignore shipping zones и проверьте Countries. Проверьте ограничения по весу и Minimum subtotal. Без рабочих учётных данных UPS перевозчику нужна фиксированная цена (Country prices или Fallback cost). Кроме того, товары можно ограничить определёнными перевозчиками на странице товара.

Тарифы в реальном времени не появляются: проверьте предупреждения вверху страницы Configure. Включите Debug log, перезагрузите оформление заказа и посмотрите поле Log на странице модуля. Там видны ошибки OAuth (проверьте Client ID, Client Secret и Test mode), сообщения об ошибках UPS и проблемы с валютой.

Тариф в USD, а магазин — нет: UPS возвращает тарифы в валюте учётной записи отправителя. Задайте UPS account currency и Exchange rate. Без курса обмена такие тарифы игнорируются и используется фиксированная цена.

«This measurement system is not valid for the selected country»: оставьте Measurement units в значении Automatic или выберите единицы, которые UPS ожидает для страны отправления.

Страница предупреждает, что единица веса или размеров магазина неизвестна: тогда веса читаются как кг, а размер коробки — как см. Задайте стандартную единицу (kg, g, lb или oz; cm, mm, m или in) в International > Localization, раздел Local units.

Тарифы выглядят устаревшими после изменения: нажмите Save на странице модуля или Clear cached UPS token and rates.

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

Для разработчиков: хуки actionVfdUpsxAllowedServices и actionVfdUpsxExcludedServices ограничивают услуги UPS, которые могут показываться. actionVfdUpsxRateRequest меняет запрос тарифа, actionVfdUpsxApiBaseUrl — адрес API, а actionVfdUpsxCurrencyCodes сопоставляет коды валют, которые возвращает UPS.

Удаление

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

UPS — торговая марка её владельца. Модуль не связан с UPS и не одобрен UPS.