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

Вимоги

PrestaShop: 8.0–9.x.

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

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

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

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

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

1. У бек-офісі перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

2. Після завершення завантаження натисніть Configure або пізніше знайдіть VibeFox SMSA Express у списку модулів і натисніть Configure.

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

4. Введіть ціни SMSA Express у таблицю цін і натисніть Save.

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

Під час встановлення модуль створює перевізника SMSA Express з текстом строку доставки SMSA Express courier. Перевізник призначається всім зонам і всім групам клієнтів. Зони, групи клієнтів, строк доставки, логотип і обмеження розмірів можна змінити в Shipping > Carriers. Не встановлюйте там ціни: ціна завжди береться з модуля.

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox SMSA Express > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Кожне збереження також очищає кеш тарифів SMSA. Значення, що не є числом, від'ємне число, курс обміну 0, код валюти не з 3 літер або Minimum weight більше за Maximum weight відхиляються з помилкою, і нічого не зберігається, доки ви не виправите значення.

Коли актуальні тарифи увімкнено, попередження над налаштуваннями повідомляють про відсутній passKey, місто відправлення або курс обміну чи про порожню таблицю цін. Також з'являється попередження, якщо модуль не знає одиницю ваги магазину (тоді ваги товарів читаються як кг). Вкажіть kg, g, lb або oz у International > Localization (Local units).

Загальні

Enable SMSA Express: вмикає або вимикає перевізника у всіх зонах одночасно. Це той самий перемикач, що й статус перевізника в Shipping > Carriers.

Method title: назва перевізника, яка показується в кошику та під час оформлення замовлення. За замовчуванням: SMSA Express. Обов'язково, до 64 символів.

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

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

Live charges: отримувати вартість доставки від SMSA Express. За замовчуванням: вимкнено.

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. Залиште поле порожнім, щоб використати місто магазину з Shop Parameters > Contact > Stores.

Ship-from country: країна, звідки відправляються ваші посилки. За замовчуванням це країна вашого магазину.

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

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

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

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

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

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

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

Ваги товарів переводяться з одиниці ваги вашого магазину в кілограми.

Умови

Minimum weight: приховати перевізника, коли кошик важить менше, у кг. 0 — без обмеження.

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

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

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

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

Зазвичай перевізник пропонується в зонах, до яких він прив'язаний у Shipping > Carriers.

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

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

Додатково

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

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

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

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

На кроці доставки PrestaShop запитує у модуля ціну SMSA Express. Враховуються лише фізичні товари: віртуальні товари не додають ваги і не входять до суми замовлення. Модуль спочатку перевіряє умови: країни з Ignore shipping zones (якщо увімкнено), вагу кошика і мінімальну суму замовлення. Якщо діє безкоштовна доставка, ціна дорівнює 0 і запит до SMSA не надсилається.

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

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

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

Якщо ви редагуєте перевізника в Shipping > Carriers після того, як у нього з'явилися замовлення, PrestaShop зберігає його як нову версію перевізника. Модуль автоматично переходить на нову версію.

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

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

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

Без активного ключа перевізник SMSA Express не показується покупцям під час оформлення замовлення, і тариф не розраховується. Вітрина PrestaShop не знає, що ви увійшли в бек-офіс, тому перевізник приховано і для вас: ви можете налаштувати модуль до купівлі ключа, але не можете перевірити його під час оформлення замовлення. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються.

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

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

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

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

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

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

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

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

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

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

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox SMSA Express і оберіть Uninstall. Ліцензійний ключ і статус ліцензії завжди видаляються. Кешовані тарифи завжди видаляються. Якщо Remove data on uninstall увімкнено, перевізника буде видалено (замовлення зберігають свою історію), а налаштування і журнал стираються. Якщо вимкнено, перевізника лише деактивують, і всі налаштування зберігаються. Повторне встановлення модуля або Reset повертає перевізникові той статус, який був раніше.

SMSA Express — торгова марка її власника. Цей модуль не пов'язаний із SMSA Express і не схвалений нею.