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

Вимоги

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

PHP: 8.0 або новіший з розширенням cURL.

Обліковий запис DrEnvio (лише для тарифів у реальному часі): тарифи Estafeta в реальному часі надходять від DrEnvio, партнера Estafeta в Мексиці. Створіть обліковий запис на drenvio.com, увімкніть Estafeta, налаштуйте там свою адресу забору відправлень і скопіюйте ключ API з панелі DrEnvio. Це той самий ключ, який використовує офіційний плагін DrEnvio. Якщо ви користуєтеся лише власними цінами, обліковий запис DrEnvio не потрібен.

Товари: для тарифів у реальному часі товарам потрібна вага.

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

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

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

OpenCart 3

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

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

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

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

5. Введіть DrEnvio API key і, за бажанням, Origin postcode. Якщо валюта магазину за замовчуванням не MXN, введіть MXN exchange rate. Задайте ціну для країни MX або Fallback cost, якщо спосіб доставки має залишатися видимим, коли DrEnvio не повертає тариф. Увімкніть Enable/Disable і натисніть Save.

OpenCart 4

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

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

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

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

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

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

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

У верхній частині сторінки розширення показує попередження: немає ключа API DrEnvio, валюта магазину за замовчуванням не MXN і немає курсу обміну, немає ціни для країни MX і немає запасної вартості (тоді спосіб доставки приховано, коли немає тарифу в реальному часі, або він ніколи не показується без ключа API), або немає класу ваги в кілограмах (ваги товарів тоді перераховуються за назвою одиниці їхнього класу ваги, а невідомі одиниці вважаються кілограмами; додайте клас kg у розділі System > Localisation > Weight Classes). Числові поля приймають крапку або кому як десятковий роздільник. Під час збереження неправильне значення повідомляється, а потім очищується або скидається, як описано для кожного поля; форма показує збережене значення, а інші налаштування все одно зберігаються (The other settings were saved.).

Загальні

Спосіб доставки пропонується для геозони нижче (або для будь-якої адреси) або для країн із Availability without shipping zones.

Enable/Disable: вмикає або вимикає доставку Estafeta. За замовчуванням: вимкнено.

Name: назва способу доставки, яку бачить покупець під час оформлення замовлення. За замовчуванням: Estafeta. Обов'язкове поле: від 1 до 64 символів, без < > ; = # { }. Неприпустима назва повідомляється, і зберігається попередня.

Tax class: клас податку, що додається до вартості доставки, або No tax (за замовчуванням). Чи включає тариф DrEnvio IVA, залежить від вашого облікового запису DrEnvio. Якщо IVA вже включено, виберіть No tax.

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

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

Тарифи в реальному часі (API DrEnvio)

Розділ пояснює, де взяти ключ. Пропонується найдешевша послуга Estafeta для адреси. Без ключа використовуються ціни з Prices without a live rate.

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

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

Origin country: двосимвольний код країни адреси забору відправлень. За замовчуванням: MX. Надсилається лише разом із поштовим індексом відправника. Неправильний код повідомляється і скидається на MX.

Origin postcode: п'ятизначний поштовий індекс адреси забору відправлень. Залиште порожнім, щоб використовувати адресу відправника, збережену у вашому обліковому записі DrEnvio. Індекс, у якому не 5 цифр, під час збереження очищується і повідомляється.

MXN exchange rate: DrEnvio розраховує вартість у мексиканських песо. Потрібен, лише якщо валюта магазину за замовчуванням не MXN: вартість 1 MXN у валюті магазину за замовчуванням, наприклад 0.05. Без нього тарифи в реальному часі не використовуються. Значення має бути більшим за 0. Якщо валюта магазину MXN, залиште поле порожнім.

Ціни без тарифу в реальному часі

Використовуються, коли немає ключа API або DrEnvio не повертає тариф Estafeta (API недоступний, невідомий поштовий індекс, індекс ще не введено). Ціни вказано у валюті магазину за замовчуванням, без податків.

Country prices: одна країна призначення в рядку у форматі CC:ЦІНА, наприклад MX:150. Використовуйте крапку або кому як десятковий роздільник, без роздільника розрядів. Частини в іншому форматі ігноруються і повідомляються під час збереження.

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

