VibeFox UPS for OpenCart — Помощь

Требования

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

PHP: 8.0 или новее, с расширением 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. Один ключ работает на одном домене.

Установка

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

OpenCart 3

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

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

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

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

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

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

7. При необходимости введите фиксированные цены как запасной вариант, включите Enable UPS shipping и нажмите Save.

OpenCart 4

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

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

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

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

После установки способ остаётся выключенным, пока вы не включите Enable UPS shipping и не сохраните настройки. Страна Ship from изначально совпадает со страной магазина. Если вы установите расширение повторно после удаления, сохранённые настройки UPS снова будут использованы.

Настройка

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

Если название, налоговый класс, порядок сортировки или геозона некорректны, ничего не сохраняется, и страница показывает причину, например Enter a valid name (64 characters max, without < > ; = # { }). Nothing was saved. Некорректные числа (например, отрицательные), неверный размер коробки, Min weight (kg) больше Max weight (kg) и ячейки цен, которые не являются числами, сообщаются при сохранении: это поле сохраняет старое значение, а остальное сохраняется. Предупреждения над настройками сообщают, если заполнен только один из полей Client ID и Client Secret, нет ни учётных данных, ни фиксированных цен (тогда способ никогда не показывается), не указан почтовый индекс или штат отправки, выбраны тарифы аккаунта без номера аккаунта, не задан курс обмена или расширение не распознаёт единицу веса или длины магазина.

Общие

Настройки применяются ко всем геозонам. UPS предлагается как один вариант доставки на этапе оформления заказа.

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

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

Tax class: налоговый класс стоимости доставки или None (по умолчанию). Тарифы UPS указываются без налогов. При налоговом классе OpenCart добавляет свой налог на доставку.

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

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

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

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. Выключите, если вы отправляете в основном компаниям. По умолчанию: включено.

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

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

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

Cache: токены UPS кэшируются до истечения срока (но не дольше времени жизни кэша OpenCart), тарифы — на 1 час, неудачные запросы — на 5–10 минут. Нажмите Clear cached UPS token and rates, чтобы сразу очистить кэш.

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

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

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

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

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

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

Country prices: цены в валюте магазина по умолчанию, без налогов, по стране назначения. Нажмите Add country, чтобы добавить строку, и кнопку удаления, чтобы удалить строку. * Default (all other countries) применяется к любой другой стране. Колонка веса (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 (kg): минимальный вес корзины, при котором появляется этот способ. 0 означает без ограничения (по умолчанию).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Заказы

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

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

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

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

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

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

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

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

UPS does not appear at checkout: проверьте, что лицензия активна и включён Enable UPS shipping. Проверьте Geo zone или включите Ignore shipping zones и проверьте Countries. Проверьте ограничения по весу и Minimum subtotal. Без рабочих учётных данных UPS способу нужна фиксированная цена (Country prices или Fallback cost). Убедитесь, что у товаров Requires Shipping установлено Yes.

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

The rate is in USD but the store is not: UPS возвращает тарифы в валюте аккаунта отправителя. Задайте UPS account currency и Exchange rate. Без курса обмена такие тарифы игнорируются, и используется фиксированная цена.

«This measurement system is not valid for the selected country»: оставьте Measurement units в положении Automatic (by ship-from country) или выберите единицы, которые UPS ожидает для вашей страны отправки.

The page warns about the weight or length unit: без весовой категории в kg неизвестные единицы веса читаются как kg. Добавьте весовую категорию в kg в разделе System > Localisation > Weight Classes. Неизвестная единица длины магазина означает, что Box size читается как cm. Используйте cm, mm, m или in как линейный класс магазина (System > Settings, вкладка Option).

Rates look outdated after a change: нажмите Save на странице расширения или Clear cached UPS token and rates.

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

For developers: расширение запускает события OpenCart, на которые могут подписаться другие расширения: vfd_ups/allowed_services и vfd_ups/excluded_services ограничивают службы UPS, которые можно показать, vfd_ups/rate_request изменяет запрос тарифа, vfd_ups/api_base_url — адрес API, а vfd_ups/currency_codes сопоставляет коды валют, которые возвращает UPS.

Удаление

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

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

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