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

Вимоги

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

PHP: 8.0 або новіша.

Договір з Jadlog (для актуальних цін і пунктів видачі): актуальні ціни і список пунктів видачі надходять з API Embarcador Jadlog. Ваша франшиза Jadlog видає доступ після підписання договору. Вам потрібні токен API Embarcador, CNPJ (або CPF) відправника, зазначеного в договорі, розрахунковий рахунок (conta corrente) і, якщо він у вас є, номер договору. Якщо ви використовуєте лише фіксовані ціни, договір з Jadlog не потрібен.

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

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

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

OpenCart 3

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

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

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

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

5. Вставте токен API, введіть CNPJ, розрахунковий рахунок, номер договору та CEP відправлення, виберіть послугу Jadlog і, якщо валюта магазину за замовчуванням не BRL, введіть курс BRL. За потреби додайте фіксовані ціни або резервну вартість (див. розділ «Налаштування»).

6. Увімкніть Enable Jadlog home delivery, Enable Jadlog Pickup або обидві опції і натисніть Save.

OpenCart 4

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

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

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

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

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

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

Усі налаштування знаходяться на сторінці розширення: Extensions > Extensions > Shipping > VibeFox Jadlog > Edit. Вони застосовуються до обох опцій Jadlog. Розділи перелічено ліворуч. Одна кнопка Save зберігає всю сторінку без перезавантаження. Кожне збереження також очищає кешовані актуальні ціни Jadlog і списки пунктів видачі. Зберігати налаштування можуть лише адміністратори з правом змінювати це розширення.

Угорі сторінки розширення показує попередження про неповне налаштування: немає токена API (використовуються лише фіксовані ціни, а пункти видачі не можна перелічити), немає токена API і немає фіксованих цін (спосіб доставки ніколи не показується), немає CNPJ або розрахункового рахунку, немає CEP відправлення, немає курсу BRL для магазину, який не продає в BRL, і немає вагової категорії «kg» або категорії довжини «cm» у магазині (тоді ваги та розміри перераховуються за назвою одиниці їхньої категорії; перевірте System > Localisation > Weight Classes і Length Classes).

