VibeFox EasyPost for PrestaShop — Помощь

Требования

PrestaShop: 8.0 – 9.x.

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

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

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

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

Установка

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

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

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

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

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

При установке модуль создаёт перевозчика EasyPost Shipping с текстом срока доставки Live carrier rate (EasyPost). Перевозчик назначается всем зонам и всем группам покупателей. Зоны, группы покупателей, срок доставки, логотип и ограничения размеров можно изменить в Shipping > Carriers. Цены там не задавайте: цена всегда берётся из модуля.

Настройки

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

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

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

Общие

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

Name: название перевозчика, которое видит покупатель при оформлении заказа, не более 64 символов (более длинное название отклоняется, и ничего не сохраняется). По умолчанию: EasyPost Shipping. Если название пустое или содержит символы, которые PrestaShop не допускает в названии перевозчика, используется название по умолчанию.

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

API key: ваш ключ API EasyPost из раздела EasyPost Dashboard > Account Settings > API Keys. Производственный ключ (начинается с EZAK) возвращает реальные тарифы. Тестовый ключ (начинается с EZTK) возвращает тестовые тарифы EasyPost; используйте его только для проверки. После сохранения поле остаётся пустым и показывает сохранённый ключ в маскированном виде, например EZAK******abcd. Оставьте поле пустым, чтобы сохранить ключ. Вводите новое значение только для его замены.

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

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

Отправка из

Адрес, с которого отправляются ваши посылки. Если Country — страна вашего магазина, пустые поля заполняются из адреса магазина в Shop Parameters > Contact > Stores (а имя отправителя — из названия магазина).

Sender name / company: имя отправителя или название компании.

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

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

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

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

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

Тарифы

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

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

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

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

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

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

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

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

Условия

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Заказы

Когда оформляется заказ с перевозчиком EasyPost, тариф, показанный при оформлении, сохраняется вместе с заказом. На странице заказа в бэк-офисе показывается блок 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. Тарифы брошенных корзин удаляются через 30 дней.

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

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

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

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

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

EasyPost не появляется при оформлении заказа: проверьте, что лицензия действует и Enable EasyPost shipping включено. В Shipping > Carriers проверьте, что перевозчик включён и охватывает зону страны покупателя и группу покупателя (или что включено Ignore shipping zones и выбрана страна). Проверьте ограничения по весу и Minimum subtotal. Без актуального тарифа перевозчику нужна резервная цена для страны или для Other countries. Товары также могут быть ограничены определёнными перевозчиками на странице товара.

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

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

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

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

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

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

Хуки для разработчиков: хуки actionVfdEpShipmentRequest (тело запроса), actionVfdEpSelectedRate (выбранный тариф) и actionVfdEpApiUrl (базовый URL API) позволяют настраивать модуль.

Удаление

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

EasyPost — товарный знак его владельца. Модуль не связан с EasyPost и не одобрен EasyPost.