VibeFox FedEx for OpenCart — Помощь

Требования

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

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

Аккаунт FedEx и ключи API (только для тарифов в реальном времени): в портале разработчиков FedEx (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. Один ключ работает на одном домене.

Установка

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

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

Настройка

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

В верхней части страницы расширение показывает предупреждения: заполнена только часть из трёх учётных данных API, нет ключей API и фиксированных цен (тогда способ доставки не показывается никогда), не указан индекс отправления, не указан штат отправления для США или Канады, валюта магазина без курса обмена для тарифов в валюте аккаунта FedEx, единица веса, которую расширение не распознаёт, при отсутствии весового класса в килограммах (добавьте его в разделе System > Localisation > Weight Classes), или, при размере коробки, единица длины, которую оно не распознаёт. Числовые поля принимают точку или запятую как десятичный разделитель. При сохранении неверный номер или размер коробки, курс обмена 0, валюта аккаунта, которая не является трёхбуквенным кодом, некорректное название или порядок сортировки сообщаются и не сохраняются; поле сохраняет прежнее значение, а остальные поля сохраняются (The other settings were saved.). Минимальный вес больше максимального также сообщается, и оба веса сохраняют прежние значения.

Основные

Настройки действуют для всех геозон. FedEx предлагается при оформлении заказа как один вариант доставки: самая дешёвая услуга FedEx или фиксированная цена, если FedEx не возвращает тариф.

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

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

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

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

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

Раздел содержит ссылку на портал разработчиков FedEx. Без ключей используются фиксированные цены.

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

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

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

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

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

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

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

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

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

Cache: кнопка Clear cached FedEx token and rates мгновенно очищает кэш. Токены FedEx кэшируются до истечения срока, тарифы — на 1 час, а неудачные запросы — на 5–10 минут.

Ship from

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

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

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

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

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

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

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

Country prices: список стран назначения и цен в валюте магазина по умолчанию, без налогов. Нажмите Add row, чтобы добавить строку, и кнопку × — чтобы удалить её. Выберите * Any other country для цены, которая применяется ко всем странам без собственной строки. Строки без правильной страны или цены игнорируются и сообщаются при сохранении.

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

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

Условия

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Заказы

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

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

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

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

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

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

FedEx не отображается при оформлении заказа: проверьте, что лицензия активна и Enable/Disable включено. Проверьте Geo zone или Ignore shipping zones и Countries. Проверьте предупреждения в верхней части страницы расширения, ограничения по весу и Minimum subtotal. Без тарифа в реальном времени способу доставки нужна цена для страны, строка * Any other country или Fallback cost. Проверьте, что у товаров Requires Shipping установлено в Yes.

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

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

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

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

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

Для разработчиков: другие расширения могут изменить адрес API, разрешённые услуги FedEx и запрос тарифа через события OpenCart vfd_fedex/api_base_url, vfd_fedex/allowed_services и vfd_fedex/rate_request (регистрируются как catalog/vfd_fedex/...); настройка vfd_fdx_api_url заменяет адрес API для тестов и не имеет поля на странице настроек.

Удаление

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

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

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