VibeFox SMSA Express for OpenCart — Допомога

Вимоги

OpenCart: 3.0.x (перевірено на 3.0.5.0) або 4.0.2 і новіша (перевірено на 4.1.0.3).

PHP: 8.0 або новіша.

Прайс SMSA Express: ціни для таблиці беруться з вашого облікового запису SMSA або від відділу продажів SMSA. Вводьте їх у валюті магазину за замовчуванням. Якщо ваш прайс у SAR, AED або іншій валюті, спочатку перерахуйте його.

passKey SMSA (лише для тарифів у реальному часі): тарифи в реальному часі використовують веб-сервіс SMSA (SECOM, операція getShipCharges). SMSA видає passKey за запитом: зверніться до свого менеджера облікового запису SMSA або напишіть на info@smsaexpress.com. passKey може відрізнятися від API-ключа порталу електронної комерції SMSA. Для цієї служби SMSA не надає тестового сервера (sandbox).

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

Встановлення

Завантаження — це один zip-файл із пакетами для обох версій OpenCart. Розпакуйте його на своєму комп'ютері. Він містить README.txt, пакет для OpenCart 3 vfd_smsa_express-oc3-(version).ocmod.zip і пакет для OpenCart 4 vfd_smsa_express.ocmod.zip. Встановлюйте лише пакет для вашої версії OpenCart. Ліцензійний ключ однаковий для обох версій.

OpenCart 3

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

2. Перейдіть до Extensions > Extensions і виберіть тип розширення Shipping. Знайдіть VibeFox SMSA Express і натисніть Install (зелена кнопка +).

3. Натисніть Edit (кнопка з олівцем), щоб відкрити сторінку налаштувань.

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

5. Введіть ваші ціни SMSA Express у таблицю цін.

6. За бажанням: у розділі Live rates (API) увімкніть Live charges, введіть ваш passKey SMSA, місто та країну відправлення і, якщо валюта магазину за замовчуванням не SAR, курс обміну.

7. Увімкніть Enable SMSA Express і натисніть Save.

OpenCart 4

1. В адмін-панелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл vfd_smsa_express.ocmod.zip. Не перейменовуйте файл: OpenCart 4 бере код розширення з імені файлу, і перейменований пакет не працює.

2. Пакет з'являється в списку встановлених розширень на тій самій сторінці. Натисніть біля нього Install (зелена кнопка +).

3. Перейдіть до Extensions > Extensions і виберіть тип розширення Shipping. Знайдіть VibeFox SMSA Express, натисніть Install (зелена кнопка +), потім Edit (кнопка з олівцем).

4. Введіть ліцензійний ключ і налаштування так само, як у кроках 4–7 для OpenCart 3. Сторінка налаштувань і її поля однакові в обох версіях.

Після встановлення спосіб вимкнено, доки ви не увімкнете Enable SMSA Express і не збережете. Якщо ви встановите розширення повторно після видалення, збережені налаштування SMSA Express знову будуть використані.

Налаштування

Усі налаштування знаходяться на сторінці розширення: Extensions > Extensions > Shipping > VibeFox SMSA Express > Edit. Розділи перелічено ліворуч. Одна кнопка Save зберігає всю сторінку без перезавантаження. Кожне збереження також очищує кешовані тарифи SMSA. Некоректна назва способу, значення, що не є числом, від'ємне число, курс обміну 0, код валюти не з 3 літер, помилкова ціна в таблиці, Minimum weight (kg), більший за Maximum weight (kg), або порядок сортування, який не є цілим числом, відхиляються з помилкою, і нічого не зберігається, доки ви не виправите. Зберігати налаштування можуть лише адміністратори з правом змінювати це розширення.

Коли тарифи в реальному часі увімкнено, попередження над налаштуваннями повідомляють про відсутній passKey, місто відправлення або курс обміну, а також про порожню таблицю цін. Попередження також з'являється, якщо в магазині немає класу ваги kg, а його одиниця ваги за замовчуванням невідома розширенню (тоді ваги товарів читаються як kg). Додайте клас ваги kg у System > Localisation > Weight Classes.

Загальні

Налаштування застосовуються до всіх геозон. Ви можете обмежити спосіб геозоною в Conditions або списком країн через Ignore shipping zones.

Enable SMSA Express: показує або приховує SMSA Express під час оформлення замовлення. За замовчуванням: вимкнено.

Method title: назва способу доставки, яку бачить покупець у кошику та під час оформлення замовлення. За замовчуванням: SMSA Express. Обов'язкове поле, не більше 64 символів, без символів < > ; = # { }.

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

