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

Вимоги

PrestaShop: 8.0–9.x.

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

API-токен Delhivery (лише для актуальних тарифів): увійдіть у Delhivery One і відкрийте Settings > API setup. Стаття довідки Delhivery «API token generation» пояснює кроки. Обидва посилання є на сторінці модуля. Тестові токени працюють із середовищем staging. Також потрібен 6-значний PIN-код вашого місця забору. Якщо ви використовуєте лише фіксовані ціни, токен не потрібен.

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

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

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

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

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

4. Введіть API-токен і PIN-код відправлення, оберіть Express або Surface та Pre-paid або COD. Якщо валюта за замовчуванням вашого магазину не INR, введіть курс конвертації. За бажанням введіть фіксовані ціни (див. розділ «Налаштування»). Натисніть Save.

Під час встановлення модуль створює перевізника Delhivery із текстом терміну доставки Courier delivery (India) і сторінкою відстеження Delhivery як URL відстеження. Перевізника призначено всім зонам і всім групам клієнтів. Зони, групи клієнтів, термін доставки, логотип і обмеження розміру можна змінити в Shipping > Carriers. Не встановлюйте там ціни: ціна завжди береться з модуля.

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

Усі параметри розташовано на сторінці модуля: Modules > Module Manager > VibeFox Delhivery > Configure. Вони діють для всіх зон. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Кожне збереження також очищає кеш тарифів Delhivery. Суми приймаються у форматах «9.99» і «9,99». Якщо в числовому полі немає невід'ємного числа, з'являється помилка і нічого не зберігається.

Якщо валюта за замовчуванням вашого магазину не INR, API-токен збережено, а курс конвертації не задано, попередження над формою нагадує, що актуальні тарифи не використовуються, доки ви не введете курс. Якщо одиниця ваги магазину не є стандартною (кг, г, фунти або унції), попередження просить встановити її в International > Localization (Local units), бо інакше вагу товарів буде прочитано як кілограми.

Загальні

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

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

Tax: податкове правило перевізника або No tax. З правилом PrestaShop додає податок до вартості доставки.

Обліковий запис API Delhivery (потрібен лише для актуальних тарифів)

Environment: Production (track.delhivery.com) (за замовчуванням) або Staging / test account (staging-express.delhivery.com). Використовуйте Staging лише з тестовим токеном Delhivery.

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

Remove saved token: увімкніть і збережіть, щоб видалити збережений токен. Після цього використовуються лише фіксовані ціни.

Origin pincode: 6-значний PIN-код вашого місця забору або складу, наприклад 110001. Якщо в ньому не 6 цифр, з'являється попередження, і актуальні тарифи не запитуються, доки це не буде виправлено.

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

Актуальний тариф запитується для індійських адрес призначення з правильним 6-значним PIN-кодом, для прямого відправлення (доставки).

Shipping mode: режим тарифікації Delhivery, за яким розраховується тариф: Express (за замовчуванням) або Surface.

Payment type: тип оплати, що передається в Delhivery: Pre-paid (за замовчуванням) або COD (cash on delivery — Delhivery adds its COD charge). Модуль не змінює його залежно від способу оплати, який обирає покупець.

Rate amount: Delhivery повертає суму з GST і без GST.

INR to (shop currency) conversion rate: у підписі вказано валюту за замовчуванням вашого магазину. Тарифи Delhivery вказані в індійських рупіях. Якщо валюта за замовчуванням не INR, введіть, скільки одиниць вашої валюти коштує одна рупія, наприклад 0.011. Курс має бути більшим за 0. Якщо залишити поле порожнім, актуальні тарифи не використовуються і діють фіксовані ціни. Не потрібно, якщо валюта за замовчуванням — INR.

Фіксовані ціни (використовуються, коли актуального тарифу немає)

Фіксовані ціни використовуються, коли ще немає токена або PIN-коду, коли адреса призначення знаходиться за межами Індії, коли PIN-код не обслуговується або коли API повертає помилку. Ціни вказуються у валюті за замовчуванням вашого магазину без податків.

Prices per country: по одному запису в рядку у форматі COUNTRY_CODE:price, наприклад IN:120. Перевіряються раніше за резервну ціну. Рядки в іншому форматі видаляються під час збереження, і попередження їх перелічує.

