VibeFox Cargoson for OpenCart — Помощь

Требования

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

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

Учётная запись Cargoson (только для живых цен): живые цены используют API расчёта стоимости перевозок Cargoson. Запросы стоимости перевозки требуют подписки Cargoson с доступом к API (на момент написания — тариф Advanced или выше). Ключ API выдаётся в вашей учётной записи Cargoson; если в вашем тарифе не видны настройки API, обратитесь в поддержку Cargoson. Цены берутся у перевозчиков и прайс-листов, подключённых к этой учётной записи. Если вы используете только фиксированные цены, учётная запись Cargoson не нужна.

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

Установка

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

OpenCart 3

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

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

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

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

5. Выберите, как рассчитывается стоимость доставки, и заполните соответствующие разделы: фиксированные цены и, для живых цен, ключ API и почтовый индекс отправки (см. Настройка). Включите Enable Cargoson и нажмите Save.

OpenCart 4

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

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

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

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

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Shipping > VibeFox Cargoson > Edit. Разделы перечислены слева. Одна кнопка Save внизу сохраняет всю страницу без перезагрузки. После сохранения вы увидите Settings saved. Cached Cargoson prices were cleared. Дробные числа можно вводить с точкой или запятой. Ничего не сохраняется, и страница выводит ошибки, если Method title пустое или длиннее 64 символов, числовое поле содержит текст или отрицательное число, Currency conversion rate равно 0, Minimum weight (kg) больше Maximum weight (kg), Price currency не является трёхбуквенным кодом, строка таблицы цен содержит некорректную страну или цену, или Sort order не является целым числом. Если расширение не знает единицу веса магазина, предупреждение после сохранения сообщит, что веса товаров принимаются в килограммах; добавьте весовой класс с единицей kg в System > Localisation > Weight Classes. Сохранять настройки могут только администраторы с правом изменения этого расширения.

Общие

Покупатель видит один тариф Cargoson. Вы можете ограничить способ доставки геозоной или странами в Availability.

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

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

Shipping cost: как рассчитывается цена.

Причина отсутствия живой цены записывается в журнал отладки. Покупателю она никогда не показывается.

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

API Cargoson (обязательно только для живых цен)

API key: ключ API из вашей учётной записи Cargoson. Он отправляется только в Cargoson и никогда не показывается покупателям и не записывается в журнал. После сохранения поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

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

Carrier: какие цены используются. Покупатель видит один тариф.

Package type code: тип упаковки Cargoson, который отправляется с запросом цены. По умолчанию: CLL. Примеры API Cargoson используют EUR (поддон EUR) и FIN (поддон FIN). Для посылок используйте код упаковки вашей учётной записи Cargoson. Заказ отправляется как одна упаковка с общим весом корзины.

Price currency: валюта цен в вашей учётной записи Cargoson в виде трёхбуквенного кода. По умолчанию: EUR. API возвращает суммы без кода валюты.

Currency conversion rate: нужен, только если валюта цен отличается от валюты по умолчанию вашего магазина: 1 единица валюты Cargoson = X единиц валюты по умолчанию. Оставьте поле пустым, чтобы отклонять такие цены, и покупатель никогда не платил в неверной валюте.

Адрес отправки (адрес забора) (для живых цен)

Collection country: страна, из которой вы отправляете. Первый вариант, Store country, использует страну вашего магазина.

Collection postcode: почтовый индекс, с которого вы отправляете. Cargoson требует его для живых цен. Адрес магазина в OpenCart — свободный текст, поэтому почтовый индекс из него никогда не берётся: введите его здесь.

Дата забора, отправляемая в Cargoson, — сегодня по часовому поясу магазина, а в выходные — ближайший понедельник.

Фиксированные цены (используются, когда Shipping cost равно Fixed prices, и как запасной вариант для живых цен)

Price per country and size: список строк с Country, Price и ценами в зависимости от веса корзины в валюте по умолчанию магазина, без налогов: XS до 1 кг, S до 2 кг, M до 3 кг, L до 5 кг, XL свыше 5 кг. Пустая или нулевая цена размера использует столбец Price; пустой Price означает, что фиксированной ставки для этого размера нет. Нажмите Add country, чтобы добавить строку. Выберите * All other countries для цен, которые действуют во всех странах без собственной строки. Страны без строки (если нет строки *) фиксированной ставки не имеют, поэтому для них способ доставки скрывается. Цены должны быть числами не меньше 0. Пустая строка игнорируется.

