VibeFox The Courier Guy for OpenCart — Помощь

Требования

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

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

Ключ API ShipLogic (для актуальных тарифов и локеров): The Courier Guy работает на платформе ShipLogic. Создайте ключ API в курьерском портале The Courier Guy в разделе Settings > API Keys (бизнес-аккаунт). Без ключа используется только таблица цен, а вариант с локером не предлагается.

Доставка в ЮАР: актуальные тарифы и локеры доступны только для адресов в ЮАР. ЮАР должна быть включённой страной магазина (System > Localisation > Countries), а для актуального тарифа курьера нужны провинции ЮАР (зоны), которые уже есть в OpenCart 3.

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

Установка

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

OpenCart 3

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

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

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

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

5. Включите Courier to the door и/или TCG locker и введите API key ShipLogic. Для актуальных тарифов заполните адрес отправителя (улица, город, провинция, почтовый индекс) и, если валюта магазина не ZAR, ZAR conversion rate.

6. Заполните таблицу цен и/или резервную стоимость и нажмите Save.

OpenCart 4

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

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

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

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

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

Настройка

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

Если название варианта, налоговый класс, порядок сортировки или геозона некорректны, ничего не сохраняется, и страница показывает причину, например Enter a valid option name (1-64 characters, without < > ; = # { }). Некорректное число (например, отрицательное) не сохраняется: страница называет поле и сохраняет прежнее значение, остальное сохраняется. Пока включён хотя бы один вариант, предупреждения вверху страницы сообщают, если ЮАР не включена как страна магазина, не задан ключ API, не заполнены курс ZAR или адрес отправителя, нет ни таблицы цен, ни резервной стоимости, у ЮАР нет зон (провинций) или последний запрос к ShipLogic завершился ошибкой (с датой и текстом ошибки). Предупреждение также появляется, если в магазине нет весовой единицы kg или единицы длины cm.

Общие

Каждый способ доставки — это отдельный вариант на этапе оформления заказа.

Courier to the door: предлагает курьерскую доставку The Courier Guy на адрес покупателя. По умолчанию: выключено.

Courier option name: название варианта курьерской доставки на этапе оформления заказа. По умолчанию: The Courier Guy. Обязательное поле, не более 64 символов, без < > ; = # { }.

TCG locker: покупатель выбирает локер на этапе оформления заказа. Предлагается только для адресов в ЮАР и только при наличии ключа API ShipLogic. По умолчанию: выключено.

Locker option name: название варианта с локером на этапе оформления заказа. По умолчанию: The Courier Guy locker. Те же правила, что и для названия курьера.

Tax status: налоговый класс обоих вариантов. При налоговом классе актуальные тарифы берутся без НДС, а OpenCart добавляет налог этого класса. None (live rates including VAT) (по умолчанию): актуальные тарифы берутся с учётом НДС.

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

API ShipLogic

API key: ваш ключ API ShipLogic из портала The Courier Guy. Он никогда не показывается покупателям и не записывается в журнал. После сохранения поле остаётся пустым и показывает Saved - leave empty to keep it. Вводите новое значение, только если хотите его изменить. Отметьте Remove the saved API key и сохраните, чтобы удалить ключ.

Account ID: необязательно. Числовой ID аккаунта ShipLogic, нужен только если ваш ключ имеет доступ к нескольким аккаунтам. Значение, не являющееся числом, не сохраняется.

Актуальные тарифы (для адресов в ЮАР; если актуальный тариф недоступен, используется таблица цен)

Актуальный тариф — это самый дешёвый сервис ShipLogic от адреса отправителя до адреса покупателя (курьер) или до локера, ближайшего к городу покупателя (локер). Нужны ключ API, адрес отправителя и, для магазинов, которые работают не в рэндах, курс пересчёта.

Price source: откуда берётся цена.

ZAR conversion rate: ShipLogic выставляет тарифы в южноафриканских рэндах (ZAR). Если валюта магазина по умолчанию не ZAR, укажите, сколько стоит 1 ZAR в вашей валюте, например 0.05. Значение должно быть больше 0. Без него актуальные тарифы не используются, и действует таблица цен. Если валюта магазина — ZAR, оставьте поле пустым. Курс не обновляется автоматически.

Адрес отправителя (откуда The Courier Guy забирает посылки в ЮАР)

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

Sender company: название вашей компании.

Sender street address: например, 12 My Road.

Sender suburb: район адреса отправителя.

Sender city: город адреса отправителя.

Sender province: выберите одну из 9 провинций ЮАР в списке.

Sender postal code: почтовый индекс адреса отправителя.

Таблица цен (ваши цены в валюте магазина по умолчанию, без налогов: используется с Price table only, за пределами ЮАР и всякий раз, когда актуальный тариф недоступен; допускается десятичная запятая или точка)

Calculation type: применяется только к таблице цен. Актуальный тариф всегда рассчитывается на весь заказ.

Prices by weight: таблица стран со столбцом Price и весовыми диапазонами XS (до 1 кг), S (до 2 кг), M (до 3 кг), L (до 5 кг) и XL (более 5 кг). Нажмите Add row, чтобы добавить строку (новая строка начинается с ЮАР), и кнопку удаления, чтобы удалить строку. Пустой или нулевой диапазон использует столбец Price. Цена 0 означает бесплатную доставку. Строка * Any country применяется к странам без собственной строки и к строке страны без цены. Цена, которая не является числом, очищается, и страница показывает её в списке.

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

Условия (оба варианта)

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

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

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

Free shipping from: промежуточная сумма корзины, начиная с которой доставка бесплатна. Оставьте поле пустым, чтобы никогда не предлагать бесплатную доставку. Когда сумма достигает этого значения, варианты показываются с ценой 0, и запрос к ShipLogic для тарифа не отправляется.

Доступность

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

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

Delivery type without zones: Courier to the door (по умолчанию) или TCG locker (customer chooses a locker). Используется только вместе с Ignore shipping zones. Другой тип по-прежнему подчиняется Geo zone.

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

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

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

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

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

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

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

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

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

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

Courier to the door: расширение запрашивает у ShipLogic самый дешёвый сервис от вашего адреса отправителя до адреса покупателя. В адресе должны быть улица, город, провинция и почтовый индекс. До этого используется таблица цен.

TCG locker: актуальный тариф — это самый дешёвый сервис «от двери до локера» до локера, ближайшего к городу покупателя. Он не пересчитывается для локера, который выбрал покупатель. Вариант с локером появляется только для адресов в ЮАР и только при наличии ключа API.

Весь заказ рассчитывается как одна посылка: общий вес, самая длинная сторона, наибольшая ширина и суммарная высота. Товары без размеров считаются кубами 10 см. Вес и размеры пересчитываются из весовых и линейных классов товаров. Сумма в рэндах конвертируется в валюту магазина по умолчанию, округляется до её знаков после запятой и показывается покупателю в его валюте с налогом выбранного налогового класса.

Запросы к ShipLogic прерываются по истечении 12 секунд. Тарифы кэшируются на 1 час, локеры — на 6 часов, ошибки — на 10 минут, поэтому медленный API не замедляет каждое обновление оформления заказа. Если актуального тарифа нет, цена берётся из таблицы, затем из Fallback cost. Если ни один из источников не подходит, вариант скрывается. Ошибки API никогда не показываются покупателю.

Расширение не оформляет отправления, не создаёт накладные и этикетки и не обновляет отслеживание автоматически. Карты локеров нет: локеры выбираются из списка. Актуальные тарифы и локеры работают только для ЮАР. Для других стран используется таблица цен. На каждый вариант показывается только один тариф (самый дешёвый уровень сервиса), без выбора уровней сервиса, страховки или дополнительных услуг на этапе оформления заказа.

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

Пункты выдачи

Когда покупатель выбирает вариант с локером на шаге способа доставки, под ним появляется выбор локера: поле поиска (по умолчанию — город адреса доставки) и список локеров с названием, адресом и часами работы. Покупатель может ввести другой город, район или почтовый индекс и нажать Search. Локер нужно выбрать до того, как покупатель сможет продолжить; иначе на шаге появится сообщение Please choose a The Courier Guy locker.

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

Если ShipLogic недоступен, выбор локера показывает сообщение Lockers cannot be loaded right now. You can place the order without choosing one - the store will contact you about the locker. Тогда заказ можно оформить без локера. На странице заказа в админ-панели он отмечается: Not chosen - ShipLogic was unavailable at checkout. Agree the locker with the customer.

В OpenCart 4 выбор локера появляется в окне Shipping method options, под вариантом с локером, и загружается заново каждый раз при открытии окна, потому что адрес на одностраничном оформлении заказа может измениться. Кнопка Continue окна не продолжает оформление без локера из списка, с тем же сообщением, и недоступность ShipLogic тоже не блокирует заказ. OpenCart 4 хранит один заказ для оформления и обновляет его каждый раз, когда покупатель снова подтверждает выбор, а локер заказа обновляется вместе с ним.

Заказы

Выбранный локер добавляется к способу доставки заказа, например: «The Courier Guy locker: название — адрес». Этот текст появляется в Sales > Orders, на странице заказа покупателя, в счёте и в письмах о заказе.

На странице заказа в Sales > Orders над историей выводится панель The Courier Guy для каждого заказа, отправленного через The Courier Guy. Для заказа с локером она показывает название, ID и провайдера локера, а также not verified (ShipLogic was unavailable at checkout), если локер не удалось проверить, или сообщение Not chosen, если ShipLogic был недоступен. Панель отображается, даже когда расширение отключено.

The Courier Guy tracking reference: оформите посылку в личном кабинете The Courier Guy, введите её номер в это поле панели и нажмите Save. Чтобы удалить номер, очистите поле и сохраните. Администраторы без права изменения заказов видят номер только для чтения. Покупатель видит номер на странице заказа в своём аккаунте (зарегистрированные покупатели) и в письмах о статусе заказа, когда вы уведомляете покупателя. В письме о новом заказе номера нет, потому что его вводят позже.

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

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

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

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

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

The Courier Guy does not appear at checkout: проверьте, что лицензия активна и вариант включён (Courier to the door или TCG locker). Проверьте Geo zone (или Ignore shipping zones и Countries), ограничения по весу и Minimum order amount. Убедитесь, что в таблице или в Fallback cost есть цена. Убедитесь, что у товаров Requires Shipping установлено Yes. Вариант с локером появляется только для адресов в ЮАР и при наличии ключа API.

Customers see no locker list: для локеров нужны ключ API, включённый TCG locker и адрес доставки в ЮАР. На странице настроек показана последняя ошибка ShipLogic, если она есть, например, отклонённый ключ.

The price is always the table price: проверьте предупреждения на странице настроек. Для актуального тарифа нужны ключ API, полный адрес отправителя и, для магазинов не в рэндах, курс ZAR. Для курьерской доставки адрес покупателя должен содержать улицу, город, провинцию (зону) и почтовый индекс. Для локеров ShipLogic должен найти локер рядом с городом покупателя. Включите Debug log, обновите оформление заказа и посмотрите поле Log на странице расширения.

ShipLogic is down: показывается цена из таблицы или резервная цена. Заказы с локером можно оформить без локера, и они отмечаются в заказе.

Rates look outdated after a change: нажмите Save на странице расширения. Это очистит кэшированные тарифы и локеры.

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

For developers: адрес API ShipLogic можно заменить настройкой vfd_tcgr_api_url (для тестов); для неё нет поля на странице настроек.

Удаление

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

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

The Courier Guy и ShipLogic являются товарными знаками их соответствующих владельцев. Это расширение не связано с The Courier Guy или ShipLogic и не одобрено ими.