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

Вимоги

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

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

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

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

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

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

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

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

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Shipping > VibeFox Delhivery > Edit. Розділи перелічені ліворуч. Одна кнопка Save зберігає всю сторінку без перезавантаження. Кожне збереження також очищує закешовані тарифи Delhivery. Суми приймають «9.99» і «9,99». Якщо значення неправильне, нічого не зберігається, а сторінка показує причину, наприклад Enter a valid method title (without < > ; = # { })., повідомлення про те, що поле має бути невід'ємним числом, або Sort order must be a whole number. Зберігати налаштування можуть лише адміністратори з правом змінювати це розширення.

Якщо основна валюта магазину не INR, API-токен збережено, а курс обміну не встановлено, попередження у верхній частині сторінки нагадує, що актуальні тарифи не використовуються, доки ви не введете курс. Якщо в магазині немає класу ваги в кілограмах і його одиниця ваги не стандартна (kg, g, lb або oz), попередження повідомляє, що ваги товарів читаються як кілограми. Встановіть стандартну одиницю в System > Localisation > Weight Classes.

Загальні

Налаштування застосовуються до всіх географічних зон. Спосіб доставки можна обмежити в розділі Availability.

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

Method title: назва способу доставки, яку бачить покупець у кошику та під час оформлення замовлення. За замовчуванням: Delhivery. Обов'язкове поле, не більше 64 символів, без символів < > ; = # { }.

Tax class: податковий клас вартості доставки або No tax (за замовчуванням). З класом OpenCart додає податок до вартості доставки.

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

Обліковий запис 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-значний pincode вашого пункту відправлення або складу, наприклад 110001. Якщо в ньому не 6 цифр, налаштування зберігаються з попередженням The origin pincode must have 6 digits — live rates are not requested until it is fixed.

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

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

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 (store currency) conversion rate: підпис показує основну валюту вашого магазину. Тарифи Delhivery вказані в індійських рупіях. Якщо основна валюта не INR, вкажіть, скільки одиниць вашої валюти коштує одна рупія, наприклад 0.011. Курс має бути більшим за 0. Якщо залишити поле порожнім, актуальні тарифи не використовуються і застосовуються фіксовані ціни. Якщо основна валюта INR, поле не потрібне.

Фіксовані ціни (використовуються, коли актуальний тариф недоступний)

Фіксовані ціни застосовуються, коли ще немає токена або pincode, напрямок знаходиться поза Індією, pincode не обслуговується або API повертає помилку. Вони вказані в основній валюті магазину, без податків.

Prices per country: по одній на рядок у форматі КОД_КРАЇНИ:ціна, наприклад 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 (kg): мінімальна вага кошика, за якої показується спосіб доставки. 0 означає без обмеження (за замовчуванням).

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

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

Доступність

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

Ignore zones: якщо увімкнено, географічна зона не перевіряється, і спосіб доставки пропонується для країн нижче (для всіх країн, якщо список порожній).

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

Додатково

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

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

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

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

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

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

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

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

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

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

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

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

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

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

В OpenCart 4 оформлення замовлення зберігає одне замовлення і оновлює його щоразу, коли покупець знову підтверджує оформлення. Режим і джерело ціни оновлюються разом із ним. Якщо покупець перемикається на інший спосіб доставки до введення AWB, панель Delhivery для цього замовлення більше не показується.

Створіть відправлення в Delhivery One, потім введіть його AWB на панелі та натисніть Save. Сторінка не перезавантажується. Літери, цифри та дефіси зберігаються (до 64 символів). Щоб видалити AWB, збережіть порожнє поле. Якщо AWB вказано, панель показує посилання Track on delhivery.com. Для збереження AWB потрібне право змінювати замовлення. Без нього панель лише для читання.

Зареєстрований покупець бачить на сторінці замовлення у своєму обліковому записі рядок Delhivery tracking: з AWB як посиланням на сторінку відстеження Delhivery. Коли ви додаєте запис в історію замовлення і повідомляєте покупця, лист про статус замовлення містить той самий рядок із посиланням. Лист про нове замовлення посилання для відстеження не містить, бо AWB вводиться пізніше. Панель і посилання для відстеження працюють і для старих замовлень, навіть коли розширення вимкнено.

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

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

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

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

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

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

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

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

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

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

AWB не зберігається: повідомлення You do not have permission to modify orders. означає, що вашій групі адміністраторів потрібне право змінювати sale/order у System > Users > User Groups.

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

Для розробників: розширення викликає події OpenCart catalog/vfd_delhivery/api_url і catalog/vfd_delhivery/api_timeout, які можуть змінити адресу API та тайм-аут.

Видалення

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

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

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