VibeFox Australia Post for OpenCart — Помощь

Требования

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

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

Ключ PAC API Australia Post (только для живых тарифов): живые тарифы используют API Postage Assessment Calculator (PAC) от Australia Post. Ключ бесплатный: зарегистрируйтесь для получения ключа PAC API в Australia Post Developer Centre (developers.auspost.com.au). На странице настроек есть ссылка на страницу регистрации. Также нужен четырёхзначный австралийский почтовый индекс, из которого вы отправляете. Если вы используете только фиксированные цены по странам, ключ API не нужен.

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

Установка

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

OpenCart 3

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

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

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

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

5. Выберите Rate source (источник тарифов). Для фиксированных цен добавьте строки в Country prices. Для живых тарифов введите ключ PAC API, почтовый индекс отправления и, если валюта по умолчанию вашего магазина не AUD, курс пересчёта в AUD (см. Настройка). Включите Enable Australia Post и нажмите Save.

OpenCart 4

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

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

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

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

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

Настройка

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

Некоторые ошибки не дают сохранить настройки, и тогда ничего не сохраняется: Method title длиннее 64 символов, Sort order, который не является целым числом, или неизвестный налоговый класс или гео-зона. Другие проблемы показываются как предупреждения над панелью, а остальные настройки сохраняются. Числовое поле с значением, которое не является числом или отрицательно, сохраняет предыдущее значение, а предупреждение называет поле. Числовые поля принимают точку или запятую как десятичный разделитель.

Если выбран источник живых тарифов, но не заполнены ключ API, четырёхзначный почтовый индекс отправления или курс AUD, после сохранения показывается предупреждение. Оно также сообщает, что происходит до исправления: способ доставки скрыт на оформлении заказа или в режиме запасного варианта используются фиксированные цены по странам. Страница также предупреждает, если в вашем магазине нет класса веса с единицей kg или класса длины с единицей cm. Тогда веса и размеры товаров переводятся по единице их класса (kg, g, lb, oz; cm, mm, m, in), а остальные единицы читаются как кг и см.

General

Настройки действуют для всех гео-зон. Ограничить способ доставки гео-зоной можно в Conditions, или списком стран в Availability without shipping zones.

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

Method title: название способа доставки, которое покупатель видит в корзине и при оформлении заказа. По умолчанию: Australia Post. Не более 64 символов: более длинное название отклоняется, и ничего не сохраняется. Если поле пустое, показывается предупреждение, и используется Australia Post.

Rate source: как рассчитывается цена.

Подробности ошибок попадают в журнал, но не покупателю.

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

API Australia Post (живые тарифы) (не нужно для фиксированных цен)

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

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

Ship-from postcode: четырёхзначный австралийский почтовый индекс, из которого отправляются посылки, например 2000.

Domestic service: используется для доставки внутри Австралии (до 22 кг, 105 см по каждой стороне): Parcel Post (по умолчанию) или Express Post.

International service: используется для доставки за пределы Австралии (до 20 кг): International Standard (по умолчанию), International Express или International Courier.

Remove GST: делит внутренние цены API на 1,1. Внутренние цены Australia Post включают 10 % GST. Включите эту опцию, когда OpenCart сам добавляет налог к доставке (выбран Tax class), чтобы GST не начислялся дважды. Международная пересылка не облагается GST и никогда не изменяется.

AUD → (your currency) rate: в надписи указана валюта по умолчанию вашего магазина. Цены Australia Post указаны в AUD. Если валюта по умолчанию не AUD, введите, сколько единиц вашей валюты стоит один AUD, например 0,61. Курс должен быть больше 0. Без него живые тарифы не используются. Если валюта по умолчанию — AUD, поле сообщает, что пересчёт не нужен: оставьте его пустым.

Посылка для живых тарифов

Корзина отправляется как одна посылка. Веса и размеры товаров переводятся из классов веса и длины OpenCart в кг и см. Значения ниже используются для товаров без веса или размеров.

Default product weight (kg): используется для каждого товара без веса, в запросе к Australia Post и в проверке Min cart weight (kg) / Max cart weight (kg). По умолчанию: 1.

Default parcel length (cm): используется, когда ни у одного товара в корзине нет размеров. По умолчанию: 22.

