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

Вимоги

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

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

Ключ API Coordinadora (лише для актуальних тарифів): актуальні котирування надходять з Cotizador Coordinadora через сервіс Coordinadora для WooCommerce, той самий, який використовує офіційний плагін Coordinadora. Coordinadora видає ключ API клієнтам із чинною комерційною угодою. Запитайте свого менеджера облікового запису Coordinadora або перегляньте wc.coordinadora.com. Також потрібен 8-значний код DANE міста, з якого ви відправляєте. Без ключа спосіб працює лише з фіксованими цінами.

Товари: для актуального котирування кожен товар у кошику має мати вагу і три розміри (довжина, ширина, висота).

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

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

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

OpenCart 3

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

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

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

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

5. Введіть ключ API, код DANE міста відправлення і, якщо валюта магазину за замовчуванням не COP, курс COP. Додайте принаймні одну фіксовану ціну для Колумбії як запасний варіант (див. Налаштування). Увімкніть Enable Coordinadora і натисніть Save.

6. Переконайтеся, що у ваших товарів є вага та розміри.

OpenCart 4

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

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

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

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

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

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

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Shipping > VibeFox Coordinadora > Edit. Налаштування діють для всіх геозон; спосіб можна обмежити геозоною та країнами в розділі Conditions. Розділи перелічено зліва. Одна кнопка Save внизу зберігає всю сторінку без перезавантаження. Після збереження ви побачите Settings saved. Cached Coordinadora rates were cleared. Числа можна вводити з крапкою або комою (9,99 = 9.99). Лише адміністратори з правом змінювати це розширення можуть зберігати налаштування.

Нічого не зберігається, і сторінка показує помилки, якщо Name порожнє або довше 64 символів, число чи ціна в таблиці некоректні або від'ємні, COP per 1 unit of store currency дорівнює 0, Min weight (kg) більше за Max weight (kg), або Sort order не є цілим числом.

Над налаштуваннями сторінка показує попередження, якщо актуальні тарифи не можуть працювати або спосіб був би приховано: Origin city (DANE code) порожнє або некоректне; COP per 1 unit of store currency не заповнено, якщо валюта за замовчуванням не COP; для Колумбії немає фіксованої ціни (або для *); немає ані ключа API, ані фіксованої ціни для Колумбії, тож спосіб ніколи не показується для колумбійських адрес. Попередження також з'являється, якщо в магазині немає класу ваги в кг або класу довжини в см, а його одиниця за замовчуванням невідома розширенню; тоді ваги товарів читаються як кг, а розміри як см (використовуйте kg, g, lb або oz та cm, mm, m або in у System > Localisation). Попередження оновлюються після кожного збереження.

Загальні

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

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

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

Актуальні тарифи Coordinadora

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

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

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

Origin city (DANE code): 8-значний код DANE міста, з якого ви відправляєте, наприклад 11001000 Bogotá, 05001000 Medellín, 76001000 Cali або 08001000 Barranquilla. Приймається також 5-значний код муніципалітету, він доповнюється до 8 знаків.

COP per 1 unit of store currency: Coordinadora встановлює тарифи в колумбійських песо. Якщо валюта магазину за замовчуванням не COP, вкажіть, скільки COP становить 1 одиниця вашої валюти, наприклад 4300. Курс також використовується для передачі оголошеної вартості в COP. Якщо залишити поле порожнім, актуальні тарифи не використовуються. Курс має бути більшим за 0. Якщо валюта за замовчуванням COP, залиште поле порожнім.

Фіксовані ціни (використовуються, коли немає ключа API, для напрямків поза Колумбією і як запасний варіант, коли актуальне котирування недоступне)

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

Fixed price per: Order (за замовчуванням) стягує ціну один раз. Item (price × quantity) множить її на кількість товарів у кошику. Це стосується лише фіксованих цін; актуальне котирування Coordinadora завжди охоплює все замовлення.

Умови

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

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

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

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

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

Tax class: податкова категорія вартості доставки або No tax (за замовчуванням). З податковою категорією OpenCart додає податок на доставку поверх тарифу. Оберіть No tax, якщо ваші ціни або котирування Coordinadora вже містять податок.

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

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

