VibeFox Chilexpress for PrestaShop — Допомога

Вимоги

PrestaShop: 8.0–9.x.

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

Ключі API Chilexpress (лише для актуальних тарифів): створіть обліковий запис на порталі розробників Chilexpress (developers.wschilexpress.com) і оформіть підписку на два продукти: Rating (Cotizador) та Coverage (Coberturas / Georreferencia). Кожен продукт має власний ключ підписки. Тестові ключі працюють лише з тестовим середовищем; ключі для промислового середовища видаються корпоративним клієнтам Chilexpress за клієнтським договором. Вам також потрібен код county Chilexpress комуни, з якої ви відправляєте, наприклад STGO. Якщо ви використовуєте лише фіксовані ціни, ключі API не потрібні.

Регіони Чилі (лише для актуальних тарифів): актуальні тарифи потребують регіону адреси доставки. У PrestaShop за замовчуванням немає регіонів Чилі; модуль може додати їх за вас (див. Chilean regions нижче). Країна Chile має існувати в магазині.

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

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

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

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

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

4. Заповніть таблицю Country prices. Для актуальних тарифів введіть обидва ключі підписки, код county відправлення та, якщо валюта магазину не CLP, обмінний курс CLP; натисніть Add Chilean regions, якщо сторінка цього вимагає; далі оберіть джерело тарифів (див. Налаштування) і натисніть Save.

Під час встановлення модуль створює перевізника Chilexpress з текстом строку доставки Chilexpress courier. Перевізник прив'язаний до зони Chile та до всіх груп покупців. Зони, групи покупців, строк доставки, логотип і обмеження за розміром можна змінити в Shipping > Carriers. Не задавайте там ціни: ціна завжди береться з модуля. Щоб пропонувати Chilexpress в інших зонах, додайте їх до перевізника на цій сторінці або увімкніть Ignore shipping zones.

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

Усі параметри розташовані на сторінці модуля: Modules > Module Manager > VibeFox Chilexpress > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Кожне збереження також очищає кешовані тарифи Chilexpress і списки комун. Для змін потрібен дозвіл «configure» для модуля; без нього сторінка показує You do not have permission to configure this module.

Сторінка показує проблеми у верхній частині: обрано тарифи API, але бракує ключа, коду county відправлення або обмінного курсу CLP; у таблиці цін немає рядка для Чилі або значення за замовчуванням; у магазині немає регіонів Чилі або в адресній формі для Чилі немає поля регіону; одиниця ваги або розмірів магазину модулю невідома (тоді вона вважається кг або см; задайте її в International > Localization, Local units); перевізника видалено. Числа можна вводити з крапкою або комою, як прийнято в мові вашого бек-офісу. Неправильне або від'ємне число, CLP exchange rate 0, Min weight (kg) більше за Max weight (kg) або Name довший за 64 символи — це помилки, і нічого не зберігається, поки ви їх не виправите.

Загальні

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

Name: назва способу доставки, яку покупець бачить під час оформлення замовлення. Це назва перевізника. За замовчуванням: Chilexpress. Обов'язково, до 64 символів.

Tax: податкове правило перевізника або No tax (значення за замовчуванням для нового перевізника). Тарифи API Chilexpress використовуються саме так, як розраховані. Оберіть No tax, якщо розрахунок уже містить IVA, а магазин додав би податок зверху.

Тарифи

Rate source: звідки береться ціна.

Актуальні тарифи доступні лише для напрямків у Чилі. Інші країни завжди використовують фіксовані ціни.

Country prices: таблиця країн призначення зі стовпцем Price і необов'язковими цінами за розміром посилки у валюті магазину за замовчуванням, без податків. Розмір визначається вагою кошика: XS до 1 кг, S до 2 кг, M до 3 кг, L до 5 кг, XL понад 5 кг. Якщо розмір залишено 0, використовується Price. Натисніть Add country, щоб додати рядок, і значок кошика, щоб видалити його. Рядок * Default застосовується до країн без власного рядка. Країна без рядка (і без * Default) не отримує фіксованої ціни, тому перевізник там приховується. Рядок, у якого ціна і ціни за розміром усі 0, означає безкоштовну доставку. Порожня таблиця показується з одним рядком для Чилі з ціною 0; останній рядок не можна видалити, лише скинути на 0, тому введіть реальні ціни перед збереженням сторінки. Повторювана країна або недійсна ціна виправляється (дублікат ігнорується, ціна встановлюється на 0), а попередження перелічує виправлення.

Calculation type: Per order стягує фіксовану ціну один раз. Per item (fixed price x number of items) множить її на кількість товарів у кошику. Тариф Chilexpress API завжди розраховується на всю посилку.

API Chilexpress (актуальні тарифи)

Розділ починається з посилань на портал розробників і сторінки підписки Rating та Coverage.

Test environment: використовує тестове середовище Chilexpress (qaservices.wschilexpress.com). Використовуйте його з тестовими ключами і вимикайте на робочому магазині.

Rating API key: ключ підписки продукту Rating (Cotizador).

Coverage API key: ключ підписки продукту Coverage (Coberturas / Georreferencia). Він потрібен, щоб знайти код county Chilexpress комуни покупця (поле City адреси разом з регіоном).

Після збереження поле ключа залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити. Ключ зберігається так, як ви його ввели; видаляються лише пробіли по краях.

Remove the saved Rating API key та Remove the saved Coverage API key: показуються лише тоді, коли ключ збережено. Увімкніть опцію і натисніть Save, щоб видалити ключ.