Fallback price: використовується, коли не застосовуються ні актуальний тариф, ні ціна за країною. Залиште поле порожнім, щоб приховати перевізника. 0 означає безкоштовно.

Fixed price is charged: Per order стягує ціну один раз. Per item (price × quantity) множить її на кількість товарів у кошику. Актуальний тариф Delhivery завжди розраховується за загальною вагою посилки.

Умови

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

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

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

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

Ваги товарів переводяться в кг з одиниці ваги вашого магазину. Тариф використовує фактичну вагу кошика (суму ваг товарів), без об'ємної ваги та коробок.

Доступність без зон доставки

Ignore zones: коли опцію вимкнено, країни визначаються зонами перевізника в Shipping > Carriers. Коли опцію увімкнено, перевізника пов'язують з усіма зонами (зокрема з тими, які ви створите пізніше) і пропонують для країн, зазначених нижче. Вимкнення повертає перевізнику його попередні зони.

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

Додатково

Debug log: записує розрахунки тарифів у logs/vfd_dlv_debug.log.php у папці модуля. Файл не можна відкрити з веб. Помилки API завжди записуються в журнал, навіть коли опцію вимкнено. Токени та повні PIN-коди покупців ніколи не записуються.

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

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

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

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

Для індійської адреси з правильним 6-значним PIN-кодом модуль надсилає в Delhivery PIN-коди відправлення та призначення, вагу кошика в грамах, режим доставки та тип оплати. Повернена сума переводиться з INR у валюту за замовчуванням вашого магазину і потім показується у валюті кошика покупця. Кожна відповідь кешується на 1 годину. Невдалий запит кешується на 10 хвилин, щоб оформлення замовлення не чекало Delhivery під час кожного оновлення. Тайм-аут API становить 10 секунд.

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

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

Модуль розраховує тарифи і дає покупцям посилання для відстеження. Він не створює відправлень і накладних, не друкує етикеток, не замовляє забір і маніфести, не перевіряє обслуговування PIN-кодів, не оцінює дати доставки, не синхронізує статуси відстеження та не розраховує міжнародні тарифи Delhivery. Поза межами Індії використовуються лише фіксовані ціни.

Замовлення та відстеження

Коли замовлення оформлено з Delhivery, модуль зберігає разом із замовленням режим доставки та джерело ціни. На сторінці замовлення в адмінпанелі блок Delhivery показує Mode: (Express або Surface), Price: (актуальний тариф Delhivery, фіксована ціна або поріг безкоштовної доставки) і Delhivery AWB / tracking number, або Not entered yet.

Створіть відправлення в Delhivery One, потім введіть його номер AWB як номер для відстеження замовлення в блоці Carriers на сторінці замовлення (Edit). Після цього блок Delhivery покаже посилання Track on delhivery.com. Покупець бачить посилання для відстеження в історії замовлення і отримує від PrestaShop лист зі статусом «В дорозі».

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

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

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

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

Вирішення проблем

Delhivery не з'являється під час оформлення замовлення: переконайтеся, що ліцензія активна і увімкнено Enable Delhivery. У Shipping > Carriers перевірте, що перевізник охоплює зону країни покупця і групу покупця, або увімкніть Ignore zones і перевірте Countries. Перевірте обмеження ваги та Show from subtotal. Без актуального тарифу потрібна ціна за країною або Fallback price. Товари також можна обмежити певними перевізниками на сторінці товару.

Актуальні тарифи не з'являються: перевірте API-токен, правильний Origin pincode і, якщо валюта за замовчуванням не INR, курс конвертації. Покупець має ввести правильний 6-значний індійський PIN-код. Увімкніть Debug log, перезавантажте оформлення замовлення і перегляньте поле Log на сторінці модуля. Там буде вказано причину, наприклад PIN-код, який не обслуговується, або HTTP-помилку від Delhivery.

GST нараховується двічі: загальна сума Delhivery вже містить GST. Установіть Rate amount у значення Gross amount (excluding GST) або установіть Tax у значення No tax.

Тестування: установіть Environment у значення Staging і використовуйте тестовий токен Delhivery.

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

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

Для розробників: модуль виконує хуки actionVfdDlvApiUrl і actionVfdDlvApiTimeout, які можуть змінити адресу API та тайм-аут.

Видалення

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

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