VibeFox EasyPost for OpenCart — Помощь

Требования

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

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

Учётная запись EasyPost (только для актуальных тарифов): создайте учётную запись на сайте EasyPost, подключите свои транспортные аккаунты (USPS, UPS, FedEx и другие) в панели EasyPost и скопируйте API-ключ из раздела EasyPost Dashboard > Account Settings > API Keys. EasyPost берёт плату за купленные этикетки, а не за запросы тарифов. Если вы используете только резервные цены, учётная запись EasyPost не нужна.

Товары: товарам нужен вес и желательно габариты.

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

Установка

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

OpenCart 3

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

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

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

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

5. Вставьте API-ключ EasyPost и заполните адрес Ship from. Почтовый индекс обязателен для актуальных тарифов.

6. Если валюта магазина по умолчанию не USD, введите USD exchange rate. По желанию введите резервные цены (см. Настройка). Включите Enable EasyPost shipping и нажмите Save.

OpenCart 4

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

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

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

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

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

Настройка

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

Вверху страницы расширение показывает предупреждения, когда актуальные тарифы нельзя использовать: нет API-ключа (с резервными ценами или без них), не указан почтовый индекс или страна отправки, либо валюта по умолчанию не USD и не задан курс обмена. Также появляется примечание, если задан тестовый API-ключ, и предупреждение, если единица веса или длины вашего магазина (System > Settings > Option) не поддерживается расширением (kg, g, lb, oz; cm, mm, m, in).

При сохранении название длиннее 64 символов, Sort order, который не является целым числом, или неизвестный налоговый класс или геозона не дают сохранить настройки, и тогда ничего не сохраняется. Значение, которое не является числом (или отрицательное), не сохраняется: предупреждение называет поле, а прежнее значение остаётся, остальные настройки сохраняются. То же происходит, если USD exchange rate равен 0 или если Minimum weight больше Maximum weight.

Общие

Enable EasyPost shipping: предлагает способ на оформлении заказа. Это статус расширения в Extensions > Extensions > Shipping. По умолчанию: выключено.

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

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

Учётная запись EasyPost

API key: ваш API-ключ EasyPost из раздела EasyPost Dashboard > Account Settings > API Keys. Ключ для работы (начинается с EZAK) возвращает реальные тарифы. Тестовый ключ (начинается с EZTK) возвращает тестовые тарифы EasyPost; используйте его только для проверки. После сохранения поле остаётся пустым и показывает сохранённый ключ в замаскированном виде, например Saved key: EZAK******abcd. Leave the field empty to keep it. Вводите новое значение, только если хотите его изменить. Без ключа используются только резервные цены.

Remove the saved API key: включите и нажмите Save, чтобы удалить сохранённый ключ.

Allowed carriers / services: необязательно, через запятую. Укажите перевозчика (USPS) или перевозчика и услугу (USPS:Priority, UPS:Ground) так, как их называет EasyPost. Показывается самый дешёвый разрешённый тариф. Оставьте поле пустым, чтобы показывать самый дешёвый тариф любого перевозчика.

Адрес отправки

Адрес, с которого отправляются ваши посылки. Если Country совпадает со страной вашего магазина, пустое поле Sender name / company берётся из названия магазина, а пустое поле State — из региона магазина (System > Settings). В OpenCart нет почтового индекса магазина, поэтому почтовый индекс нужно указать здесь.

Sender name / company: имя отправителя или название компании. Пустое значение означает название магазина (только для той же страны).

Street address: улица адреса отправки.

City: город адреса отправки.

State: двухбуквенный код штата, например CA или NY.

ZIP code: почтовый индекс адреса отправки, например 94105. Обязателен для актуальных тарифов.

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

Тарифы

Parcels: как корзина передаётся в EasyPost.

Веса переводятся из единицы веса вашего магазина в унции (минимум 1 oz), а габариты из единицы длины магазина в дюймы. Если у какого-либо товара нет габаритов, посылка тарифицируется только по весу.

USD exchange rate: тарифы EasyPost указаны в USD. Введите цену 1 USD в валюте магазина по умолчанию, например 0.92. Без него актуальные тарифы не используются, применяются только резервные цены. Не нужно, если валюта магазина по умолчанию — USD. Магазины в USD и CAD просят EasyPost назначать цены в их собственной валюте. Принимаются и точка, и запятая как десятичный разделитель.

Tax class: налоговый класс, применяемый к доставке, или No tax. Тарифы EasyPost не включают налог с продаж.

Резервные цены

Используются, когда актуального тарифа нет: нет API-ключа, EasyPost недоступен, ключ отклонён или ни у одного перевозчика нет тарифа для адреса. Цены указываются в валюте магазина по умолчанию, без налогов. Оставьте оба поля пустыми, чтобы в этом случае скрывать способ.

