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

Вимоги

WordPress: 5.8 або новіша версія.

WooCommerce: 7.0 або новіша, встановлений і активний. Плагін не активується без нього.

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

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

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

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

1. У WordPress перейдіть до Plugins > Add New > Upload Plugin, виберіть ZIP-файл плагіна та натисніть Install Now. Також можна завантажити папку vfd_chilexpress до /wp-content/plugins/ через FTP.

2. Натисніть Activate.

3. Відкрийте налаштування: WooCommerce > Settings > Shipping > VibeFox Chilexpress або натисніть Settings під назвою плагіна на сторінці Plugins.

4. Введіть ліцензійний ключ VibeFox у блоці ліцензії у верхній частині сторінки та натисніть Activate.

5. Заповніть таблицю цін. Для актуальних тарифів введіть обидва ключі підписки, код county відправлення та, якщо валюта магазину не CLP, обмінний курс CLP, потім оберіть джерело тарифів (див. розділ «Конфігурація»).

6. Додайте VibeFox Chilexpress до зони доставки для Чилі в WooCommerce > Settings > Shipping > Shipping zones або увімкніть Ignore shipping zones і оберіть країни.

Конфігурація

Усі налаштування розташовані на одній сторінці: WooCommerce > Settings > Shipping > VibeFox Chilexpress. Вони діють для всіх зон доставки. Коли ви додаєте метод до зони, вікно зони містить лише одне поле:

Title (zone): назва цього варіанта доставки на оформленні замовлення для цієї зони. Залиште порожнім, щоб використати загальне Name.

На сторінці налаштувань угорі виводяться проблеми: вибрано тарифи API, але не заповнено ключ, код county відправлення або обмінний курс CLP, або в таблиці цін немає рядка для Чилі чи для * Default. Кожного разу, коли ви зберігаєте налаштування, очищаються кешовані тарифи та списки комун. Числа можна вводити з крапкою або комою; неправильне число не зберігається, і показується помилка.

Загальні

Enable/Disable: вмикає або вимикає доставку Chilexpress одразу у всіх зонах.

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

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

Тарифи

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

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

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

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

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

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

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

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

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

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

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

Доступність

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

Max weight (kg): метод приховується, якщо вага кошика перевищує це значення. Default: 25. 0 означає без обмежень.

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

Excluded shipping classes: приховує метод, якщо будь-який товар у кошику належить до одного з цих класів доставки WooCommerce.

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

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

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

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

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

Додатково

Debug log: записує запити до API та розрахунки тарифів у WooCommerce > Status > Logs, джерело vfd-chilexpress. Помилки API записуються завжди, навіть якщо цю опцію вимкнено. Ключі API ніколи не записуються.

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

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

Коли покупець вводить адресу доставки, WooCommerce запитує у плагіна тариф. Плагін спочатку перевіряє умови: вагу кошика, мінімальну суму та виключені класи доставки. Якщо діє безкоштовна доставка, покупець отримує безкоштовний тариф, і запит до Chilexpress не надсилається.

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

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

Метод працює на класичному оформленні замовлення та в блоках «Кошик» і «Оформлення замовлення». Він сумісний з High-Performance Order Storage (HPOS) WooCommerce.

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

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

Плагін працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії розташований угорі сторінки WooCommerce > Settings > Shipping > VibeFox Chilexpress. Вставте ключ у поле License key і натисніть Activate. У блоці показано статус, наприклад дату, до якої ліцензія активна, і ваш домен. Скористайтеся Check now, щоб перевірити статус ще раз, Change key, щоб ввести інший ключ, і Remove key, щоб видалити ключ із цього сайту. Посилання Manage licenses and domains in your account відкриває ваш обліковий запис vibefox.net.

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

Без активного ключа Chilexpress не показується покупцям на оформленні замовлення. Адміністратори магазину, які увійшли в систему, як і раніше бачать його з позначкою (unlicensed — visible to admins only), щоб ви могли налаштувати й протестувати плагін до покупки ключа. Нагадування з'являється на сторінці Plugins і на сторінках WooCommerce. Існуючі замовлення не зачіпаються.

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

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

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

Актуальний тариф не показано, замість нього використовується фіксована ціна: спершу перегляньте попередження вгорі сторінки налаштувань. Якщо їх немає, увімкніть Debug log, оновіть оформлення замовлення і відкрийте WooCommerce > Status > Logs, джерело vfd-chilexpress. Типові причини: комуна, яку Chilexpress не розпізнає (перевірте поле «Місто» і регіон), ключ від іншого продукту або іншого середовища, або адреса призначення без покриття Chilexpress.

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

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

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

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

Блок ліцензії показує помилку: дотримуйтеся повідомлення в блоці. Наприклад, якщо ключ уже використовується на іншому домені, звільніть слот у своєму обліковому записі vibefox.net і натисніть Check now. Якщо адреса сайту змінилася, натисніть Check now, щоб активувати ключ для нового домену. Якщо сервер ліцензій недоступний, плагін продовжує працювати за останнім відомим статусом.

Видалення

Деактивація плагіна зберігає всі налаштування; вона лише очищає кешовані тарифи та списки комун. Щоб видалити плагін, деактивуйте його та видаліть на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна та кеші завжди видаляються. Налаштування та методи зон видаляються, лише якщо була увімкнена опція Remove data on uninstall. Інакше вони зберігаються для повторного встановлення. Рядки доставки існуючих замовлень завжди зберігаються.

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