Тарифи в реальному часі (API) (необов'язково; якщо SMSA не повертає вартість, використовується таблиця цін)

Live charges: отримувати вартість доставки від SMSA Express. Коли вимкнено, під час оформлення замовлення нічого не надсилається до SMSA. За замовчуванням: вимкнено.

SMSA passKey: ключ веб-сервісу SMSA (SECOM). Після збереження поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити. Позначте Remove the saved passKey, щоб видалити його. Якщо журнал показує "Invalid Passkey", цей сервіс не приймає ключ. Запитайте в SMSA passKey для веб-сервісу.

Ship-from city: місто, з якого відправляються ваші посилки, написане так, як це робить SMSA, наприклад Riyadh, Jeddah або Dammam. Обов'язкове для тарифів у реальному часі: в OpenCart немає міста магазину, тому воно ніколи не береться з адреси магазину.

Ship-from country: країна, з якої відправляються ваші посилки. Перший варіант, Store country, використовує країну вашого магазину з System > Settings > Store > Local. Це значення за замовчуванням.

Shipment type: надсилається до SMSA як тип відправлення. DLV (значення за замовчуванням) — стандартна доставка. Змінюйте, лише якщо SMSA дав вам інший код.

Currency of SMSA charges: тризначний код валюти, у якій SMSA повертає вартість, зазвичай SAR (за замовчуванням). Тариф у будь-якій валюті, окрім цієї або валюти магазину за замовчуванням, не використовується.

Exchange rate: ціна 1 одиниці валюти SMSA у валюті магазину за замовчуванням, наприклад 0.27. Не потрібен, якщо обидві валюти однакові. Без нього тарифи в іншій валюті не використовуються, і застосовується таблиця цін.

Ціни (ваш прайс SMSA Express у валюті магазину за замовчуванням; використовується, коли тарифи в реальному часі вимкнено, і як резервний варіант, коли SMSA не повертає вартість)

Price table: один рядок на країну призначення. Натисніть Add country, щоб додати рядок. Рядок * All other countries застосовується до країн без власного рядка. Кожен рядок має ціну Base і вагові колонки: XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg і XL >5 kg. Порожня або нульова вагова колонка використовує базову ціну. Базова ціна 0 означає безкоштовну доставку. Рядки без жодної ціни не зберігаються. Якщо в країни два рядки, використовується перший. Приймаються обидва варіанти: "9.99" і "9,99".

Price for countries not in the table: використовується, коли в таблиці немає рядка для країни призначення (і немає рядка *) або в рядку немає ціни для цієї ваги. Залиште порожнім, щоб приховати спосіб у цьому випадку.

Price applies: як розраховується ціна.

Ваги товарів перераховуються з їхнього класу ваги OpenCart у кілограми.

Умови

Minimum weight (kg): приховувати спосіб, коли кошик важить менше. 0 означає без обмеження (за замовчуванням).

Maximum weight (kg): приховувати спосіб, коли кошик важить більше. За замовчуванням: 30. 0 або порожнє поле означає без обмеження.

Minimum order amount: показувати спосіб, лише коли сума товарів, що потребують доставки (після купона, без податків), досягає цієї суми. Залиште порожнім, щоб показувати завжди.

Free shipping from: сума товарів, що потребують доставки (після купона, без податків), починаючи з якої доставка SMSA Express безкоштовна. Коли кошик її досягає, ціна дорівнює 0, і запит до SMSA не надсилається. Залиште порожнім, щоб ніколи не пропонувати безкоштовну доставку.

Tax class: податковий клас вартості доставки або No tax (за замовчуванням). Виберіть No tax, якщо ваші ціни (таблиця та тарифи SMSA) вже містять податок, наприклад ПДВ Саудівської Аравії.

Geo zone: пропонувати SMSA Express лише для адрес у цій геозоні. All zones (за замовчуванням) означає без обмеження. Не перевіряється, поки увімкнено Ignore shipping zones. Геозони керуються в System > Localisation > Geo Zones.

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

Зазвичай спосіб пропонується для адрес геозони, обраної в Conditions.

Ignore shipping zones: пропонувати SMSA Express для країн, зазначених нижче, незалежно від геозони. Коли вимкнено, рішення ухвалює геозона, а список країн не використовується.

Countries: країни призначення для цього режиму. Залиште порожнім, щоб використовувати всі увімкнені в магазині країни. Це поле використовується, лише якщо увімкнено Ignore shipping zones.

Додатково

Debug log: записує розрахунки тарифів у storage/logs/vfd_smsa_debug.log.php. Файл неможливо прочитати з веб-браузера. Адреси покупців і ключі не записуються. Помилки тарифів у реальному часі записуються завжди, навіть коли цю опцію вимкнено. Вимкніть журнал, коли закінчите. Коли файл досягає 5 МБ, його переносять до vfd_smsa_debug.old.log.php, і починається новий журнал.

Log: показує розмір і останні записи журналу налагодження. Натисніть Clear log, щоб очистити його.

Remove data on uninstall: якщо увімкнено, видалення розширення стирає налаштування SMSA Express і журнал налагодження. Якщо вимкнено (за замовчуванням), налаштування зберігаються для повторного встановлення. Кешовані вартості завжди видаляються.

Імпорт / Експорт

Export: натисніть Download JSON, щоб зберегти налаштування у файл JSON. passKey не експортується.

Import: вставте раніше експортований JSON і натисніть Import, щоб відновити налаштування, наприклад в іншому магазині. Значення перевіряються так само, як під час звичайного збереження. Збережений passKey залишається.

Як це працює під час оформлення замовлення

Коли OpenCart показує способи доставки, він запитує у розширення ціну SMSA Express. Якщо задано Geo zone (і Ignore shipping zones вимкнено) та адреса поза нею, SMSA Express не пропонується. Враховуються лише товари з Requires Shipping, встановленим у Yes: інші не додають ваги і не входять до суми замовлення. Далі розширення перевіряє умови: країни з Ignore shipping zones (якщо увімкнено), вагу кошика та мінімальну суму замовлення. Подарункові сертифікати, бонусні бали та кредит магазину не враховуються. Якщо діє безкоштовна доставка, ціна дорівнює 0, і запит до SMSA не надсилається.

Коли тарифи в реальному часі увімкнено, розширення надсилає до SMSA місто та країну відправлення, місто та країну покупця, тип відправлення, вагу посилки в кг і суму накладеного платежу 0. SMSA відповідає вартістю та її валютою. Розширення перераховує її у валюту магазину за замовчуванням і округлює до його десяткових знаків. Потім ціна показується у валюті покупця з податком обраного Tax class. Тариф у реальному часі запитується лише після того, як покупець ввів адресу доставки з містом.

Кожна вартість кешується на одну годину, щоб та сама корзина не спричиняла новий запит. Невдалий запит кешується на 5 хвилин. Після тайм-ауту або помилки сервера SMSA не запитується 2 хвилини. Після відхиленого ключа SMSA не запитується 5 хвилин. Так оформлення замовлення ніколи не чекає на службу, що не працює, під час кожного оновлення. Тайм-аут запиту становить 12 секунд.

Щоразу, коли SMSA не повертає придатного тарифу (немає passKey, місто ще не введено, недійсний ключ, тайм-аут, помилка, немає сервісу до міста або невідома валюта), використовується таблиця цін. Якщо таблиця та Price for countries not in the table не дають ціни, спосіб приховується. Покупець ніколи не бачить помилку. Причина записується до журналу.

Розширення лише розраховує вартість доставки. Воно не створює відправлень SMSA, не друкує етикетки AWB, не обробляє повернення та не відстежує посилки. Накладений платіж і його комісія не входять до тарифу в реальному часі. Вибору пункту видачі SMSA немає: спосіб — доставка до дверей. Розширення нічого не додає до замовлень: замовлення показує назву способу та вартість доставки, як і будь-який інший спосіб доставки OpenCart.

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

Ліцензійний ключ

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

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

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

Усунення несправностей

SMSA Express не з'являється під час оформлення замовлення: переконайтеся, що ліцензія активна і Enable SMSA Express увімкнено. Перевірте Geo zone (або, якщо Ignore shipping zones увімкнено, Countries), обмеження ваги та Minimum order amount. Перевірте, що для країни або * є ціна, або задано Price for countries not in the table. Переконайтеся, що товари мають Requires Shipping, встановлене в Yes.

Покупці бачать ціну з таблиці замість вартості SMSA: SMSA потребує міста покупця, тому доки його не введено, показується ціна з таблиці. Таблиця також використовується, коли SMSA не відповідає, відхиляє ключ або місто, або повертає вартість у валюті без курсу обміну. Причину дивіться в полі Log на сторінці розширення.

"Invalid Passkey" у журналі: ключ не приймається веб-сервісом SMSA. Запитайте в SMSA passKey для веб-сервісу.

Місто покупця не приймається: SMSA очікує власний варіант написання міст. Перевірте місто в адресі доставки та Ship-from city.

Налаштування не зберігаються і з'являється помилка: числове поле містить текст або від'ємне значення, курс обміну дорівнює 0, код валюти не з 3 літер або Minimum weight (kg) більший за Maximum weight (kg). Виправте значення, назване в повідомленні, і натисніть Save ще раз.

Податок на доставку стягується двічі: ваш прайс або тарифи SMSA можуть уже містити ПДВ. Встановіть Tax class у значення No tax.

Тарифи виглядають застарілими після змін: натисніть Save на сторінці розширення. Це очистить кешовані тарифи SMSA.

Сторінка показує "Warning: You do not have permission to modify VibeFox SMSA Express!": ваша група адміністраторів може лише переглядати налаштування. Надайте групі право на зміну для extension/shipping/vfd_smsa_express (OpenCart 3) або extension/vfd_smsa_express/shipping/vfd_smsa_express (OpenCart 4) у System > Users > User Groups.

Для розробників: адресу веб-сервісу SMSA можна замінити налаштуванням vfd_smsa_api_url (для тестів); на сторінці налаштувань для нього немає поля.

Видалення

Перейдіть до Extensions > Extensions, виберіть тип Shipping і натисніть Uninstall (червона кнопка −) поруч із VibeFox SMSA Express. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди скидає Enable SMSA Express, Sort order, Tax class і Geo zone. Кешовані тарифи завжди видаляються. Якщо Remove data on uninstall увімкнено, налаштування SMSA Express і журнал налагодження також видаляються. Якщо вимкнено, інші налаштування зберігаються і знову використовуються під час повторного встановлення розширення. Наявні замовлення зберігають свій спосіб доставки та вартість.

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

SMSA Express є торговою маркою її власника. Це розширення не пов'язане з SMSA Express і не схвалено SMSA Express.