VibeFox Shippo for PrestaShop — Помощь

Требования

PrestaShop: от 8.0 до 9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более старые версии PHP.

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

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

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

Установка

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

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

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

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

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

6. При необходимости введите резервные цены в таблице по странам и весу и нажмите Save.

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

Настройка

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

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

Общие

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

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

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

Учётная запись 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). Показывается самый дешёвый разрешённый тариф. Оставьте поле пустым, чтобы показывать самый дешёвый тариф любого перевозчика.

Адрес отправки (адрес, с которого отправляются ваши посылки; пустые поля берутся из адреса магазина в Shop Parameters > Contact > Stores, если он находится в той же стране)

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

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

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

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

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

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

Тарифы

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 (до 2 кг), M (до 3 кг), L (до 5 кг) и XL (свыше 5 кг). Пустой диапазон или 0 использует столбец Price. Строка * Default применяется к странам без собственной строки. Новая строка создаётся как * Default. Строка, сохранённая с пустыми ячейками, взимает 0, поэтому удаляйте строки, которые не заполняете.

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

Условия

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

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

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

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

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

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

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

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

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

Debug log: записывает запросы к Shippo в logs/vfd_shpo_debug.log.php в папке модуля. Файл нельзя открыть из веба. Ошибки API записываются всегда, даже когда эта опция выключена. API-токен и адреса клиентов никогда не записываются в журнал.

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

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

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

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

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

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

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

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

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

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

Заказы

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

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Shippo — это первый блок на странице Modules > Module Manager > VibeFox Shippo > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-shipping-shippo и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт на vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока следуют языку back office (включены английский и русский).

Если ключ не принят, блок указывает причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on и дату. После смены адреса магазина или после освобождения слота домена в вашем аккаунте нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.

Один ключ работает на одном домене: домене основного магазина, в том числе при мультимагазинной настройке. Удаление ключа из магазина не освобождает слот домена. Освободите слот в своём аккаунте vibefox.net.

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

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

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

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

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

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

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

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

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

Удаление

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

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