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.