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

Вимоги

PrestaShop: 8.0–9.x.

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

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

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

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

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

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

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

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

5. Щоб пропонувати також пункти Jadlog Pickup, увімкніть Enable Jadlog Pickup і натисніть Save.

Під час встановлення модуль створює двох перевізників: Jadlog (доставка додому, увімкнено, текст терміну доставки Jadlog delivery to your address) і Jadlog Pickup (вимкнено, текст терміну доставки Pickup at a Jadlog Pickup point). Обидва прив'язані до зони Бразилії та до всіх груп клієнтів. Зони, групи клієнтів, термін доставки, логотип і обмеження розмірів можна змінити в Shipping > Carriers. Не встановлюйте там ціни: ціна завжди береться з модуля.

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox Jadlog > Configure. Вони застосовуються до обох перевізників Jadlog. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Кожне збереження також очищає кеш цін Jadlog і списків пунктів Pickup.

Угорі сторінки модуль показує попередження про неповне налаштування: немає токена API (використовуються лише фіксовані ціни, а пункти Pickup не можна вивести списком), немає ні токена API, ні фіксованих цін (спосіб доставки ніколи не показується), не вказано CNPJ або поточний рахунок, не вказано CEP відправлення, не задано курс BRL для магазину, який продає не в BRL, одиниця ваги або розмірів магазину, яку модуль не розпізнає (тоді ваги приймаються в кг, а розміри в см; задайте одиниці в International > Localization, Local units), або видалений перевізник Jadlog. Під час збереження повідомляються некоректні значення: CEP без 8 цифр, CNPJ без 14 цифр (або 11 для CPF), некоректне число, мінімальна вага більша за максимальну (обидві ваги зберігають збережені значення), невідома країна або некоректна ціна в таблиці цін.

General

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

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

Tax status: None або Taxable з одним із ваших податкових правил. Значення зберігається для обох перевізників Jadlog. Ціни Jadlog є остаточними цінами перевізника. Виберіть None, якщо PrestaShop не повинен додавати до них податок.

Jadlog live prices

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

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

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

CNPJ: CNPJ (14 цифр) або CPF (11 цифр) відправника, зазначений у договорі з Jadlog. Допускаються крапки, косі риски та дефіси.

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

Contract number: номер вашого договору з Jadlog, якщо він був присвоєний вашим франчайзі.

Origin CEP: поштовий індекс, з якого відправляються посилки, 8 цифр. Зберігається у форматі 00000-000. Залиште поле порожнім, щоб використовувати поштовий індекс магазину з Shop Parameters > Contact > Stores, якщо адреса магазину в Бразилії.

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 і поруч із кожним пунктом Pickup, наприклад «Delivery time: 3 business days». За замовчуванням увімкнено. Термін доставки завжди зберігається із замовленням.

Jadlog Pickup

Другий перевізник із послугою Jadlog Pickup (40). Потрібен токен API. Без пунктів перевізник приховується.

Enable Jadlog Pickup: вмикає або вимикає перевізника Jadlog Pickup. Це той самий перемикач, що й його статус у Shipping > Carriers. Після встановлення вимкнено.

Jadlog Pickup carrier name: назва цього варіанта під час оформлення замовлення. За замовчуванням: Jadlog Pickup. Обов'язкове поле.

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

Fixed prices (використовуються, коли немає токена 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 уже охоплюють весь кошик.

Conditions

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

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

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

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

Availability without shipping zones

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

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

Advanced

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

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

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

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

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

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

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

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

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

Пункти Pickup

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

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

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

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

Замовлення

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

Сторінка замовлення в адмінпанелі показує блок Jadlog з Jadlog service, Delivery time і для Jadlog Pickup — Pickup point, Pickup point address та Pickup point ID. Покупець бачить обраний пункт на сторінці підтвердження замовлення та в деталях замовлення. Пункт додається до назви перевізника в електронному листі з підтвердженням замовлення. Лист про нове замовлення магазину (якщо ви використовуєте модуль сповіщень електронною поштою) також містить ID пункту.

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

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

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

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

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

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

Jadlog не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і увімкнено Enable/Disable (або Enable Jadlog Pickup). У Shipping > Carriers перевірте, що перевізник охоплює зону країни покупця і групу покупця, або увімкніть Ignore shipping zones. Перегляньте попередження вгорі сторінки модуля, обмеження ваги та Minimum order amount. Якщо покупець ще не ввів повний 8-значний CEP, можна використовувати лише фіксовані ціни, тож додайте рядок у Price per country або Fallback cost. Також на сторінці товару можна обмежити товари певними перевізниками.

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

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

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

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

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

До цін Jadlog додається податок: встановіть Tax status у None.

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

Сторінка повідомляє, що перевізника Jadlog не знайдено: перевізника видалено в Shipping > Carriers. Скиньте модуль у Modules > Module Manager, щоб створити його знову.

Видалення

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

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