Origin county code: код county Chilexpress (комуни), з якої ви відправляєте, 2–5 літер, наприклад STGO (Santiago Centro), PROV (Providencia) або VALP (Valparaíso). Після встановлення поле порожнє. Значення, яке не є кодом county, відхиляється з помилкою.

Service: послуга Chilexpress, яка використовується для тарифу. Якщо вона не пропонується для напрямку, використовується найдешевша доступна послуга.

CLP exchange rate: Chilexpress розраховує тарифи в чилійських песо. Потрібен лише тоді, коли валюта магазину за замовчуванням не CLP: ціна 1 CLP у цій валюті, наприклад 0.001. Без нього тарифи API не використовуються. Якщо валюта магазину — CLP, залиште поле порожнім. Значення має бути більше 0.

Chilean regions: комуни Чилі шукаються за регіонами, тому актуальним тарифам потрібен регіон адреси. Якщо в магазині немає регіонів Чилі, поле показує кнопку Add Chilean regions. Вона додає 16 регіонів як штати Chile (ISO-коди RM, VS…), вмикає «Contains states» для Chile і додає поле регіону до адресної форми для Чилі. Регіони, які вже є (за кодом або назвою), не додаються повторно. Коли все налаштовано, поле показує Chilean addresses have a region з кількістю регіонів.

Доступність

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

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

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

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

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

Безкоштовна доставка

Free shipping: вмикає поріг безкоштовної доставки.

Free shipping from: проміжна сума кошика (товари, що потребують доставки, після знижок, без податків), від якої доставка безкоштовна. Використовується лише тоді, коли увімкнено Free shipping. У цьому разі запит до API не надсилається.

Додатково

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

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

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

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

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

Для адреси в Чилі та джерела тарифів API модуль бере регіон адреси та комуну з поля City і шукає код county Chilexpress у списку комун цього регіону (Coverage API). Діакритика, пробіли та варіанти написання ігноруються, тож Ñuñoa і Nunoa збігаються, а Santiago збігається з Santiago Centro. Код county, введений безпосередньо в поле City, також приймається. Далі модуль надсилає до Rating API коди county відправлення та призначення, вагу кошика (не менше 0,1 кг), розміри посилки (довжина і ширина найбільшого товару, висоти складених товарів) і проміжну суму кошика в CLP як оголошену вартість. Chilexpress повертає свої послуги; модуль використовує обрану або найдешевшу послугу і перераховує суму в песо у валюту магазину за замовчуванням. Ціна округлюється до десяткових знаків цієї валюти і потім показується у валюті кошика покупця.

Тарифи кешуються на 1 годину, списки комун на 7 днів. Невдалий запит запам'ятовується на 5 хвилин, щоб повільний або недоступний API не сповільнював кожне оновлення оформлення замовлення. Тайм-аут API становить 10 секунд. Якщо Chilexpress повертає помилку, не повертає послугу з ціною або комуна чи регіон невідомі, покупець не бачить жодної помилки. У режимі лише API перевізник приховується, інакше використовується фіксована ціна. Причина записується в журнал налагодження.

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

Модуль лише розраховує тарифи. Він не створює відправлень і транспортних замовлень (OT), не друкує етикетки, не замовляє забір посилок і не відстежує посилки; бронюйте відправлення у своєму обліковому записі Chilexpress. Покупці не можуть обрати офіс Chilexpress, і селектора комун немає: покупець вводить комуну в стандартне поле City. Міжнародні відправлення використовують фіксовані ціни.

Замовлення

Коли замовлення оформлюється з перевізником Chilexpress, модуль зберігає, як була розрахована його ціна. На сторінці замовлення в бек-офісі показується блок Chilexpress із Chilexpress service (для актуального тарифу — послуга, яку розрахував Chilexpress, наприклад Express) та Price source: Live rate (Chilexpress Rating API), Fixed price або Free shipping.

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

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

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

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

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

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

Доставка в Чилі безкоштовна, хоча не мала б бути: рядок для Чилі (або * Default) у Country prices має 0 у Price і в стовпцях розмірів. Введіть ціни та натисніть Save.

Актуальний тариф не показується, натомість використовується фіксована ціна: спочатку перегляньте попередження у верхній частині сторінки модуля. Якщо їх немає, увімкніть Debug log, перезавантажте оформлення замовлення і подивіться поле Log на сторінці модуля. Типові причини: в адреси немає регіону або бракує поля регіону (скористайтеся Add Chilean regions), комуна, яку Chilexpress не розпізнає (перевірте поле City і регіон), ключ для іншого продукту або середовища, або напрямок без покриття Chilexpress.

HTTP 401 або 403 у журналі: ключ підписки неправильний, неактивний або належить іншому продукту чи середовищу. Тестові ключі працюють лише з увімкненим Test environment.

Тарифи API не використовуються в магазині з іншою валютою: введіть CLP exchange rate.

Тарифи API з IVA чи без IVA? Вони використовуються саме так, як їх розраховує Chilexpress. Якщо ваш магазин додає податок до доставки, а розрахунок уже містить IVA, встановіть Tax на No tax.

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

На сторінці написано «The Chilexpress carrier was not found»: перевізника видалено в Shipping > Carriers. Скиньте модуль у Modules > Module Manager, щоб створити його знову.

На сторінці написано «The country Chile does not exist in this shop»: додайте або увімкніть Chile в International > Locations > Countries, потім скористайтеся Add Chilean regions.

Видалення

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

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