VibeFox FedEx for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Учётная запись FedEx и ключи API (только для актуальных тарифов): в FedEx Developer Portal (developer.fedex.com) создайте проект с Rate API, привяжите свою учётную запись доставки FedEx и скопируйте API Key и Secret Key. Также понадобится 9-значный номер учётной записи FedEx. Тестовые ключи работают только при включённом Sandbox, производственные — только при выключенном. Модуль использует REST API FedEx с OAuth 2.0; ему не нужны meter number и пароль веб-служб. Если вы используете только фиксированные цены, ключи FedEx не нужны.

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

Установка

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

2. После окончания загрузки нажмите Configure или позже найдите VibeFox FedEx в списке модулей и нажмите Configure.

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

4. Введите API Key, Secret Key, 9-значный номер учётной записи FedEx и адрес Ship from (почтовый индекс и, для США и Канады, 2-буквенный код штата). Выключите Sandbox, если используете производственные ключи. По желанию введите фиксированные цены как резервный вариант. Нажмите Save.

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

Настройка

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

Вверху страницы модуль показывает предупреждения: заполнены только некоторые из трёх учётных данных API; нет ключей API и фиксированных цен (тогда перевозчик никогда не показывается); не указан почтовый индекс отправления; не указан код штата отправления для США или Канады; валюта магазина отличается от валюты учётной записи FedEx без курса обмена; единица веса магазина (или, при размере коробки, единица измерения размеров) не поддерживается модулем; или перевозчик удалён. Числовые поля принимают точку или запятую как десятичный разделитель. Некорректное число или размер коробки, курс обмена 0, код валюты учётной записи, который не состоит из 3 букв, и название длиннее 64 символов не сохраняются и выводятся как ошибка; поле сохраняет прежнее значение, остальные поля сохраняются. Также выводится ошибка, если минимальный вес больше максимального; оба веса сохраняют прежние значения.

Общие

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

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

Tax status: правило налога для перевозчика или No tax. Если выбрано правило налога (и налоги включены в магазине), PrestaShop добавляет налог к стоимости доставки, поэтому используется стоимость FedEx без налогов. При No tax используется чистая стоимость FedEx без изменений.

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

Без ключей используются фиксированные цены ниже. В разделе есть кнопка Clear cached FedEx token and rates.

Sandbox: использует песочницу FedEx (apis-sandbox.fedex.com) с тестовыми ключами. Выключите её для реальных тарифов (apis.fedex.com) с производственными ключами. По умолчанию: включено.

API Key: API Key (client_id) вашего проекта в FedEx Developer Portal.

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

FedEx account number: 9-значный номер учётной записи доставки FedEx, связанной с проектом. Для неё рассчитываются тарифы по учётной записи (согласованные).

Rates: Account rates (your negotiated FedEx prices) (по умолчанию) или List rates (FedEx published prices).

Residential delivery: считать адреса клиентов жилыми (FedEx Home Delivery, надбавка за доставку на адрес жилья). Выключите, если вы отправляете в основном организациям. По умолчанию: включено.

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

FedEx account currency: валюта вашей учётной записи FedEx, например USD для американских учётных записей или CAD для Канады. По умолчанию: USD. Также FedEx всегда просят рассчитать стоимость в валюте магазина по умолчанию.

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

Адрес отправления

Адрес, с которого FedEx забирает посылки или на который вы их сдаёте. Используется для актуальных тарифов.

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

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

City: город отправления.

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

Фиксированные цены

Используются, когда ключи API не введены, и как резерв, когда FedEx не возвращает тариф (API недоступен, неверные ключи, нет подходящей службы). Оставьте оба поля пустыми, чтобы в этом случае скрыть перевозчика.

Country prices: таблица кодов стран назначения из 2 букв и цен в валюте магазина по умолчанию, без налогов. Нажмите Add row, чтобы добавить страну, и значок корзины, чтобы удалить её. Используйте * как код страны для всех остальных стран. Строки, которые не содержат кода страны (или *) с ценой, пропускаются и выводятся как ошибка при сохранении.

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

Fixed price is: Per order берёт цену один раз. Per item (price x number of items) умножает её на количество товаров в корзине. Это относится только к фиксированным ценам. Актуальные тарифы FedEx всегда рассчитываются для общего веса корзины.

Условия

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

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

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

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

Default product weight: вес в кг для товаров без веса, для тарифов FedEx и для ограничений по весу выше. По умолчанию: 0.5. Веса товаров пересчитываются из единицы веса магазина (кг, г, фунты или унции), которая задаётся в International > Localization (Local units).

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

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

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

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

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

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

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

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

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

В остальных случаях модуль получает токен OAuth и отправляет в Rate API FedEx адрес отправления, адрес доставки, вес корзины (в кг или, для магазинов с фунтами или унциями, в фунтах), размер коробки, если он задан, и вашу валюту по умолчанию как предпочтительную валюту. Для стран, где нужен почтовый индекс, запрос отправляется только после того, как покупатель его ввёл. Для международных отправлений передаётся таможенная стоимость корзины. Коды штатов передаются только для США и Канады.

FedEx возвращает доступные службы. Для каждой службы модуль берёт выбранный вами тариф по учётной записи или публичный тариф, предпочитает тариф в вашей валюте по умолчанию, пересчитывает тариф в валюте учётной записи FedEx по вашему курсу и отбрасывает тарифы, которые не может пересчитать. Для цены используется самая дешёвая служба, а цена показывается в валюте корзины покупателя.

Токен кэшируется для каждой среды и ключа и запрашивается заново автоматически, когда FedEx его отклоняет. Тарифы кэшируются на 1 час. Неудачный запрос тарифа запоминается на 10 минут, неудачный запрос токена — на 5 минут, чтобы сбой не замедлял каждое обновление оформления заказа. Тайм-аут API — 15 секунд. Если FedEx не отвечает, покупатель не видит ошибки: используется фиксированная цена или перевозчик скрывается. Причина записывается в журнал отладки.

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

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

Заказы

На странице заказа в бэк-офисе заказы с перевозчиком FedEx имеют блок FedEx shipping. В нём показываются FedEx service тарифа (для актуальных тарифов), Price source (FedEx live rate, Fixed price (no live rate) или Free shipping threshold) и Calculated price (excl. tax) в валюте магазина по умолчанию. Значения фиксируются в момент оформления заказа: последующие изменения настроек их не меняют.

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

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

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

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

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

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

Актуальные тарифы не появляются: включите Debug log, обновите оформление заказа и посмотрите поле Log на странице модуля. Там записываются неверные ключи, неправильная среда (тестовые ключи при выключенном Sandbox или производственные ключи при включённом), отсутствующий почтовый индекс доставки и коды ошибок FedEx.

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

Умножает ли «Per item» тариф FedEx? Нет. Per item применяется только к фиксированным ценам.

Тарифы выглядят устаревшими после изменения: сохранение страницы модуля очищает кэш. Также можно нажать Clear cached FedEx token and rates.

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

Нужно предлагать только некоторые службы: разработчики могут ограничить службы с помощью хука actionVfdFdxAllowedServices. Хуки actionVfdFdxRateRequest и actionVfdFdxApiBaseUrl изменяют запрос тарифа и адрес API.

Удаление

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

FedEx — торговая марка её владельца. Этот модуль не связан с FedEx и не одобрен компанией FedEx.