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

Вимоги

PrestaShop: від 8.0 до 9.x.

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

Обліковий запис 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 для sandbox і для production відрізняються. Якщо ви використовуєте лише таблицю цін, обліковий запис SF Express не потрібен.

Китайські провінції (лише для актуальних цін): актуальна ціна потребує провінцію адреси доставки. У PrestaShop за замовчуванням немає китайських провінцій. Модуль може додати їх за вас (див. нижче Chinese provinces).

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

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

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

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

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

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

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

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

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

Усі налаштування містяться на сторінці модуля: Modules > Module Manager > VibeFox SF Express > Configure. Вони діють для всіх зон перевізника. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Кожне збереження також очищує кеш цін SF Express.

Під час збереження модуль перевіряє числа. Значення, яке не є числом, від'ємна сума або вага, курс конвертації 0, Min weight більше за Max weight або хибна ціна в таблиці цін відхиляються з повідомленням, і нічого не зберігається, доки ви не виправите помилку. Попередження над налаштуваннями показують, коли актуальні ціни налаштовано частково (перелічуються відсутні параметри), коли не вказано курс конвертації, коли в китайських адресах немає поля провінції або коли модулю невідома одиниця ваги чи розмірів вашого магазину. Одиниці задаються в International > Localization (Local units).

Загальні

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

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

Tax: податкове правило перевізника або No tax. З податковим правилом податок на доставку вашого магазину додається до вартості. Оберіть No tax, якщо ціна 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) з тестовими обліковими даними. Ціни в sandbox не справжні. У робочому магазині вимкніть. За замовчуванням: вимкнено.

SF Express product: ціна якого продукту SF Express показується.

Cheapest product offered by SF Express: за замовчуванням. Використовується найнижча ціна, яку повертає SF Express.

SF Express Priority (顺丰特快, code 1): лише ціна цього продукту.

SF Standard Express (顺丰标快, code 2): лише ціна цього продукту.

Sender province: провінція, звідки відправляються посилки. Залиште порожнім, щоб використовувати провінцію адреси магазину в Shop Parameters > Contact > Stores, якщо магазин знаходиться в Китаї.

Sender city: стандартна китайська назва міста, наприклад 深圳市. Залиште порожнім, щоб використовувати місто магазину, якщо магазин знаходиться в Китаї.

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

Chinese provinces: показує, чи можуть китайські адреси мати провінцію. Якщо ні, натисніть Add Chinese provinces. Кнопка додає 32 провінції, автономні райони та муніципалітети як регіони Китаю (коди ISO, як-от GD і BJ, назви на кшталт «Guangdong / 广东»), вмикає «Contains states» для Китаю та додає поле регіону у форму китайської адреси. Провінції, які вже існують, повторно не додаються. Без цього натискання нічого не змінюється.

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

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

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

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

Per order (tier by the total cart weight): ціна категорії, що відповідає загальній вазі кошика, стягується один раз.

Per item (every item is priced by its own weight): кожен товар оцінюється за своєю ваговою категорією та множиться на кількість. Запасна вартість множиться на кількість товарів.

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

Умови

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

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

Min weight: мінімальна вага кошика в кг. Ваги товарів переводяться з одиниці ваги вашого магазину. 0 означає відсутність обмеження.

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

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

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

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

Додатково

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

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

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

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

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

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

SF Express розпізнає адреси за стандартними китайськими назвами. Провінція покупця береться з поля регіону адреси. Місто має бути написане китайською, наприклад 广州市. Для Beijing, Shanghai, Tianjin і Chongqing місто заповнюється автоматично. Місто, написане латиницею, наприклад «Guangzhou», отримує ціну з таблиці.

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

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

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

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

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

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox SF Express — це перший блок на сторінці Modules > Module Manager > VibeFox SF Express > Configure, над налаштуваннями. Введіть ключ у поле License key і натисніть Activate. Після цього блок показує ключ у прихованому вигляді, статус (наприклад, дату, до якої діє ліцензія, і ваш домен) та кнопки Check now, щоб перевірити статус ще раз, Change key, щоб ввести інший ключ, і Remove key, щоб видалити ключ із цього магазину. Нижче є рядок Product: presta-shipping-sf-express і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише співробітники з правом Configure для модуля. Тексти блоку відповідають мові back office (включено англійську та російську).

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

Один ключ працює на одному домені: домені основного магазину, також у багатомагазинній конфігурації. Видалення ключа з магазину не звільняє слот домену. Звільніть слот у своєму обліковому записі vibefox.net.

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

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

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

SF Express не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і ввімкнено Enable SF Express. У Shipping > Carriers перевірте, що перевізник охоплює зону країни покупця та групу покупця (або ввімкніть Ignore shipping zones і перевірте Countries). Перевірте обмеження ваги та Minimum subtotal. Переконайтеся, що в таблиці або в Fallback cost є ціна для країни. Товари також можуть бути обмежені певними перевізниками на сторінці товару.

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

У формі адреси для Китаю немає провінції: натисніть Add Chinese provinces у розділі API на сторінці модуля.

Помилка A1006 у журналі: недійсний підпис. Checkword неправильний або належить до іншого середовища. Перевірте налаштування Sandbox.

Помилка A1004 у журналі: API запиту цін не додано до вашого застосунку FengQiao.

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

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

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

Для розробників: хук actionVfdSfExpressQuoteRequest змінює запит ціни, наприклад, на інший код продукту. actionVfdSfExpressApiUrl змінює URL шлюзу.

Видалення

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

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