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

Вимоги

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

PHP: 8.0 або новіша версія.

Договір із SF Express (лише для актуальних цін): актуальні ціни використовують відкриту платформу FengQiao компанії SF Express (open.sf-express.com). Вам потрібні щомісячний договір із SF Express і обліковий запис розробника на FengQiao. Зареєструйтеся там, створіть застосунок, додайте до нього API "Delivery time standard and price query" (EXP_RECE_QUERY_DELIVERTM) і скопіюйте код клієнта та checkword. Checkword для тестового та робочого середовищ різні. Якщо ви використовуєте лише таблицю цін, обліковий запис SF Express не потрібен.

Провінції Китаю (лише для актуальних цін): для актуальної ціни потрібна провінція адреси доставки, тобто зона OpenCart (Region / State) цієї адреси. В OpenCart є зони Китаю, але Тибету немає. Розширення може додати його за вас (див. Chinese provinces нижче).

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

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

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

OpenCart 3

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

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

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

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

5. Заповніть таблицю цін та/або запасну вартість.

6. Для актуальних цін у материковому Китаї введіть код клієнта та checkword, провінцію й місто відправлення, а якщо валюта вашого магазину не CNY, — курс конвертації валюти. Натисніть Add Chinese provinces, якщо сторінка цього вимагає. Спочатку перевірте роботу в Sandbox з тестовими даними.

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

OpenCart 4

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

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

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

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

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

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

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Shipping > VibeFox SF Express > Edit. Розділи перелічені ліворуч. Вони застосовуються до всіх геозон. Одна кнопка Save внизу зберігає всю сторінку без перезавантаження. Кожне збереження також очищає кеш цін SF Express. Зберігати налаштування можуть лише адміністратори з правом змінювати це розширення.

Під час збереження розширення перевіряє значення. Порожня назва способу доставки, назва довша за 64 символи або з символами < > ; = # { }, значення, що не є числом, від'ємна сума чи вага, курс конвертації 0, Min weight (kg) більше за Max weight (kg), помилкова ціна в таблиці цін або порядок сортування, що не є цілим числом, відхиляються з повідомленням, і нічого не зберігається, доки ви не виправите це. Попередження над налаштуваннями повідомляють, коли актуальні ціни налаштовані лише частково (перелічено відсутні налаштування), коли бракує курсу конвертації, коли в магазині немає зон Китаю або коли в магазині немає вагової одиниці кг чи одиниці довжини см, а його одиниця за замовчуванням розширенню невідома.

Загальні

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

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

Tax class: клас податку на вартість доставки або No tax. З класом податку до вартості додається податок на доставку вашого магазину. Виберіть No tax, якщо ціна SF Express уже включає все, що ви хочете стягувати.

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

