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

Вимоги

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

PHP: 8.0 або новіша.

Обліковий запис ShipStation: підключіть перевізників у ShipStation (Settings > Shipping > Carriers), потім скопіюйте API Key та API Secret у розділі ShipStation > Settings > Account > API Settings. Доступ до API залежить від вашого тарифного плану ShipStation. Розширення використовує ShipStation API V1 (API Key та API Secret). Без ключів використовуються лише резервні ціни.

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

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

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

OpenCart 3

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

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

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

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

5. Вставте API Key та API Secret, вкажіть поштовий індекс відправлення і натисніть Save. Сторінка тепер виведе коди перевізників вашого облікового запису. Введіть потрібний(і) у полі Carrier codes і збережіть ще раз.

6. Якщо валюта магазину за замовчуванням не збігається з валютою вашого облікового запису ShipStation, задайте Exchange rate. За бажанням заповніть резервні ціни.

7. Увімкніть Enable ShipStation shipping і натисніть Save.

OpenCart 4

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

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

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

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

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

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

Усі налаштування знаходяться на сторінці розширення: Extensions > Extensions > Shipping > VibeFox ShipStation > Edit. Розділи перелічено ліворуч. Одна кнопка Save зберігає всю сторінку без перезавантаження. Кожне збереження очищує кеш тарифів ShipStation і перевіряє API Key та API Secret. Потім сторінка показує перевізників, підключених до вашого облікового запису, з їхніми кодами, наприклад "stamps_com (Stamps.com), ups_walleted (UPS by ShipStation)". Зберігати налаштування можуть лише адміністратори з правом змінювати це розширення.

Попередження у верхній частині сторінки повідомляють, коли тарифи в реальному часі не можуть працювати: немає ключів, немає коду перевізника, немає поштового індексу відправлення, не задано курс обміну, не пройдено перевірку підключення або коди перевізників не підключені до вашого облікового запису. Попередження також з'являється, якщо одиниця ваги чи довжини магазину не підтримується розширенням для перерахунку. Використовуйте kg, g, lb або oz та cm, mm, m або in (System > Settings > Option). Некоректна назва, числове поле або комірка ціни з від'ємним значенням чи текстом замість числа, Minimum weight, більший за Maximum weight, або порядок сортування, який не є цілим числом, виводяться як помилка, і нічого не зберігається.

Загальні

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

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

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

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

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

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

API Secret: API Secret з тієї самої сторінки. Він зберігається так само, як ключ.

Remove the saved API key and secret: з'являється, коли ключі збережено. Позначте і збережіть, щоб видалити обидва.

Carrier codes: один або кілька кодів перевізників ShipStation, розділених комами, наприклад stamps_com, ups_walleted. Використовується до 5 кодів, з одним запитом до API на перевізника. Якщо ви введете більше, зберігаються лише перші 5, і сторінка повідомить про це. Показується найдешевший тариф цих перевізників. Беріть коди зі списку, який з'явиться після збереження.

Allowed services: необов'язково, коди послуг ShipStation, розділені комами, наприклад usps_priority_mail, ups_ground. Залиште порожнім, щоб показувати найдешевшу послугу перевізників, зазначених вище.

Package code: "package" (за замовчуванням) розраховує тарифи для вашої власної коробки і виключає конверти та коробки з фіксованим тарифом перевізника. Залиште порожнім, щоб розраховувати тарифи для всіх типів упаковки, які пропонує перевізник.

Відправлення з

Ship-from postal code: обов'язковий для тарифів у реальному часі, наприклад 78703. ShipStation розраховує тарифи лише за поштовим індексом, і він має бути в країні вашого облікового запису ShipStation. OpenCart не має поштового індексу магазину, тому він ніколи не береться з адреси магазину.

Тарифи

Parcels: як кошик надсилається до ShipStation.

ShipStation account currency: валюта, у якій ShipStation повертає тарифи: USD, CAD, GBP, AUD, NZD або EUR. За замовчуванням: USD (облікові записи США).

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

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

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

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

Умови

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

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

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

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

Доступність

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

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

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

Додатково

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

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

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

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

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

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

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

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

Далі розширення надсилає до ShipStation поштовий індекс відправлення, країну призначення, код штату, місто та поштовий індекс, вагу посилки і розмір коробки. Запит не робиться, доки покупець не введе поштовий індекс. Країни без поштових індексів отримують резервні ціни. Товари складаються в одну коробку. Якщо товар не має розмірів, посилка розраховується лише за вагою.

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

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

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

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

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

Замовлення

Коли замовлення оформлено з тарифом ShipStation у реальному часі, обрана послуга зберігається разом із замовленням. Відкрийте замовлення в Sales > Orders: панель ShipStation над історією замовлення показує її як Service, наприклад "USPS Ground Advantage - Package", щоб ви могли створити відповідну етикетку в ShipStation. У режимі за товарами послуги перелічуються через кому. Пізніші зміни кошика її не змінюють, і панель показується навіть після вимкнення способу. Замовлення з резервною ціною або безкоштовною доставкою не мають панелі ShipStation.

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

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

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

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

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

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

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

Під час оформлення замовлення показується резервна ціна замість тарифу ShipStation: перегляньте попередження у верхній частині сторінки розширення (ключі, код перевізника, поштовий індекс відправлення, курс обміну). Увімкніть Debug log, перезавантажте сторінку оформлення замовлення та перегляньте поле Log. Поштовий індекс покупця обов'язковий. Запит не робиться, доки його не введено.

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

Перевірка підключення до ShipStation не пройдена: у повідомленні вказано причину. Перевірте API Key та API Secret, потім збережіть ще раз, щоб повторити перевірку.

Тариф відрізняється від тарифу ShipStation: посилка формується за вагою та розмірами товарів, товари складаються в одну коробку. Товари без розмірів розраховуються лише за вагою. Тарифи кешуються на 1 годину. Натисніть Save на сторінці розширення, щоб очистити кеш.

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

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

Видалення

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

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

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