VibeFox Aramex for OpenCart — Помощь

Требования

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

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

Аккаунт Aramex (только для живых тарифов): живые тарифы используют Aramex Rate Calculator API. Aramex предоставляет доступ к API владельцам своих аккаунтов. Уточните у своего менеджера Aramex или посмотрите Aramex Developers Solution Center на сайте Aramex. Нужны шесть значений: имя пользователя API (обычно адрес электронной почты), пароль, номер аккаунта, PIN аккаунта, код подразделения аккаунта (например, DXB) и код страны аккаунта (например, AE). Если вы используете только фиксированные цены по странам, аккаунт Aramex не нужен.

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

Установка

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

OpenCart 3

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

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

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

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

5. Выберите способ расчёта стоимости доставки, заполните соответствующие разделы (см. Настройка), включите Enable Aramex и нажмите Save.

OpenCart 4

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

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

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

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

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Shipping > VibeFox Aramex > Edit. Разделы перечислены слева. Одна кнопка Save внизу сохраняет всю страницу без перезагрузки. Каждое сохранение также очищает закэшированные тарифы Aramex. Если значение неверно, ничего не сохраняется, и страница показывает причину, например Enter a method title (1 to 64 characters)., сообщение о том, что поле должно быть числом, или The account country code must have 2 letters, e.g. AE. Сохранять настройки могут только администраторы с правом изменения этого расширения.

Общие

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

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

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

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

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

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

Аккаунт Aramex API (нужен только для живых тарифов; все шесть полей обязательны)

Username: ваше имя пользователя Aramex API, обычно адрес электронной почты. Очистка поля также удаляет сохранённый пароль.

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

Account number: номер вашего клиентского аккаунта Aramex. Очистка поля также удаляет сохранённый PIN.

Account PIN: PIN вашего аккаунта Aramex. Как и пароль, после сохранения он больше не показывается.

Account entity: код подразделения (офиса) Aramex вашего аккаунта, например DXB, AMM или RUH.

Account country code: двухбуквенный код страны вашего аккаунта Aramex, например AE.

Услуга Aramex (для живых тарифов)

Если адрес доставки находится в стране отправления, отправление рассчитывается как Domestic. Все остальные отправления рассчитываются как International express.

International service: услуга Aramex для отправлений за границу: PPX Priority Parcel Express (по умолчанию), PDX Priority Document Express, PLX Priority Letter Express (документы до 0,5 кг), DPX Value Express Parcels, EPX Economy Parcel Express, EDX Economy Document Express, GPX Ground Parcel Express или GDX Ground Document Express.

Domestic service: услуга Aramex для отправлений внутри страны отправления: ONP Overnight (Parcel) (по умолчанию), OND Overnight (Document), SMP Same Day (Parcel), SMD Same Day (Document), SDD Same Day Delivery, EMD Early Morning Delivery, PEC Economy Delivery, PEX Road Express или HVY Heavy (20 кг и более).

Payment type: кто оплачивает отправление Aramex: Prepaid (shipper pays) (по умолчанию), Collect (receiver pays) или Third party. Обычно Prepaid.

API weight unit: единица, которая отправляется в Aramex: Kilograms (KG) (по умолчанию) или Pounds (LB). Веса товаров переводятся из их класса веса, размеры — из класса длины. Тарифицируемый вес — большее из фактического веса и объёмного веса (длина × ширина × высота в см / 5000). Минимум — 0,5 кг; это действует и для товаров без веса.

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

Отправление из (для живых тарифов)

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

Origin city: город, из которого вы отправляете. Aramex его требует. Адрес магазина в OpenCart — свободный текст, поэтому город из него не берётся: введите его здесь.

Origin state / emirate: необязательно.

Origin postcode: необязательно.

Если страна отправления — страна вашего магазина, пустой регион берётся из региона магазина в System > Settings > Store > Local.

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

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

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

Условия

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

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

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

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

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

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

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

Countries: предлагать Aramex только для этих стран назначения. Оставьте поле пустым, чтобы разрешить все страны. Это ограничение действует вместе с Geo zone.

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

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

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

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

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

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

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

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

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

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

Каждый ответ кэшируется на 1 час, чтобы одна и та же корзина не вызывала новый запрос. Неудачный запрос кэшируется на 10 минут, чтобы оформление заказа не ждало Aramex при каждом обновлении. Тайм-аут API — 10 секунд.

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

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

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

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

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

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

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

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

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

Живые тарифы не появляются: включите Debug log, перезагрузите оформление заказа и посмотрите поле Log на странице расширения. Там указана причина: нет данных для входа в API, код ошибки Aramex, нет города отправления, нет города или почтового индекса доставки, ограничение по весу или сумме либо тариф в другой валюте. С Aramex live rates, fixed prices if the API fails покупатели всё равно получают фиксированную цену, пока вы исправляете проблему.

Ошибка ERR75 в журнале: Aramex отклонил вход. Проверьте имя пользователя, пароль, номер аккаунта, PIN, подразделение и код страны у своего менеджера Aramex.

Тариф в другой валюте отклоняется: Aramex ответил в валюте, отличной от валюты магазина по умолчанию. Введите Currency conversion rate или попросите Aramex рассчитать тариф в вашей валюте.

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

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

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

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

Удаление

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

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

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