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

Вимоги

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

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

Обліковий запис Shippo: створіть обліковий запис Shippo, підключіть або увімкніть перевізників (USPS, UPS, FedEx, DHL та інших) і скопіюйте токен API з Shippo > Settings > Advanced > API. Shippo стягує плату за придбані етикетки, а не за запити тарифів. Нові облікові записи Shippo можуть потребувати перевірки з боку Shippo, перш ніж почнуть повертатися актуальні тарифи. Без токена використовуються лише запасні ціни.

Товари: товари мають мати вагу та габарити. Товари без габаритів використовують типовий розмір коробки.

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

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

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

OpenCart 3

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

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

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

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

5. Вставте ваш токен API Shippo і заповніть адресу Ship from. Поштовий індекс обов'язковий для актуальних тарифів.

6. Оберіть Shippo rate currency (USD, якщо ви відправляєте зі США) і, якщо валюта магазину за замовчуванням інша, введіть Exchange rate.

7. За бажанням введіть запасні ціни, увімкніть Enable Shippo shipping і натисніть Save.

OpenCart 4

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

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

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

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

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

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

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

Попередження у верхній частині сторінки повідомляють, коли спосіб доставки ніколи не може бути показаний або коли актуальні тарифи неможливо використати: немає токена API, немає поштового індексу чи країни відправлення, немає курсу обміну, або одиниця ваги чи довжини магазину не розпізнається розширенням (використовуйте кг, г, фунти або унції та см, мм, м або дюйми в System > Settings, вкладка Local). Повідомлення нагадує, коли встановлено тестовий токен. Під час збереження некоректна назва, значення, що не є числом, від'ємне число або комірка ціни, Minimum weight (kg) більше за Maximum weight (kg) або порядок сортування, що не є цілим числом, позначаються як помилка, і нічого не зберігається, доки ви їх не виправите.

Загальні

Enable Shippo shipping: пропонує спосіб доставки під час оформлення замовлення. Це стан розширення в Extensions > Extensions > Shipping.

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

Tax class: клас податку на вартість доставки або No tax. Тарифи Shippo не включають податок з продажу. No tax показує їх так, як вони котируються; клас податку додає податок на доставку за вашими податковими правилами.

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

Обліковий запис Shippo

API token: ваш токен API Shippo. Використовуйте робочий токен (shippo_live_...) для актуальних тарифів у робочому магазині або тестовий токен (shippo_test_...) для тестових тарифів Shippo. Токен надсилається лише до Shippo і ніколи не записується в журнал. Після збереження поле лишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

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

Allowed carriers / services: необов'язково, через кому. Введіть перевізника так, як його називає Shippo (USPS, UPS, FedEx, DHL Express), або токен рівня послуги Shippo (usps_priority, ups_ground). Показується найдешевший дозволений тариф. Залиште порожнім, щоб показувати найдешевший тариф будь-якого перевізника.

Ship from (адреса, з якої відправляються ваші посилки)

Коли країна відправлення збігається з країною вашого магазину, порожні ім'я відправника та регіон беруться з назви магазину та регіону в System > Settings. В OpenCart немає структурованих даних про вулицю, місто або поштовий індекс магазину, тож введіть їх тут.

Sender name / company: ім'я відправника. Його також використовують для підпису митної декларації. Якщо поле порожнє, використовується назва магазину.

Street address: вулиця відправника.

City: місто відправника.

State / province: дволітерний код штату, наприклад CA або NY. Деякі перевізники його потребують.

Postal / ZIP code: обов'язковий для актуальних тарифів, наприклад 94105.

Country: країна, з якої ви відправляєте. За замовчуванням: Сполучені Штати.

Тарифи

Parcels: як кошик передається в Shippo.

Default box size: довжина x ширина x висота в лінійній одиниці вашого магазину (вона вказана в назві поля), наприклад 30 x 20 x 10. Shippo потребує розмір коробки. Він використовується, коли в товару в кошику немає габаритів. Залиште порожнім, щоб використовувати 30 x 20 x 10 см. Значення, яке не вдалося прочитати, ігнорується з повідомленням після збереження, а інші налаштування зберігаються.

Shippo rate currency: валюта, в якій Shippo котирує ваших перевізників, тобто валюта країни відправлення: USD (США), CAD (Канада), GBP (Велика Британія), EUR (єврозона) або AUD (Австралія). За замовчуванням: USD. Тарифи, які Shippo повертає у валюті за замовчуванням вашого магазину, завжди використовуються як є.

