VibeFox ShipStation for OpenCart — Помощь

Требования

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

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

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

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

Установка

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

OpenCart 3

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

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

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

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

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

6. Если валюта магазина по умолчанию не совпадает с валютой вашей учётной записи ShipStation, задайте Exchange rate. По желанию заполните резервные цены.

7. Включите Enable ShipStation shipping и нажмите Save.

OpenCart 4

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

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

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

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

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Shipping > VibeFox ShipStation > Edit. Разделы перечислены слева. Одна кнопка Save сохраняет всю страницу без перезагрузки. При каждом сохранении очищается кэш тарифов ShipStation и проверяются API Key и API Secret. Затем страница показывает перевозчиков, подключённых к вашей учётной записи, с их кодами, например "stamps_com (Stamps.com), ups_walleted (UPS by ShipStation)". Сохранять настройки могут только администраторы с правом изменения этого расширения.

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

Общие

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

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

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

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

Учётная запись 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: обязателен для тарифов в реальном времени, например 78703. ShipStation рассчитывает тарифы только по почтовому индексу, и он должен находиться в стране вашей учётной записи ShipStation. У OpenCart нет почтового индекса магазина, поэтому он никогда не берётся из адреса магазина.

Тарифы

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: таблица с ценой Base по каждой стране и колонками размера по весу посылки: XS до 1 кг, S до 2 кг, M до 3 кг, L до 5 кг и XL свыше 5 кг. Нажмите Add country, чтобы добавить строку. Пустой размер использует базовую цену. Базовая цена 0 означает бесплатную доставку. Строка * Default (all other countries) применяется к странам без собственной строки. Строка без цены не сохраняется.

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

Условия

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

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

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

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

Доступность

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

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

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

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

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

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

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

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

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

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

Как это работает на странице оформления заказа

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

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

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

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

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

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

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

Заказы

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Удаление

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

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

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