Country prices: одна строка на страну: двухбуквенный код страны, двоеточие и цена, например US:9.99. Строки в другом формате пропускаются и перечисляются в предупреждении при сохранении.

Other countries: цена для стран, которых нет в списке выше. Оставьте поле пустым, чтобы скрывать способ для них.

Условия

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

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

Minimum weight: скрывать способ, если корзина весит меньше, в единице веса вашего магазина (она указана в подписи поля). 0 означает отсутствие ограничения (по умолчанию).

Maximum weight: скрывать способ, если корзина весит больше, в единице веса вашего магазина. 0 означает отсутствие ограничения (по умолчанию).

Доступность

Обычно геозона определяет, где предлагается способ. Также его можно предлагать по странам независимо от геозоны.

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

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

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

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

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

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

Remove data on uninstall: если включено, удаление расширения стирает его настройки и журнал. Данные EasyPost оформленных заказов сохраняются. Отключение способа никогда не удаляет настройки.

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

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

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

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

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

Иначе расширение отправляет в EasyPost адрес отправки, адрес доставки и посылку и получает тарифы всех ваших транспортных аккаунтов. Оно выбирает самый дешёвый разрешённый тариф, переводит его в валюту магазина по умолчанию и показывает покупателю в его валюте с налогом выбранного Tax class. Для стран, отмеченных как Postcode Required в System > Localisation > Countries, запрос делается только если в адресе доставки есть почтовый индекс. В стандартных данных OpenCart для США этот флаг выключен, поэтому адрес в США без почтового индекса тоже отправляется; EasyPost тогда возвращает ошибку, и используется резервная цена.

Каждый ответ кэшируется на 1 час для того же адреса и той же посылки. Адрес без пригодных тарифов запоминается на 10 минут. После тайм-аута, отклонённого ключа, ограничения частоты запросов или ошибки сервера EasyPost запросы не делаются в течение 5 минут. Тайм-аут API составляет 10 секунд. Во всех этих случаях покупатель не видит ошибку: используется резервная цена, или способ скрывается, если резервной цены нет. Причина записывается в журнал.

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

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

Заказы

Когда оформляется заказ со способом EasyPost, тариф, показанный на оформлении заказа, сохраняется с заказом. Страница заказа в админ-панели (Sales > Orders) показывает блок EasyPost shipping над историей:

Carrier / service: перевозчик и услуга EasyPost для тарифа, например USPS Priority. В режиме одна посылка на товар перечисляются все использованные услуги.

Estimated delivery days: сроки доставки, которые вернул EasyPost (только в режиме одна посылка на заказ, когда EasyPost их возвращает).

Price source: Live EasyPost rate, Fallback price (no live rate) или Free shipping threshold.

Calculated price (excl. tax): цена в валюте магазина по умолчанию.

Блок показывается, даже если расширение позже будет выключено. Последующие изменения заказа в админ-панели не меняют эти значения. Используйте их, чтобы купить этикетку в своей учётной записи EasyPost. OpenCart создаёт запись заказа каждый раз, когда оформление доходит до шага подтверждения; сохранённые тарифы таких незавершённых заказов удаляются через 30 дней.

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

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

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

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

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

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

EasyPost не появляется на оформлении заказа: проверьте, что лицензия действует и включено Enable EasyPost shipping. Проверьте Geo zone (или Ignore shipping zones и Countries), ограничения по весу и Minimum subtotal. Без актуального тарифа способу нужна резервная цена для страны или для Other countries. Убедитесь, что у товаров Requires Shipping равно Yes.

Актуальные тарифы не появляются: прочитайте предупреждения вверху страницы расширения, затем включите Debug log, перезагрузите оформление заказа и посмотрите поле Log. Частые причины: нет API-ключа или почтового индекса отправки, магазин не в USD без USD exchange rate, у адреса доставки ещё нет почтового индекса, ни один перевозчик вашей учётной записи EasyPost не обслуживает адрес, или Allowed carriers / services отфильтровывает все тарифы.

Тарифы похожи на тестовые цены: задан тестовый ключ (EZTK...). На рабочем магазине используйте производственный ключ (EZAK...).

Тарифы перестали работать на несколько минут: после тайм-аута, отклонённого ключа или ошибки сервера EasyPost расширение приостанавливает запросы на 5 минут и использует резервные цены. Проверьте API-ключ и журнал.

Налог включён? Тарифы EasyPost не включают налог с продаж. Выберите налоговый класс в Tax class, чтобы добавить налог к доставке.

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

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

Для разработчиков: другие расширения могут изменять тело запроса, выбранный тариф и базовый URL API с помощью событий OpenCart vfd_easypost/shipment_request, vfd_easypost/selected_rate и vfd_easypost/api_url.

Удаление

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

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

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