Fixed price applies: Per order (по умолчанию) списывает цену один раз. Per item (price × quantity) умножает её на количество товаров в корзине. Живые цены Cargoson всегда считаются за отправление.

Условия

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

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

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

Free shipping: включает бесплатную доставку Cargoson от суммы, указанной ниже.

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

Tax class: налоговый класс стоимости доставки или No tax (по умолчанию). Тарифы перевозчиков в Cargoson обычно указываются без НДС. Выберите No tax, если ваши цены уже включают налоги.

Доступность

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

Ignore shipping zones: не проверять геозону; решает список стран ниже.

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

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

Debug log: записывает каждый расчёт тарифа в storage/logs/vfd_cgs_debug.log.php. Файл недоступен из веб-браузера. Ошибки API и отклонённые цены записываются всегда, даже если эта опция выключена. Ключ API и почтовый индекс покупателя никогда не записываются. Когда файл достигает 5 МБ, его переносят в vfd_cgs_debug.old.log.php, и начинается новый журнал.

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

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

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

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

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

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

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

В фиксированном режиме цена берётся из таблицы. В живых режимах расширение отправляет в Cargoson дату забора, страну и почтовый индекс отправки, страну и почтовый индекс доставки, а также одну упаковку с кодом типа упаковки и общим весом корзины (не менее 0,1 кг). Живая цена запрашивается только тогда, когда в адресе доставки есть почтовый индекс. Cargoson возвращает цены ваших перевозчиков; расширение выбирает самую дешёвую (у выбранного перевозчика, если он задан) и при необходимости конвертирует её в валюту по умолчанию. Цена рассчитывается в валюте по умолчанию, округляется до её знаков после запятой и показывается покупателю в его валюте с налогом выбранного Tax class.

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

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

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

Заказы

Когда покупатель оформляет заказ с Cargoson, тариф, рассчитанный при оформлении заказа, сохраняется вместе с заказом. В Sales > Orders страница заказа показывает панель Cargoson shipping:

Carrier, Service и Cargoson service ID: перевозчик и сервис Cargoson, которые были рассчитаны, показываются, когда использовалась живая цена.

Price source: Cargoson live price, Fixed price или Free shipping threshold.

Calculated price (excl. tax): цена в валюте по умолчанию вашего магазина.

Панель показывается и тогда, когда способ доставки выключен. В OpenCart 4 заказ создаётся один раз на шаге подтверждения и обновляется каждый раз, когда покупатель возвращается на этот шаг, поэтому сохранённая котировка — последняя рассчитанная при оформлении заказа; если покупатель переключается на другой способ доставки, котировка Cargoson для заказа удаляется. Изменение заказа в админке котировку не меняет, и позже она тоже не меняется. Бронируйте отправку в Cargoson или через его собственные интеграции.

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

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

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

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

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

Cargoson не появляется при оформлении заказа: проверьте, что лицензия активна и включено Enable Cargoson. Проверьте Geo zone (или Ignore shipping zones и Countries), ограничения по весу и Minimum order amount. В фиксированном режиме проверьте, что у страны или * All other countries есть цена для размера корзины. Проверьте, что у товаров Requires Shipping установлено в Yes.

Живые цены не появляются: посмотрите поле Log на странице расширения. Ошибки API всегда записываются; включите Debug log, чтобы видеть каждый расчёт. Обычные причины: ещё не введён почтовый индекс доставки, нет Collection postcode, ключ API отклонён (неверный или просроченный ключ либо в вашем тарифе Cargoson нет доступа к API), нет перевозчика для маршрута или веса, либо цена в другой валюте. При Cargoson live prices, fixed prices if the API fails покупатели получают фиксированную цену, пока вы устраняете проблему.

Cargoson отклоняет тип упаковки: используйте код упаковки, который ваша учётная запись Cargoson использует в Package type code. Причина появится в журнале.

Цена в другой валюте отклоняется: установите Price currency в валюту ваших цен Cargoson и введите Currency conversion rate.

Налог на доставку начисляется дважды: ваши цены Cargoson уже включают НДС. Установите Tax class в No tax.

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

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

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

Удаление

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

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

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