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

Вимоги

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

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

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

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

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

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

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

Після встановлення спосіб вимкнений, доки ви не увімкнете Enable/Disable і не збережете. Якщо ви встановите розширення повторно після видалення, будуть використані збережені вами налаштування Chilexpress.

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

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Shipping > VibeFox Chilexpress > Edit. Розділи перелічено зліва. Одна кнопка Save внизу зберігає всю сторінку без перезавантаження. Після збереження ви побачите Settings saved. Cached Chilexpress rates and comuna lists were cleared. Лише адміністратори з правом змінювати це розширення можуть зберігати налаштування, очищати журнал або додавати регіони.

Сторінка зверху показує проблеми: обрано тарифи API, але ключ Rating API порожній; ключ Coverage API порожній; код county джерела відправлення порожній або некоректний; валюта магазину не CLP, і курс CLP не задано; у Country prices немає рядка для Чилі або для типового значення; у Чилі немає зон у магазині; одиниця ваги або довжини магазину невідома розширенню (тоді ваги читаються як кг, а розміри як см; використовуйте kg, g, lb або oz та cm, mm, m або in у System > Localisation). Числа можна вводити з крапкою або комою. Нічого не зберігається, і сторінка показує помилки, якщо Name порожнє, містить один із символів < > ; = # { } або довше 64 символів, число некоректне або від'ємне, CLP exchange rate дорівнює 0, Min weight (kg) більше за Max weight (kg), Origin county code не є кодом county або Sort order не є цілим числом.

Загальні

Один спосіб доставки «Chilexpress» для кожної геозони або для геозони, обраної в розділі Доступність.

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

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

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

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

Тарифи

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

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

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

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

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

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

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

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

Coverage API key: ключ передплати продукту Coverage (Coberturas / Georreferencia). Він потрібен, щоб знайти код county Chilexpress для comuna клієнта (поле 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 для comuna, з якої ви відправляєте, 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: comuna Чилі шукаються за регіонами, тому актуальним тарифам потрібен регіон (зона) адреси. Поле показує, скільки зон має Чилі і яких регіонів бракує, та містить кнопку Add Chilean regions. Вона додає лише відсутні регіони як зони Чилі; наявні зони не змінюються, а регіон не додається двічі. Коли всі 16 регіонів на місці, поле показує All 16 Chilean regions are zones of Chile. Якщо Чилі не є країною магазину, поле про це повідомляє: додайте її в System > Localisation > Countries.

Доступність

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

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

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

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

Ignore shipping zones: пропонувати спосіб для країн нижче без перевірки геозони.

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

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

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

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

Додатково

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

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

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

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

Export: натисніть Download JSON, щоб зберегти налаштування у файл JSON. Ключі API не експортуються.

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

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

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

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

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

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

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

Замовлення

Коли замовлення оформлено через Chilexpress, розширення зберігає, як розраховано його ціну. У Sales > Orders на сторінці замовлення відображається панель Chilexpress із Chilexpress service (для актуального тарифу — сервіс, запропонований Chilexpress, наприклад Express; інакше тире) та Price: Live rate (Chilexpress Rating API), Fixed price або Free shipping. Панель показується й тоді, коли спосіб вимкнено. В OpenCart 4 панель Chilexpress показується над History, і коли замовлення повторно підтверджується під час оформлення або переводиться на інший спосіб доставки, панель слідує за зміною.

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

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

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

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

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

Chilexpress не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і Enable/Disable увімкнено. Перевірте Geo zone (або Ignore shipping zones і Countries), обмеження ваги та Minimum subtotal. За фіксованих цін перевірте, що для країни або * Default (other countries) є рядок. Перевірте, що для товарів Requires Shipping має значення Yes.

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

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

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

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

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

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

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

Для розробників: базову адресу API Chilexpress можна замінити налаштуванням vfd_chx_api_base_url (для тестів); для нього немає поля на сторінці налаштувань.

Видалення

Перейдіть до Extensions > Extensions, оберіть тип Shipping і натисніть Uninstall (червона кнопка −) поруч із VibeFox Chilexpress. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди скидає Enable/Disable, Sort order, Tax class та Geo zone. Кешовані тарифи та списки comuna завжди видаляються. Якщо Remove data on uninstall увімкнено, видаляються також решта налаштувань і журнал налагодження. Якщо вимкнено, вони зберігаються і використовуються знову під час повторного встановлення розширення. Сервіси Chilexpress, збережені із замовленнями, ніколи не видаляються, а наявні замовлення зберігають свій спосіб доставки та вартість. Регіони Чилі, додані через Add Chilean regions, залишаються в магазині.

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

Chilexpress є торговою маркою її власника. Це розширення не є афілійованим із Chilexpress і не схвалене нею.