Default parcel width (cm): используется, когда ни у одного товара в корзине нет размеров. По умолчанию: 16.

Default parcel height (cm): используется, когда ни у одного товара в корзине нет размеров. По умолчанию: 8.

Когда у товаров есть размеры, посылка берёт наибольшие длину и ширину среди них, а высота увеличивается, пока посылка не вместит объём всех товаров.

Фиксированные цены (используются с фиксированными ценами и как запасной вариант для живых тарифов)

Country prices: список стран и цен в валюте по умолчанию вашего магазина, без налогов. Нажмите Add row, чтобы добавить строку, и кнопку ×, чтобы удалить строку. Выберите * All other countries для цены, которая действует для каждой страны без собственной строки. Страна без цены (и без строки *) не получает фиксированного тарифа, поэтому способ доставки для неё скрыт. Строки без цены удаляются при сохранении. Таблица пуста, пока вы не добавите цены.

Fixed price per: Order (по умолчанию) взимает цену один раз. Item (price × quantity) умножает её на количество товаров в корзине. Это относится только к фиксированным ценам. Живые тарифы всегда рассчитываются на всю посылку.

Условия

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

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

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

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

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

Tax class: налоговый класс стоимости доставки или No tax (по умолчанию). Внутренние цены Australia Post включают GST: при выбранном налоговом классе включите Remove GST.

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

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

Обычно способ доставки предлагается в гео-зоне, выбранной в Conditions (All zones означает везде).

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

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

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

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

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

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

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

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

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

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

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

В режиме фиксированных цен цена берётся из таблицы. В режимах живых тарифов расширение отправляет в Australia Post вес посылки и, для доставки внутри Австралии, почтовые индексы отправления и доставки и размеры посылки; для международной доставки — страну назначения. Внутренний живой тариф запрашивается, только если в адресе доставки есть четырёхзначный почтовый индекс. Запрос не отправляется, если посылка выходит за пределы Australia Post (22 кг или 105 см внутри страны, 20 кг за рубеж). Цена в AUD пересчитывается по вашему курсу, а GST вычитается из внутренних цен, если включено Remove GST. Цена рассчитывается в валюте магазина по умолчанию, округляется до её знаков после запятой и показывается покупателю в его валюте с налогом выбранного Tax class.

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

Расширение только рассчитывает тарифы. Оно не создаёт этикетки, отправления и манифесты eParcel или MyPost Business, не отслеживает посылки и не позволяет покупателям выбирать постаматы или почтовые отделения. Оно ничего не добавляет к заказам: в заказе показываются название способа доставки и стоимость доставки, как для любого другого способа доставки OpenCart. Корзина всегда рассчитывается как одна посылка. Письма, конверты и договорные тарифы (eParcel) не учитываются.

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

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

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Australia Post — первый блок на странице Extensions > Extensions > Shipping > VibeFox Australia Post > Edit, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату окончания действия лицензии и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: opencart-shipping-australia-post и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт vibefox.net. Менять ключ могут только администраторы с правом изменения расширения. Тексты блока следуют языку администратора (включены английский и русский).

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

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

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

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

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

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

Живые тарифы не появляются: включите Debug log, перезагрузите оформление заказа и посмотрите поле Log на странице расширения. Там указана причина: нет ключа API или почтового индекса отправления, ещё нет четырёхзначного почтового индекса доставки, посылка выходит за пределы, нет курса AUD или сообщение об ошибке от Australia Post. С Live rates, fixed price if the API gives no rate покупатели всё равно получают фиксированную цену, пока вы исправляете проблему.

Мой магазин не в AUD: введите курс (сколько единиц валюты по умолчанию стоит один AUD) в поле AUD → (your currency) rate. Фиксированные цены всегда указываются в валюте по умолчанию.

GST начисляется на доставку дважды: внутренние цены Australia Post включают 10 % GST. Если выбран Tax class, включите Remove GST или установите Tax class в No tax.

Цена слишком высокая или слишком низкая: проверьте веса и размеры товаров, их классы веса и длины, а также значения по умолчанию в Parcel for live rates. При Item (price × quantity) фиксированные цены умножаются на количество товаров.

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

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

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

Удаление

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

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

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