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

Вимоги

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

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

Обліковий запис EasyPost (лише для актуальних тарифів): створіть обліковий запис на сайті EasyPost, підключіть свої транспортні облікові записи (USPS, UPS, FedEx та інші) в панелі EasyPost і скопіюйте API-ключ з EasyPost Dashboard > Account Settings > API Keys. EasyPost стягує плату за придбані етикетки, а не за запити тарифів. Якщо ви використовуєте лише резервні ціни, обліковий запис EasyPost не потрібен.

Товари: товарам потрібні вага і бажано габарити.

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

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

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

OpenCart 3

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

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

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

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

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

6. Якщо валюта магазину за замовчуванням не USD, введіть USD exchange rate. За бажанням введіть резервні ціни (див. Налаштування). Увімкніть Enable EasyPost shipping і натисніть Save.

OpenCart 4

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

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

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

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

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

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

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

Угорі сторінки розширення показує попередження, коли актуальні тарифи не можна використати: немає API-ключа (з резервними цінами або без них), немає поштового індексу чи країни відправлення, або валюта за замовчуванням не USD без курсу обміну. Також з'являється примітка, коли задано тестовий API-ключ, і попередження, коли одиниця ваги або довжини вашого магазину (System > Settings > Option) не відома розширенню (kg, g, lb, oz; cm, mm, m, in).

При збереженні назва довша за 64 символи, Sort order, який не є цілим числом, або невідомий податковий клас чи геозона не дають зберегти налаштування, і тоді нічого не зберігається. Значення, яке не є числом (або є від'ємним), не зберігається: попередження називає поле, а попереднє значення лишається, решта налаштувань зберігається. Так само буде, якщо USD exchange rate дорівнює 0, або якщо Minimum weight більше за Maximum weight.

Загальні

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

Name: назва способу доставки, яку бачить покупець на оформленні замовлення, не більше 64 символів. За замовчуванням: EasyPost Shipping. Якщо назва порожня, використовується назва за замовчуванням. Назва із символами < > ; = # { } замінюється назвою за замовчуванням з попередженням.

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

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

API key: ваш API-ключ EasyPost з EasyPost Dashboard > Account Settings > API Keys. Робочий ключ (починається з EZAK) повертає справжні тарифи. Тестовий ключ (починається з EZTK) повертає тестові тарифи EasyPost; використовуйте його лише для перевірки. Після збереження поле лишається порожнім і показує збережений ключ у замаскованому вигляді, наприклад Saved key: EZAK******abcd. Leave the field empty to keep it. Вводьте нове значення, лише якщо хочете його змінити. Без ключа використовуються лише резервні ціни.

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

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

Адреса відправлення

Адреса, з якої відправляються ваші посилки. Якщо Country є країною вашого магазину, порожнє поле Sender name / company береться з назви магазину, а порожнє поле State з регіону магазину (System > Settings). В OpenCart немає поштового індексу магазину, тож поштовий індекс потрібно вказати тут.

Sender name / company: ім'я відправника або назва компанії. Порожнє значення означає назву магазину (лише для тієї самої країни).

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

City: місто адреси відправлення.

State: двобуквений код штату, наприклад CA або NY.

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

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

Тарифи

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

Ваги переводяться з одиниці ваги вашого магазину в унції (мінімум 1 oz), а габарити з одиниці довжини магазину в дюйми. Якщо в якогось товару немає габаритів, посилка тарифікується лише за вагою.

USD exchange rate: тарифи EasyPost вказані в USD. Введіть ціну 1 USD у валюті магазину за замовчуванням, наприклад 0.92. Без нього актуальні тарифи не використовуються, лише резервні ціни. Не потрібен, якщо валюта магазину за замовчуванням USD. Магазини в USD і CAD просять EasyPost розраховувати в їхній валюті. Приймаються і крапка, і кома як десятковий роздільник.

Tax class: податковий клас, що застосовується до доставки, або No tax. Тарифи EasyPost не включають податок з продажу.

Резервні ціни

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

Country prices: один рядок на країну: двобуквений код країни, двокрапка і ціна, наприклад US:9.99. Рядки в іншому форматі ігноруються і перелічуються в попередженні під час збереження.

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

Умови

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

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

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

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

Доступність

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

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

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

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

Додатково

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

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

Remove data on uninstall: якщо увімкнено, видалення розширення стирає його налаштування та журнал. Дані EasyPost оформлених замовлень зберігаються. Вимкнення способу ніколи не стирає налаштування.

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

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

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

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

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

Інакше розширення надсилає в EasyPost адресу відправлення, адресу доставки та посилку і отримує тарифи всіх ваших транспортних облікових записів. Воно обирає найдешевший дозволений тариф, переводить його у валюту магазину за замовчуванням і показує покупцеві у його валюті з податком обраного Tax class. Для країн, позначених як Postcode Required у System > Localisation > Countries, запит робиться лише тоді, коли в адресі доставки є поштовий індекс. У стандартних даних OpenCart цей прапорець вимкнено для США, тож адреса в США без поштового індексу теж надсилається; EasyPost тоді повертає помилку, і використовується резервна ціна.

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

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

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

Замовлення

Коли оформлюється замовлення зі способом EasyPost, тариф, показаний на оформленні замовлення, зберігається разом із замовленням. Сторінка замовлення в адмін-панелі (Sales > Orders) показує блок EasyPost shipping над історією:

Carrier / service: перевізник і послуга EasyPost для тарифу, наприклад USPS Priority. У режимі одна посилка на товар перелічуються всі використані послуги.

Estimated delivery days: строки доставки, які повернув EasyPost (лише в режимі одна посилка на замовлення, коли EasyPost їх повертає).

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

Calculated price (excl. tax): ціна у валюті магазину за замовчуванням.

Блок показується, навіть якщо розширення згодом буде вимкнено. Подальші зміни замовлення в адмін-панелі не змінюють ці значення. Використовуйте їх, щоб купити етикетку у своєму обліковому записі EasyPost. OpenCart створює запис замовлення щоразу, коли оформлення доходить до кроку підтвердження; збережені тарифи таких незавершених замовлень видаляються через 30 днів.

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

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

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

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

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

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

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

Актуальні тарифи не з'являються: прочитайте попередження вгорі сторінки розширення, потім увімкніть Debug log, перезавантажте оформлення замовлення і перегляньте поле Log. Типові причини: немає API-ключа або поштового індексу відправлення, магазин не в USD без USD exchange rate, у адреси доставки ще немає поштового індексу, жоден перевізник вашого облікового запису EasyPost не обслуговує адресу, або Allowed carriers / services відфільтровує всі тарифи.

Тарифи схожі на тестові ціни: задано тестовий ключ (EZTK...). На робочому магазині використовуйте робочий ключ (EZAK...).

Тарифи зупинилися на кілька хвилин: після тайм-ауту, відхиленого ключа або помилки сервера EasyPost розширення призупиняє запити на 5 хвилин і використовує резервні ціни. Перевірте API-ключ і журнал.

Чи включено податок? Тарифи EasyPost не включають податок з продажу. Оберіть податковий клас у Tax class, щоб додати податок до доставки.

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

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

Для розробників: інші розширення можуть змінювати тіло запиту, обраний тариф і базову URL-адресу API за допомогою подій OpenCart vfd_easypost/shipment_request, vfd_easypost/selected_rate і vfd_easypost/api_url.

Видалення

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

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

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