VibeFox USPS for OpenCart — Помощь

Требования

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

PHP: 8.0 или новее, с расширением cURL.

Приложение в USPS Developer Portal (только для тарифов в реальном времени): войдите в USPS Developer Portal (developers.usps.com) с бесплатной бизнес-учётной записью USPS, создайте приложение и скопируйте его Consumer Key и Consumer Secret. Расширение использует актуальные API USPS с OAuth 2.0. Старый Web Tools User ID с ними не работает. Без ключей используются только фиксированные цены.

Почтовый индекс отправителя: тарифы в реальном времени требуют 5-значный почтовый индекс США, с которого отправляются посылки.

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

Установка

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

OpenCart 3

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

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

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

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

5. Введите Consumer Key и Consumer Secret, 5-значный Ship from ZIP code и выберите Services. Если основная валюта вашего магазина не USD, введите USD exchange rate.

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

OpenCart 4

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

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

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

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

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

Настройка

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

Недопустимое значение не сохраняется: страница указывает поле, возвращает прежнее значение и выводит The other settings were saved. Это относится к пустому, слишком длинному названию или названию с запрещёнными символами, отрицательному или нечисловому числу, почтовому индексу не из 5 цифр, неверному размеру коробки, Min weight (kg) больше Max weight (kg) (оба ограничения сохраняют свои значения), порядку сортировки, который не является целым числом, а также неизвестному классу налога или геозоне. Цены по странам, которые не являются числами, очищаются и перечисляются. Предупреждения над настройками сообщают, что задан только один из двух ключей, что ключей и фиксированных цен нет (тогда способ никогда не показывается), что не указан почтовый индекс, что не выбрана ни одна услуга, что не задан курс USD, что включена тестовая среда или что расширение не распознаёт единицу веса или длины магазина.

Общие

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

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

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

Tax class: класс налога на стоимость доставки. Цены USPS не включают налоги. No tax (по умолчанию) означает, что доставка не облагается налогом.

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

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

Consumer Key: Consumer Key (client_id) вашего приложения разработчика USPS. Его очистка также удаляет сохранённый Consumer Secret.

Consumer Secret: Consumer Secret (client_secret) того же приложения. После сохранения поле остаётся пустым и показывает Saved — leave empty to keep it. Clearing the Consumer Key removes it too. Вводите новое значение, только если хотите его изменить.

Test environment: используйте USPS Testing Environment для отправителей. Только для приложений, которым она доступна. Для реальных цен оставьте выключенным. По умолчанию: выключено.

Prices: какой прайс-лист USPS используется.

Services: услуги USPS, которые могут рассчитываться. Показывается самая дешёвая из выбранных услуг, которую USPS предлагает для посылки. Выберите из USPS Ground Advantage, Priority Mail / Priority Mail International, Priority Mail Express / Priority Mail Express International, First-Class Package International Service, Media Mail (books and media only) и Library Mail (libraries and schools only). По умолчанию: Ground Advantage, Priority Mail и First-Class Package International. Тарифы Flat Rate, Cubic, Hold for Pickup и Sunday никогда не используются. Если ни одна услуга не выбрана, тарифы в реальном времени не используются.

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

Cache: расчёты кэшируются на 1 час, неудачный расчёт на 10 минут. После таймаута, ошибки сервера, ограничения частоты запросов или отклонённых ключей USPS не запрашивается в течение 5 минут. Нажмите Clear cached USPS token and rates, чтобы сразу очистить кэш.

Отправка и посылка (цены USPS зависят от почтового индекса отправителя, веса и размера посылки; корзина рассчитывается как одна посылка)

Ship from ZIP code: 5-значный почтовый индекс США, с которого отправляются посылки. ZIP+4 сокращается до 5 цифр. В OpenCart нет почтового индекса магазина, поэтому введите его здесь.

Box size (L x W x H): необязательные размеры коробки в единицах длины вашего магазина (указаны в названии поля), например 30x20x15. Оставьте пустым, чтобы использовать размеры товара: самая длинная сторона, самая широкая сторона и сложенные высоты. Товары без размеров рассчитываются как коробка 10 x 8 x 4 дюйма.

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

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

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

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

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

Условия

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

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

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

Max weight (kg): способ скрывается при весе корзины выше этого значения. По умолчанию: 30. Пустое значение означает 30 кг, 0 означает без ограничения. USPS принимает до 70 фунтов (31,7 кг): более тяжёлые посылки получают фиксированные цены.

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

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

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

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

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

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

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

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

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

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

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

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

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

Расширение получает токен OAuth от USPS и хранит его до незадолго до истечения срока. Для направлений в США и на их территориях (Пуэрто-Рико, Виргинские острова США, Гуам, Американское Самоа, Северные Марианские острова, Микронезия, Маршалловы острова и Палау) оно запрашивает внутренние тарифы и требует 5-значный почтовый индекс покупателя: без него запрос не отправляется. Для других стран запрашиваются международные тарифы.

Запрос содержит почтовый индекс отправителя, вес корзины, размер посылки и тип цены. Посылки тяжелее 70 фунтов получают фиксированные цены. Покупатель видит один вариант с самой дешёвой выбранной услугой. Цена в USD пересчитывается в основную валюту магазина, округляется до её знаков после запятой и показывается в валюте покупателя с налогом выбранного Tax class.

Каждый расчёт кэшируется на 1 час. Неудачный расчёт запоминается на 10 минут. После таймаута, ошибки сервера, ограничения частоты запросов или отклонённых ключей USPS не запрашивается в течение 5 минут. Таймаут HTTP составляет 10 секунд.

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

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

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

Заказы

Когда заказ оформляется с USPS, расширение сохраняет, как была определена цена доставки. Страница заказа в Sales > Orders показывает панель USPS с USPS service (для тарифа в реальном времени, например USPS Ground Advantage), Price source (USPS live rate, Fixed price или Free shipping) и Calculated price (excl. tax). Эти значения сохраняются при оформлении заказа.

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

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

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

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

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

Решение проблем

USPS не отображается при оформлении заказа: проверьте, что лицензия активна и включено Enable USPS shipping. Проверьте Geo zone или включите Ignore shipping zones и проверьте Countries. Проверьте ограничения веса и Minimum subtotal. Без работающих ключей USPS способу нужна фиксированная цена (Country prices или Fallback cost). Проверьте, что у товаров Requires Shipping установлено в Yes.

Тарифы в реальном времени не появляются: проверьте предупреждения в верхней части страницы Edit: оба ключа, почтовый индекс, хотя бы одну услугу и, для магазинов не в USD, курс. Покупатели из США должны указать почтовый индекс. Включите Debug log, перезагрузите оформление заказа и посмотрите поле Log на странице расширения.

Тарифы не являются реальными ценами: выключите Test environment.

Страница предупреждает о единице веса или длины: без весовой категории с единицей kg неизвестные единицы веса считаются килограммами. Добавьте весовую категорию в kg в System > Localisation > Weight Classes. Неизвестная единица длины магазина считается сантиметрами. Используйте cm, mm, m или in как классы длины магазина (System > Settings, вкладка Option).

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

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

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

Удаление

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

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

USPS является товарным знаком её владельца. Это расширение не связано с USPS и не одобрено USPS.