Під час збереження некоректна назва будь-якої з опцій (порожня, довша за 64 символи або з символами < > ; = # { }), Sort order, яке не є цілим числом, або клас податку чи геозона, яких не існує, зупиняють збереження з помилкою. Інші неправильні значення зберігаються із зауваженням над налаштуваннями: недійсне число або число менше за 0 не зберігається, мінімальна вага більша за максимальну залишає обидві збережені ваги, курс BRL, який не є додатним числом, очищається, CEP без 8 цифр або CNPJ без 14 цифр (або 11 для CPF) зберігається як введено, з попередженням, а в таблиці цін рядок із невідомою країною видаляється, а некоректна ціна лишається порожньою.

Загальні

У Jadlog дві опції доставки: Jadlog home delivery (цей розділ) і Jadlog Pickup (окремий розділ). Налаштування на цій сторінці застосовуються до обох.

Enable Jadlog home delivery: пропонує доставку Jadlog на адресу покупця з обраною нижче послугою. За замовчуванням: off.

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

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

Tax class: клас податку на вартість доставки або No tax (за замовчуванням). Ціни Jadlog є остаточними тарифами перевізника. Оберіть No tax, якщо OpenCart не повинен додавати до них податок. Це стосується обох опцій.

Актуальні ціни Jadlog

Актуальні ціни запитуються лише для адрес у Бразилії з повним 8-значним CEP.

API token: токен Embarcador від Jadlog. Його можна вставити зі словом «Bearer» або без нього. Залиште поле порожнім, щоб використовувати лише фіксовані ціни. Після збереження поле лишається порожнім і показує Saved - leave empty to keep it. Вводьте нове значення, лише щоб змінити його. Коли токен не збережено, сторінка показує No token saved.

Remove the saved API token: позначте і натисніть Save, щоб видалити збережений токен.

CNPJ: CNPJ (14 цифр) або CPF (11 цифр) відправника, зареєстрованого в договорі Jadlog, наприклад 00.000.000/0000-00.

Current account (conta corrente): номер вашого розрахункового рахунку Jadlog. Без нього і без CNPJ Jadlog не може розрахувати вартість, і використовуються лише фіксовані ціни.

Contract number: номер вашого договору з Jadlog, якщо його видала франшиза.

Origin CEP: поштовий індекс, з якого відправляються посилки, 8 цифр (00000-000). Обов'язковий для актуальних цін: в OpenCart немає поштового індексу магазину, тож без цього поля використовуються лише фіксовані ціни.

Jadlog service: послуга (modalidade) вашого договору для доставки додому: .Package (3, за замовчуванням), .Com (9), Expresso (0), Rodoviário (4), Econômico (5), Doc (6), Corporate (7), Internacional (10), Cargo (12) або Emergencial (14). Jadlog Pickup (40) — друга опція.

Insurance type: Normal (N) (за замовчуванням) або Own insurance policy (A - apolice), як погоджено у вашому договорі з Jadlog.

Volumetric weight: Jadlog стягує більше з фактичної та об'ємної ваги.

BRL exchange rate: Jadlog розраховує вартість у бразильських реалах. Якщо валюта магазину за замовчуванням — BRL, це поле не потрібне. Інакше введіть, скільки коштує 1 BRL у валюті магазину за замовчуванням, наприклад 0.16. Ціна Jadlog множиться на цей курс, а оголошена вартість замовлення, яка надсилається до Jadlog, перераховується назад у BRL. Без курсу актуальні ціни не використовуються, і застосовуються лише фіксовані ціни.

Delivery time: показує термін доставки, який повертає Jadlog під час оформлення, поруч із назвою доставки додому (наприклад, «Jadlog (3 business days)») і поруч з кожним пунктом видачі. Увімкнено за замовчуванням. Термін доставки завжди зберігається із замовленням.

Jadlog Pickup

Друга опція доставки з послугою Jadlog Pickup (40). Для неї потрібен токен API. Без пунктів опцію приховано.

Enable Jadlog Pickup: пропонує доставку до пункту видачі Jadlog, обраного під час оформлення замовлення. За замовчуванням: off.

Jadlog Pickup title: назва цієї опції під час оформлення замовлення. За замовчуванням: Jadlog Pickup. Обов'язкове поле, до 64 символів.

Points to show: скільки пунктів видачі пропонувати, від 1 до 10. За замовчуванням: 5.

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

Price per country: таблиця зі стовпцями Country, Price, XS, S, M, L і XL у валюті магазину за замовчуванням. Натисніть Add country, щоб додати рядок, і кнопку ×, щоб його видалити. Стовпець розміру обирається за вагою кошика: XS до 1 кг, S до 2 кг, M до 3 кг, L до 5 кг, XL понад 5 кг. Price використовується, коли стовпець розміру порожній. Ціна 0 означає безкоштовну доставку для цієї країни. Для всіх інших країн використовуйте * Default (other countries).

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

Fixed price applies: Per order (за замовчуванням) стягує ціну один раз. Per item (price x quantity) множить її на кількість товарів у кошику. Це стосується лише фіксованих цін і резервної вартості. Ціни Jadlog уже покривають весь кошик.

Умови

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

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

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

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

Доступність

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

Ignore shipping zones: коли ввімкнено, Geo zone не перевіряється, і Jadlog пропонується для країн нижче. Коли вимкнено (за замовчуванням), діє лише Geo zone.

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

Додатково

Debug log: записує кожен запит і відповідь Jadlog у storage/logs/vfd_jdlg_debug.log.php (в OpenCart 4 — system/storage/logs/vfd_jdlg_debug.log.php). Файл не можна прочитати через веб. Помилки API і замовлення Jadlog Pickup без пункту завжди записуються до журналу, навіть коли цю опцію вимкнено. Токен, CNPJ і рахунок ніколи не записуються, а CEP покупця скорочується. Вимкніть журнал, коли закінчите.

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

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

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

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

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

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

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

Для адреси доставки в Бразилії з повним 8-значним CEP розширення надсилає Jadlog CEP відправлення і призначення, вагу, ваш CNPJ, розрахунковий рахунок, договір, послугу, тип страхування і оголошену вартість замовлення. Ваги товарів перераховуються з їхнього вагового класу OpenCart у кг, а розміри — з їхнього класу довжини в см. Кошики без ваги розраховуються як 0.1 кг. Отримана ціна перераховується у валюту магазину за замовчуванням, округлюється до її знаків після коми і показується покупцеві у його валюті з податком обраного Tax class. Якщо актуальної ціни немає (немає токена, адреса поза Бразилією, неповний CEP, немає курсу BRL, помилка Jadlog), розширення використовує таблицю Price per country, потім Fallback cost. Якщо жоден з них не дає ціну, опцію для цього кошика приховують.

Кожна ціна кешується на 1 годину, тож той самий кошик не викликає новий запит. Невдалий запит кешується на 10 хвилин. Якщо Jadlog не відповідає, повертає помилку сервера або відхиляє токен, API не викликається повторно протягом 10 хвилин. Тайм-аут API — 10 секунд. Покупець ніколи не бачить помилку API. Причина записується до журналу.

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

Розширення лише розраховує ціни і перелічує пункти видачі. Воно не створює відправлень Jadlog, не друкує етикетки, не замовляє забір відправлень, не скасовує відправлення і не відстежує посилки. Воно не показує карту пунктів видачі і не запитує у Jadlog міжнародні розрахунки. Для інших країн використовуйте фіксовані ціни.

Пункти видачі

Опція Jadlog Pickup пропонується лише для адрес у Бразилії і лише коли ввімкнено Enable Jadlog Pickup і збережено токен API. Коли покупець ввів повний 8-значний CEP, розширення запитує у Jadlog актуальні пункти видачі, найближчі до нього, і показує під опцією до Points to show пунктів, кожен із ціною, наприклад «назва пункту — ціна (3 business days) — адреса». Якщо список ще не в кеші, він завантажується у фоновому режимі, коли покупець обирає Jadlog Pickup, щоб крок способу доставки не чекав на Jadlog.

Ціна до кожного пункту запитується у Jadlog. Якщо Jadlog не дає ціну для пункту, використовується фіксована ціна, а пункт без жодної ціни не показується. Списки пунктів кешуються на 12 годин. Ціна опції — це ціна обраного пункту. Доки пункт не обрано, це ціна найближчого пункту, для якого є ціна. Коли покупець обирає пункт, ціна поруч із Jadlog Pickup оновлюється.

Пункт обов'язковий. Коли покупець натискає Continue на кроці способу доставки без пункту, він бачить Please select a Jadlog Pickup point. Розширення перевіряє на сервері, що пункт є у списку Jadlog для поштового індексу доставки. Якщо ні, покупець бачить The selected Jadlog Pickup point is not in the Jadlog list for this CEP. Please choose the point again. Якщо CEP неповний, поруч немає пунктів або Jadlog недоступний, під опцією показується повідомлення.

Без токена API, коли Jadlog недоступний або коли поруч немає активних пунктів, опцію Jadlog Pickup приховують. Замовлення без пункту не можна було б відправити.

В OpenCart 4 список пунктів видачі з'являється у вікні Shipping method options під опцією Jadlog Pickup. Він завантажується у фоновому режимі: спочатку з кешу, а потім разом із цінами інших пунктів від Jadlog. Коли покупець обирає пункт, ціна біля Jadlog Pickup у вікні оновлюється. Кнопка Continue у вікні не переходить далі без дійсного пункту видачі, з тими самими повідомленнями.

Замовлення

Коли замовлення оформлено з опцією Jadlog, розширення зберігає послугу Jadlog і, якщо Jadlog її повернув, термін доставки в робочих днях. Для замовлення Jadlog Pickup також зберігаються назва, адреса і ID пункту видачі. В OpenCart 4 для оформлення зберігається одне замовлення, яке оновлюється щоразу, коли покупець підтверджує його знову, і разом із ним оновлюються дані Jadlog замовлення. Якщо покупець переключає це замовлення на інший спосіб доставки, його дані Jadlog видаляються.

Пункт додається до способу доставки замовлення після назви опції, наприклад Jadlog Pickup:, далі назва та адреса пункту. Цей текст з'являється на сторінках замовлення в адмін-панелі та в кабінеті покупця, у листах про замовлення і в рахунку.

Сторінка замовлення в адмін-панелі (Sales > Orders) показує панель Jadlog з Jadlog service, Delivery time і, для Jadlog Pickup, Pickup point, Pickup point address та Pickup point ID. В OpenCart 4 панель показується над розділом History.

Оформіть відправлення в системі Jadlog самостійно. Замовлення показує послугу і ID пункту видачі, які для цього потрібні.

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

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

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

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

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

Jadlog не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і увімкнено Enable Jadlog home delivery (або Enable Jadlog Pickup). Перевірте Geo zone або увімкніть Ignore shipping zones і перевірте Countries. Перевірте попередження вгорі сторінки розширення, обмеження ваги, Minimum order amount і що у товарів Requires Shipping встановлено в Yes. Якщо покупець ще не ввів повний 8-значний CEP, можна використовувати лише фіксовані ціни, тож додайте рядок Price per country або Fallback cost.

Показуються лише фіксовані ціни: увімкніть Debug log, перезавантажте оформлення замовлення і подивіться поле Log на сторінці розширення. Там вказано причину: немає CNPJ або розрахункового рахунку, немає CEP відправлення, неповний CEP призначення, немає курсу BRL або текст помилки Jadlog.

HTTP 401 або 403 у журналі: Jadlog відхилив токен API. Уточніть його у своїй франшизі Jadlog. Після цієї помилки API призупиняється на 10 хвилин. Збереження налаштувань знімає паузу, тож ви можете спробувати одразу.

Пункти видачі не з'являються: для опції Jadlog Pickup потрібні Enable Jadlog Pickup, токен API і повний 8-значний CEP у Бразилії. Якщо у Jadlog немає активних пунктів поблизу CEP, опцію приховують. Причину дивіться в журналі.

Ціни показуються в реалах, а не у моїй валюті: введіть BRL exchange rate (скільки коштує 1 BRL у валюті магазину за замовчуванням).

Ціни здаються занадто низькими або занадто високими: заповніть ваги та розміри товарів. Кошики без ваги розраховуються як 0.1 кг, а для об'ємної ваги потрібні розміри.

До цін Jadlog додається податок: встановіть Tax class на No tax.

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

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

Видалення

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

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

Jadlog є торговельною маркою її власника. Це розширення не пов'язане з Jadlog і не схвалене ним.