VibeFox Shippo for OpenCart — Помощь

Требования

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

PHP: 8.0 или новее.

Аккаунт Shippo: создайте аккаунт Shippo, подключите или включите перевозчиков (USPS, UPS, FedEx, DHL и других) и скопируйте токен API из раздела Shippo > Settings > Advanced > API. Shippo берёт плату за купленные этикетки, а не за запросы тарифов. Новые аккаунты Shippo могут потребовать проверки со стороны Shippo, прежде чем начнут возвращаться актуальные тарифы. Без токена используются только запасные цены.

Товары: у товаров должны быть вес и габариты. Товары без габаритов используют размер коробки по умолчанию.

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

Установка

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

OpenCart 3

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

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

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

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

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

6. Выберите Shippo rate currency (USD, если вы отправляете из США) и, если валюта магазина по умолчанию другая, введите Exchange rate.

7. При необходимости введите запасные цены, включите Enable Shippo shipping и нажмите Save.

OpenCart 4

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

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

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

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

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

Настройка

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

Предупреждения в верхней части страницы сообщают, когда способ доставки не может быть показан никогда или когда актуальные тарифы невозможно использовать: нет токена API, нет почтового индекса или страны отправки, не задан курс обмена, либо единица веса или длины магазина не распознаётся расширением (используйте кг, г, фунты или унции и см, мм, м или дюймы в разделе System > Settings, вкладка Local). Уведомление напоминает, когда задан тестовый токен. При сохранении некорректное название, значение, которое не является числом, отрицательное число или ячейка цены, Minimum weight (kg) больше Maximum weight (kg) или порядок сортировки, не являющийся целым числом, отображаются как ошибка, и ничего не сохраняется, пока вы их не исправите.

Общие

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

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

Tax class: класс налога на стоимость доставки или No tax. Тарифы Shippo не включают налог с продаж. No tax показывает их как есть; класс налога добавляет налог на доставку по вашим налоговым правилам.

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

Аккаунт Shippo

API token: ваш токен API Shippo. Используйте боевой токен (shippo_live_...) для актуальных тарифов в рабочем магазине или тестовый токен (shippo_test_...) для тестовых тарифов Shippo. Токен передаётся только в Shippo и никогда не записывается в журнал. После сохранения поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

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

Allowed carriers / services: необязательно, через запятую. Введите перевозчика так, как его называет Shippo (USPS, UPS, FedEx, DHL Express), или токен уровня услуги Shippo (usps_priority, ups_ground). Показывается самый дешёвый разрешённый тариф. Оставьте поле пустым, чтобы показывать самый дешёвый тариф любого перевозчика.

Ship from (адрес, с которого отправляются ваши посылки)

Если страна отправки совпадает со страной магазина, пустые имя отправителя и регион берутся из названия магазина и региона в System > Settings. В OpenCart нет структурированных данных об улице, городе или почтовом индексе магазина, поэтому укажите их здесь.

Sender name / company: имя отправителя. Оно также используется для подписи таможенной декларации. Если поле пустое, используется название магазина.

Street address: улица отправителя.

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

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

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

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

Тарифы

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

Default box size: длина x ширина x высота в линейной единице вашего магазина (она указана в названии поля), например 30 x 20 x 10. Shippo требует размер коробки. Он используется, когда у товара в корзине нет габаритов. Оставьте поле пустым, чтобы использовать 30 x 20 x 10 см. Значение, которое не удаётся прочитать, игнорируется с уведомлением после сохранения, а остальные настройки сохраняются.

Shippo rate currency: валюта, в которой Shippo указывает тарифы перевозчиков, то есть валюта страны отправки: USD (США), CAD (Канада), GBP (Великобритания), EUR (еврозона) или AUD (Австралия). По умолчанию: USD. Тарифы, которые Shippo возвращает в валюте по умолчанию вашего магазина, всегда используются как есть.

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

Запасные цены (используются, когда актуального тарифа нет: нет токена API, Shippo недоступен, токен отклонён или для адреса нет тарифов перевозчиков; цены в валюте магазина по умолчанию, без налога; оставьте оба поля пустыми, чтобы в этом случае скрыть способ доставки)

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

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

Условия

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Затем расширение передаёт Shippo адрес отправки магазина, адрес покупателя и посылку. Для стран, где OpenCart требует почтовый индекс, запрос ждёт, пока покупатель его введёт. Для международных отправлений добавляется таможенная декларация с названиями товаров (с выбранными опциями), количеством, весом и стоимостью. Shippo возвращает тарифы ваших перевозчиков, и расширение использует самый дешёвый разрешённый тариф. Цена рассчитывается в валюте магазина по умолчанию, округляется до нужного количества знаков и показывается покупателю в его валюте с налогом выбранного Tax class.

В режиме «за заказ» товары укладываются в одну коробку: самая длинная и средняя стороны самых крупных товаров и сумма наименьших сторон всех единиц. Если у какого-либо товара нет габаритов, для всей посылки используется размер коробки по умолчанию. В режиме «за товар» каждый товар тарифицируется как отдельная посылка, а тариф умножается на его количество.

Каждый ответ кэшируется на 1 час для адреса и посылки. Если Shippo отвечает без пригодного тарифа, адрес запоминается на 10 минут. После таймаута, отклонённого токена, ошибки сервера или ограничения частоты запросов расширение приостанавливает запросы на 5 минут и использует запасные цены. Таймаут запроса составляет 10 секунд.

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

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

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

Заказы

Когда заказ оформляется с актуальным тарифом Shippo, расширение сохраняет выбранные Carrier / service и, для одной посылки на заказ, Estimated delivery days. Откройте заказ в Sales > Orders: эти данные отображаются в панели Shippo над историей заказа, чтобы вы могли купить соответствующую этикетку в Shippo. Данные сохраняются вместе с заказом: последующие изменения корзины или настроек их не меняют. Панель также показывается после того, как вы отключили способ доставки. У заказов с запасной ценой или бесплатной доставкой панели Shippo нет.

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

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

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

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

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

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

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

Актуальные тарифы не появляются: включите Debug log, обновите оформление заказа и посмотрите поле Log на странице расширения. Частые причины: нет токена API или почтового индекса отправки; валюта магазина по умолчанию отличается от валюты тарифов Shippo, а курс обмена не задан; покупатель ещё не ввёл почтовый индекс; ни один из перевозчиков вашего аккаунта Shippo не обслуживает адрес; аккаунт Shippo ещё не проверен.

Тестовые тарифы в рабочем магазине: тестовый токен (shippo_test_...) возвращает тестовые тарифы Shippo. Используйте боевой токен (shippo_live_...).

Бесплатная доставка для неожиданных стран: проверьте таблицу цен на наличие пустой строки, особенно пустой строки * Default. Строка со всеми пустыми ячейками взимает 0.

Неверные веса или размеры коробок: если страница предупреждает о неизвестной единице веса или длины, задайте весовой класс в кг, г, фунтах или унциях и линейный класс в см, мм, м или дюймах в разделе System > Settings, вкладка Local.

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

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

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

Удаление

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

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

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