VibeFox ShipStation for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Учётная запись ShipStation: подключите перевозчиков в ShipStation (Settings > Shipping > Carriers), затем скопируйте API Key и API Secret из раздела ShipStation > Settings > Account > API Settings. Доступ к API зависит от вашего тарифного плана ShipStation. Если страница недоступна, ваш план не включает доступ к API. Модуль использует ShipStation API V1 (API Key и API Secret). Учётные записи ShipStation API V2 с одним ключом API не поддерживаются. Без ключей используются только резервные цены.

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

Установка

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

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

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

4. Вставьте API Key и API Secret, укажите почтовый индекс отправки и нажмите Save. Страница выведет коды перевозчиков вашей учётной записи. Введите нужные в поле Carrier codes и сохраните снова.

5. Если валюта магазина по умолчанию отличается от валюты вашей учётной записи ShipStation, укажите Exchange rate.

6. По желанию заполните резервные цены.

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

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox ShipStation > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Каждое сохранение очищает кэш тарифов ShipStation и проверяет API Key и API Secret. Затем страница показывает перевозчиков, подключённых к вашей учётной записи, с их кодами, например «stamps_com (Stamps.com), ups_walleted (UPS by ShipStation)».

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

Общие

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

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

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

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

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

API Secret: API Secret с той же страницы. Он хранится так же, как ключ.

Remove the saved API key and secret: появляется, когда ключи сохранены. Отметьте и сохраните, чтобы удалить оба.

Carrier codes: один или несколько кодов перевозчиков ShipStation через запятую, например stamps_com, ups_walleted. Используется до 5 кодов, по одному запросу к API на перевозчика. Если вы введёте больше, сохранятся только первые 5, и страница сообщит об этом. Показывается самый дешёвый тариф этих перевозчиков. Коды берите из списка, который появляется после сохранения.

Allowed services: необязательно, коды служб ShipStation через запятую, например usps_priority_mail, ups_ground. Оставьте пустым, чтобы показывать самую дешёвую службу перевозчиков, указанных выше.

Package code: «package» (по умолчанию) рассчитывает вашу собственную коробку и исключает конверты и коробки с фиксированным тарифом перевозчика. Оставьте пустым, чтобы рассчитывать все типы упаковки, которые предлагает перевозчик.

Отправка из

Ship-from postal code: обязателен для тарифов в реальном времени. ShipStation рассчитывает тариф только по почтовому индексу, и он должен находиться в стране вашей учётной записи ShipStation. Оставьте пустым, чтобы использовать почтовый индекс магазина из Shop Parameters > Contact > Stores.

Тарифы

Parcels: как корзина отправляется в ShipStation.

ShipStation account currency: валюта, в которой ShipStation возвращает тарифы: USD, CAD, GBP, AUD, NZD или EUR. По умолчанию: USD (американские учётные записи).

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

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

Prices by country: таблица с базовой ценой для каждой страны и столбцами размера по весу посылки: XS ≤ 1 kg, S ≤ 2 kg, M ≤ 3 kg, L ≤ 5 kg и XL > 5 kg. Нажмите Add country, чтобы добавить строку, и значок корзины, чтобы удалить её. Пустой размер использует базовую цену. Базовая цена 0 означает бесплатную доставку. Строка * Default (all other countries) применяется к странам без собственной строки. Строка без какой-либо цены не сохраняется.

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

Условия

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Затем модуль отправляет в ShipStation почтовый индекс отправки, страну назначения, регион, город и почтовый индекс, вес посылки и размер коробки. Запрос не делается, пока покупатель не введёт почтовый индекс. Страны без почтовых индексов получают резервные цены. Товары укладываются в одну коробку. Если у товара нет размеров, посылка рассчитывается только по весу.

ShipStation запрашивается по одному разу для каждого кода перевозчика. Модуль использует самый дешёвый разрешённый тариф, пересчитанный в валюту магазина по умолчанию. Затем цена показывается в валюте корзины покупателя.

Каждый ответ кэшируется на 1 час. Если ShipStation отвечает без пригодного тарифа, ответ запоминается на 10 минут. Если ShipStation отклоняет ключи или недоступен, запросы приостанавливаются на 5 минут. После лимита запросов пауза соответствует времени сброса, которое указывает ShipStation. Тайм-аут запроса составляет 12 секунд. Отключение модуля очищает кэш тарифов.

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

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

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

Заказы

Когда заказ оформлен с тарифом ShipStation в реальном времени, выбранная служба сохраняется вместе с заказом. Страница заказа в бэк-офисе показывает её в блоке ShipStation в поле Service, например «USPS Ground Advantage - Package», чтобы вы могли создать соответствующую этикетку в ShipStation. Последующие пересчёты корзины её не меняют. Заказы, оформленные с резервной ценой или бесплатной доставкой, не имеют блока службы.

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

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

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

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

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

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

При оформлении заказа показывается резервная цена вместо тарифа ShipStation: проверьте предупреждения вверху страницы модуля (ключи, код перевозчика, почтовый индекс отправки, курс обмена). Включите Debug log, обновите страницу оформления заказа и посмотрите поле Log. Почтовый индекс покупателя обязателен. Запрос не делается, пока он не введён.

Какой код перевозчика вводить: сохраните настройки с ключом и секретом. Страница выводит коды перевозчиков вашей учётной записи. Используйте один или несколько из них.

Проверка подключения к ShipStation не прошла: сообщение показывает причину. Проверьте API Key и API Secret, затем сохраните снова, чтобы повторить проверку.

Тариф отличается от ShipStation: посылка формируется из весов и размеров товаров, товары укладываются в одну коробку. Товары без размеров рассчитываются только по весу. Тарифы кэшируются на 1 час. Нажмите Save на странице модуля, чтобы очистить кэш.

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

Удаление

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

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