VibeFox Aramex for PrestaShop — Помощь

Требования

PrestaShop: 8.0 – 9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более старых версиях PHP.

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

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

Установка

1. В бэк-офисе перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. По окончании загрузки нажмите Configure или позже найдите VibeFox Aramex в списке модулей и нажмите Configure.

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

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

При установке модуль создаёт перевозчика Aramex с текстом срока доставки Courier delivery. Перевозчик назначается всем зонам и всем группам клиентов. Зоны, группы клиентов, срок доставки, логотип и ограничения по размеру можно изменить в Shipping > Carriers. Не задавайте там цены: цена всегда берётся из модуля.

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Aramex > Configure. У каждого раздела своя кнопка Save, которая сохраняет всю страницу. Каждое сохранение также очищает кэш тарифов Aramex.

Общие

Enable Aramex: включает или выключает перевозчика. Это тот же переключатель, что и статус перевозчика в Shipping > Carriers.

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

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

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

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

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

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

Account number: номер вашей клиентской учётной записи Aramex.

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, 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 (оплачивает отправитель), Collect (оплачивает получатель) или Third party (третья сторона). Обычно Prepaid.

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

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

Отправка из (адрес отправления) (используется для тарифов в реальном времени)

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

Origin city: город, из которого вы отправляете. Aramex требует его указать.

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

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

Если страна отправления совпадает со страной магазина, пустые поля заполняются из адреса магазина в Shop Parameters > Contact > Stores.

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

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

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

Условия

Minimum weight: скрывать перевозчика, если корзина весит меньше, в кг. 0 означает без ограничения.

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

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

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

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

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

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

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

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

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

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

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

На этапе доставки PrestaShop запрашивает у модуля цену Aramex. Учитываются только физические товары: виртуальные товары не добавляют вес и не входят в сумму заказа. Модуль сначала проверяет условия: разрешённые страны, вес корзины и минимальную сумму заказа. Если действует бесплатная доставка, цена равна 0 и запрос в Aramex не отправляется.

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

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

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

Если вы редактируете перевозчика в Shipping > Carriers после того, как по нему есть заказы, PrestaShop сохраняет его как новую версию перевозчика. Модуль автоматически использует новую версию.

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

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Aramex — первый блок на странице Modules > Module Manager > VibeFox Aramex > Configure, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой лицензия действительна, и ваш домен), а также кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-shipping-aramex и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока соответствуют языку бэк-офиса (включены английский и русский).

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

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

Без активного ключа перевозчик Aramex не показывается покупателям при оформлении заказа, и тарифы не рассчитываются. Витрина PrestaShop не знает, что вы вошли в бэк-офис, поэтому перевозчик скрыт и для вас: модуль можно настроить до покупки ключа, но нельзя проверить при оформлении заказа. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются.

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

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

Aramex не появляется при оформлении заказа: проверьте, что лицензия активна и Enable Aramex включён. В Shipping > Carriers проверьте, что перевозчик охватывает зону страны покупателя и его группу. Проверьте Countries, ограничения по весу и Minimum order amount. В фиксированном режиме проверьте, что у страны или у * есть цена. Товары также могут быть ограничены определёнными перевозчиками на странице товара.

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

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

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

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

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

Страница сообщает, что перевозчик Aramex не найден: перевозчик был удалён в Shipping > Carriers. Сбросьте модуль в Modules > Module Manager, чтобы создать его заново.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox Aramex и выберите Uninstall. Лицензионный ключ, статус лицензии и кэш тарифов удаляются всегда. Если Remove data on uninstall включён, перевозчик удаляется (заказы сохраняют историю), а настройки и журнал удаляются. Если выключен, перевозчик только отключается, а все настройки сохраняются. Повторная установка модуля снова включает сохранённого перевозчика.

Aramex является товарным знаком его правообладателя. Этот модуль не связан с Aramex и не одобрен компанией Aramex.