Exchange rate: ціна 1 одиниці валюти тарифів Shippo у валюті за замовчуванням вашого магазину, наприклад 0.92. Не потрібен, якщо валюти однакові. Без нього тарифи в іншій валюті не використовуються, і діють запасні ціни. Розширення не конвертує валюти автоматично.

Запасні ціни (використовуються, коли актуального тарифу немає: немає токена API, Shippo недоступний, токен відхилено або немає тарифів перевізників для адреси; ціни у валюті магазину за замовчуванням, без податку; залиште обидва поля порожніми, щоб у цьому випадку приховати спосіб доставки)

Country prices: таблиця цін за країною та вагою кошика. Натисніть Add country, щоб додати рядок. Колонки: Price і вагові категорії XS (до 1 кг), S (від 1 до 2 кг), M (від 2 до 3 кг), L (від 3 до 5 кг) та XL (понад 5 кг). Порожня категорія або категорія 0 використовує колонку Price. Рядок * Default застосовується до країн без власного рядка. Рядок, збережений з усіма порожніми комірками, стягує 0, тож видаляйте рядки, які ви не заповните.

Other countries: ціна для країн, яких немає в таблиці вище (коли немає рядка * Default). Залиште порожнім, щоб приховати спосіб доставки для цих країн.

Умови

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

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

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

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

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

Зазвичай геозона визначає, де пропонується спосіб доставки. Також його можна пропонувати за країною, незалежно від геозони.

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

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

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

Додатково

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

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

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

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

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

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

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

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

Далі розширення передає Shippo адресу відправлення магазину, адресу покупця та посилку. Для країн, де OpenCart вимагає поштовий індекс, запит чекає, поки покупець його введе. Для міжнародних відправлень додається митна декларація з назвами товарів (з вибраними опціями), кількістю, вагою та вартістю. Shippo повертає тарифи ваших перевізників, і розширення використовує найдешевший дозволений тариф. Ціна обчислюється у валюті за замовчуванням вашого магазину, округлюється до потрібної кількості знаків і показується покупцеві у його валюті з податком обраного Tax class.

У режимі «за замовлення» товари складаються в одну коробку: найдовша і середня сторони найбільших товарів, а також найменші сторони всіх одиниць, додані разом. Якщо в якогось товару немає габаритів, для всієї посилки використовується типовий розмір коробки. У режимі «за товар» кожен товар тарифікується як окрема посилка, а тариф множиться на його кількість.

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

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

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

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

Замовлення

Коли замовлення оформлюється з актуальним тарифом Shippo, розширення зберігає обраний Carrier / service і, для однієї посилки на замовлення, Estimated delivery days. Відкрийте замовлення в Sales > Orders: ці дані відображаються в панелі Shippo над історією замовлення, щоб ви могли купити відповідну етикетку в Shippo. Дані зберігаються разом із замовленням: пізніші зміни кошика або налаштувань їх не змінюють. Панель також показується після того, як ви вимкнули спосіб доставки. У замовлень із запасною ціною або безкоштовною доставкою панелі Shippo немає.

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

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

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

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

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

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

Shippo не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і Enable Shippo shipping увімкнено. Перевірте Geo zone (або, якщо ввімкнено Ignore shipping zones, Countries), обмеження ваги та Minimum subtotal. Без актуального тарифу перевірте, що для країни, рядка * Default або Other countries є ціна. Перевірте, що в товарів Requires Shipping встановлено Yes.

Актуальні тарифи не з'являються: увімкніть Debug log, перезавантажте оформлення і подивіться поле Log на сторінці розширення. Поширені причини: немає токена API або поштового індексу відправлення; валюта магазину за замовчуванням відрізняється від валюти тарифів Shippo без курсу обміну; покупець ще не ввів поштовий індекс; жоден з перевізників вашого облікового запису Shippo не обслуговує адресу; або обліковий запис Shippo ще не перевірено.

Тестові тарифи в робочому магазині: тестовий токен (shippo_test_...) повертає тестові тарифи Shippo. Використовуйте робочий токен (shippo_live_...).

Безкоштовна доставка для неочікуваних країн: перевірте таблицю цін на наявність порожнього рядка, особливо порожнього рядка * Default. Рядок з усіма порожніми комірками стягує 0.

Неправильні ваги або розміри коробок: якщо сторінка попереджає про невідому одиницю ваги або довжини, встановіть ваговий клас у кг, г, фунтах або унціях та лінійний клас у см, мм, м або дюймах в System > Settings, вкладка Local.

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

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

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

Видалення

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

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

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