API FengQiao SF Express (актуальні ціни) (необов'язково, для адрес доставки в материковому Китаї)

Customer code (partnerID): код клієнта (顾客编码) вашого застосунку FengQiao. Його очищення також очищає збережений checkword, тож ви можете видалити облікові дані.

Checkword: checkword (校验码) того самого середовища. Він використовується лише для підпису запитів і ніколи не надсилається та не записується в журнал. Після збереження поле лишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Sandbox: використовує тестове середовище FengQiao (sfapi-sbox.sf-express.com) для перевірки з тестовими обліковими даними. Ціни в тестовому середовищі не справжні. У робочому магазині вимкніть цю опцію. За замовчуванням: вимкнено.

SF Express product: який продукт SF Express показувати з ціною.

Sender province: провінція, з якої відправляються посилки, наприклад Guangdong / 广东. Перший варіант використовує регіон вашого магазину (System > Settings > Store > Local), якщо магазин знаходиться в Китаї. Тоді з'являється Same as the store region з назвою провінції, інакше — — Select —.

Sender city: стандартна китайська назва міста, наприклад 深圳市. Обов'язково для актуальних цін: адреса магазину в OpenCart є вільним текстом, тому місто з неї ніколи не береться.

Currency conversion rate: ціни SF Express вказані в CNY (юань). Якщо валюта магазину за замовчуванням не CNY, введіть, скільки одиниць вашої валюти коштує один CNY (1 CNY = ? одиниць), наприклад 0.13. Без цього курсу актуальні ціни не використовуються. Якщо валюта магазину — CNY, поле повідомляє, що курс не потрібен, і ціни використовуються як є. Як десятковий роздільник приймаються і крапка, і кома.

Chinese provinces: показує, скільки з 32 провінцій, автономних регіонів і муніципалітетів SF Express є зонами Китаю в OpenCart і яких бракує. Адреси в відсутній провінції отримують табличну ціну. Натисніть Add Chinese provinces, щоб додати лише відсутні як зони Китаю (код ISO, назва на кшталт "Tibet / 西藏"). Наявні зони не змінюються. Без цього натискання нічого не змінюється. Зони, додані так, залишаються в магазині після видалення розширення.

Таблиця цін і запасна вартість (використовується для Гонконгу, Макао, Тайваню та інших країн, коли актуальні ціни не налаштовані або SF Express не повертає ціну; ціни у валюті магазину за замовчуванням, без податку)

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

Fallback cost: використовується, коли ні SF Express, ні таблиця не дають ціни. Залиште порожнім, щоб у цьому випадку приховати спосіб доставки.

Table / fallback price is: як стягуються табличні та запасні ціни.

Актуальні ціни SF Express завжди розраховуються для всього замовлення.

Умови

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

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

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

Max weight (kg): максимальна вага кошика в кг. За замовчуванням: 50. 0 або порожнє значення означає без обмеження.

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

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

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

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

Додатково

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

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

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

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

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

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

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

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

Для адреси доставки в материковому Китаї з встановленими кодом клієнта та checkword розширення надсилає до SF Express вашу провінцію та місто відправлення, провінцію та місто покупця, вагу кошика (щонайменше 0,1 кг) і об'єм кошика (з товарів з усіма трьома розмірами). Запит підписується вашим checkword. SF Express повертає ціни в CNY; розширення перераховує обрану ціну у валюту магазину за замовчуванням і округлює її до потрібної кількості знаків. Потім ціна показується покупцеві у його валюті з податком обраного Tax class.

SF Express розпізнає адреси за стандартними китайськими назвами. Провінція покупця береться із зони Region / State адреси й зіставляється за назвою. Зона "Hong Kong" не є провінцією материкового Китаю і отримує табличну ціну. Місто потрібно писати китайською, наприклад 广州市. Для Пекіна, Шанхаю, Тяньцзіня та Чунціна місто заповнюється автоматично. Місто латиницею, наприклад "Guangzhou", отримує табличну ціну.

Кожна ціна кешується на одну годину, тож той самий кошик не викликає новий запит. Невдалий запит кешується на 10 хвилин, щоб оформлення не чекало SF Express під час кожного оновлення. Тайм-аут HTTP становить 10 секунд.

Якщо актуальної ціни немає, ціна береться з таблиці цін, а потім із Fallback cost. Якщо жодне не застосовується, спосіб доставки приховується. Покупець ніколи не бачить помилки. Помилка записується в журнал.

Розширення лише розраховує ціни. Воно не створює накладні чи ярлики, не оформляє замовлення в SF Express, не викликає кур'єра та не скасовує й не відстежує відправлення. Створюйте і відстежуйте відправлення у своєму обліковому записі SF Express, як зазвичай. Покупці не можуть обрати пункт видачі або поштомат SF. SF Express використовується як кур'єрська доставка до дверей. Актуальні ціни доступні лише для адрес доставки в материковому Китаї. Розширення створено на основі документації FengQiao та імітованих відповідей, тож перед переходом до роботи зі справжніми замовленнями звірте ціни зі своїм обліковим записом SF Express (спочатку в Sandbox).

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

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

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

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

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

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

SF Express не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і Enable SF Express увімкнено. Перевірте Geo zone або увімкніть Ignore shipping zones і перевірте Countries. Перевірте обмеження ваги та Minimum subtotal. Перевірте, що таблиця або Fallback cost мають ціну для країни. Перевірте, що в товарів Requires Shipping встановлено Yes.

Ціна береться з таблиці, а не з SF Express: актуальні ціни потребують коду клієнта та checkword, провінції та міста відправлення, адреси доставки в материковому Китаї з провінцією та китайською назвою міста, а для магазинів не в CNY — курсу конвертації валюти. Прочитайте попередження у верхній частині сторінки розширення, потім увімкніть Debug log, перезавантажте оформлення і подивіться поле Log, щоб побачити причину. Невдалий запит повторюється через 10 хвилин.

У журналі помилка підпису: checkword неправильний або належить до іншого середовища. Перевірте налаштування Sandbox. Якщо SF Express повідомляє, що API не дозволено, додайте API запиту цін до свого застосунку FengQiao.

Адреси в Тибеті отримують табличну ціну: натисніть Add Chinese provinces у розділі API на сторінці розширення.

Гонконг: працює з таблицею цін і запасною вартістю. Запит цін FengQiao стосується адрес материкового Китаю.

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

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

Для розробників: події OpenCart vfd_sf_express/quote_request і vfd_sf_express/api_url дозволяють іншому розширенню змінити запит ціни (наприклад, на інший код товару) та URL шлюзу.

Видалення

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

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

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