Додатково

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

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

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

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

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

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

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

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

Для адреси в Колумбії з ключем API розширення знаходить код DANE міста призначення в такому порядку: код DANE у полі міста (колумбійські модулі оформлення замовлення для департаментів і міст записують його, наприклад MEDELLIN (ANT) (05001000)), 8-значний поштовий індекс або вбудований список обласних центрів і близько 40 найбільших міст. Якщо в адреси є регіон (департамент), місто зі списку перевіряється відповідно до нього. Наголоси та регістр ігноруються.

Далі розширення надсилає до Coordinadora код DANE призначення і кожен товар із містом відправлення, його вагу (кг), розміри (см), кількість і оголошену вартість (COP). Оголошена вартість — це сума рядка товару до податку, після знижки за купоном. Класи ваги та довжини товарів переводяться автоматично. Coordinadora повертає ціну в COP; розширення переводить її у валюту магазину за замовчуванням, округлює до знаків цієї валюти і показує у валюті покупця з податком обраної Tax class. Кожне котирування кешується на 1 годину. Невдалий запит пам'ятається 10 хвилин, щоб збій Coordinadora ніколи не сповільнював кожне оновлення оформлення замовлення. Тайм-аут API становить 10 секунд.

Коли актуальне котирування недоступне (помилка API, невідоме місто, товар без ваги або розмірів, неповні налаштування), використовується фіксована ціна. Якщо її немає, спосіб приховується для цього кошика. Подробиці помилок потрапляють у журнал налагодження, але ніколи не показуються покупцю.

Розширення лише розраховує тарифи. Воно не створює відправлень і guías (накладних), не друкує етикетки, не бронює забір посилок (recogidas), не відстежує посилки, не здійснює накладений платіж (recaudo) і не пропонує пункти видачі Droop; для цього користуйтеся порталом Coordinadora. Воно нічого не додає до замовлень: замовлення показує назву способу і вартість доставки, як будь-який інший спосіб доставки OpenCart. Міжнародні напрямки використовують фіксовані ціни.

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

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

Розширення працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Coordinadora — перший блок на сторінці Extensions > Extensions > Shipping > VibeFox Coordinadora > Edit, над налаштуваннями. Вставте ключ у поле License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої дійсна ліцензія, і ваш домен) та кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа і Remove key для видалення ключа з цього магазину. Нижче є рядок Product: opencart-shipping-coordinadora і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис на vibefox.net. Змінювати ключ можуть лише адміністратори з правом зміни для розширення. Тексти блоку відповідають мові адмінпанелі (включено англійську та російську).

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

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

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

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

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

Coordinadora не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і Enable Coordinadora увімкнено. Перегляньте попередження у верхній частині сторінки розширення, Geo zone, Countries, обмеження ваги та Minimum order subtotal. Без актуального котирування має існувати фіксована ціна для країни або для *. Перевірте, що для товарів Requires Shipping має значення Yes.

Актуальний тариф не показується, видно лише фіксовану ціну: увімкніть Debug log, перезавантажте оформлення замовлення і подивіться поле Log на сторінці розширення. Типові причини: місто призначення не розпізнано, у товару немає ваги або розмірів, бракує коду DANE відправлення чи курсу COP, або Coordinadora повернула помилку.

Місто призначення не розпізнано: встановіть колумбійський модуль оформлення замовлення для департаментів і міст, який записує код DANE в поле міста. Розробники можуть додати інші міста або змінити адресу API за допомогою подій OpenCart vfd_coordinadora/dane_cities, vfd_coordinadora/destination_dane та vfd_coordinadora/api_url; адресу API також можна замінити налаштуванням vfd_crd_api_url (для тестів), для якого немає поля на сторінці налаштувань.

Чи включає тариф податок? Тариф — це те, що котирує Coordinadora. З Tax class OpenCart додає податок на доставку поверх тарифу; оберіть No tax, якщо котирування вже його містить.

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

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

Видалення

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

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

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