Calculation type: Per order (за замовчуванням) стягує ціну один раз. Per item (price x number of items) множить її на кількість товарів у кошику. Це стосується Country prices і Fallback cost. Тариф DrEnvio в реальному часі завжди є ціною всієї посилки.

Умови

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

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

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

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

Якщо Min weight більша за Max weight, під час збереження з'являється помилка, і обидві ваги залишаються без змін. Ваги товарів переводяться в кілограми за класом ваги кожного товару.

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

Ignore shipping zones: пропонувати спосіб доставки для країн нижче без перевірки геозони. За замовчуванням: вимкнено.

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

Додатково

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

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

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

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

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

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

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

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

Інакше розширення надсилає DrEnvio країну та поштовий індекс призначення, вагу кошика, кількість товарів і суму в MXN, а також поштовий індекс відправника, якщо ви його задали. Мексиканські поштові індекси мають містити 5 цифр; доки покупець не введе адресу доставки з таким індексом, запит не надсилається. DrEnvio повертає розрахунки всіх перевізників вашого облікового запису. Розширення використовує лише розрахунки Estafeta, ігнорує нульові ціни, обирає найдешевшу і переводить її у валюту магазину за замовчуванням. Ціна округлюється до знаків цієї валюти і показується покупцеві у його валюті з податком обраного Tax class.

Кожна відповідь кешується на 1 годину. Невдалий запит або маршрут без тарифу Estafeta запам'ятовується на 5 хвилин, щоб повільний або зламаний API ніколи не гальмував кожне оновлення оформлення замовлення. Тайм-аут API становить 12 секунд. У таких випадках покупець не бачить помилки: використовується ціна для країни або запасна вартість, або спосіб доставки приховується, якщо немає ні того, ні іншого. Причина записується в журнал.

Покупець бачить лише назву способу доставки та ціну. Розширення лише розраховує тарифи. Воно не створює відправлень, не друкує накладні (guías) і не відстежує посилки; створюйте відправлення у своєму обліковому записі DrEnvio або Estafeta. Покупець не може вибрати конкретну послугу Estafeta чи відділення Estafeta, а курси валют не оновлюються автоматично.

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

Замовлення

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

Сторінка замовлення в Sales > Orders показує панель Estafeta:

Estafeta service: послуга Estafeta з розрахунку DrEnvio та її строк доставки. Показується лише для тарифів у реальному часі.

Price source: Live DrEnvio rate, Country price (no live rate), Fallback cost (no live rate) або Free shipping threshold.

Shipping cost: ціна доставки, розрахована під час оформлення замовлення, у валюті магазину за замовчуванням, без податку.

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

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

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

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

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

Estafeta не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і Enable/Disable увімкнено. Перевірте Geo zone або Ignore shipping zones і Countries. Перевірте попередження у верхній частині сторінки розширення, обмеження ваги та Minimum subtotal. Без ключа API або коли DrEnvio не має тарифу Estafeta, спосіб доставки потребує ціни для країни призначення або запасної вартості. Перевірте, що товари мають Requires Shipping, встановлений у Yes.

Тарифи в реальному часі не з'являються: увімкніть Debug log, перезавантажте оформлення замовлення і подивіться поле Log на сторінці розширення. Там вказано причину: немає ключа API; немає курсу обміну для магазину, валюта якого не MXN; поштовий індекс відсутній або невірний; ключ API відхилено (HTTP 401 або 403 від DrEnvio, перевірте ключ API); немає тарифу Estafeta для маршруту (у журналі перелічено перевізників, яких повернув DrEnvio); або тариф у валюті, відмінній від MXN.

Чи включає ціна IVA? Це залежить від вашого облікового запису DrEnvio. Якщо ціни DrEnvio вже включають IVA, встановіть Tax class у No tax.

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

На сторінці замовлення немає панелі Estafeta: панель показується лише для замовлень, оформлених з Estafeta, поки розширення було встановлено й увімкнено.

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

Для розробників: адресу API DrEnvio можна замінити налаштуванням vfd_est_api_url (для тестів); для нього немає поля на сторінці налаштувань.

Видалення

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

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

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