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

Вимоги

PrestaShop: 8.0–9.x.

PHP: 8.0 або новіша версія. Модуль не встановлюється на старіших версіях PHP.

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

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

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

1. У бек-офісі перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

2. Коли завантаження завершиться, натисніть Configure або пізніше знайдіть VibeFox ShipStation у списку модулів і натисніть Configure.

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

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

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

6. За бажанням заповніть резервні ціни.

Під час встановлення модуль створює перевізника ShipStation Shipping із текстом строку доставки ShipStation carriers (USPS, UPS, FedEx, ...). Перевізник призначається всім зонам і всім групам клієнтів. Зони, групи клієнтів, строк доставки, логотип і обмеження розміру можна змінити в Shipping > Carriers. Не задавайте там ціни: ціна завжди береться з модуля.

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox ShipStation > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Кожне збереження очищує кеш тарифів ShipStation і перевіряє API Key та API Secret. Далі сторінка показує перевізників, підключених до вашого облікового запису, з їхніми кодами, наприклад «stamps_com (Stamps.com), ups_walleted (UPS by ShipStation)».

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

Загальні

Enable ShipStation shipping: вмикає або вимикає перевізника. Це той самий перемикач, що й статус перевізника в Shipping > Carriers.

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

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

Обліковий запис 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: обов'язковий для актуальних тарифів. ShipStation розраховує тариф лише за поштовим індексом, і він має знаходитися в країні вашого облікового запису ShipStation. Залиште порожнім, щоб використати поштовий індекс магазину з Shop Parameters > Contact > Stores.

Тарифи

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

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

Умови

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

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

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

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

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

Зазвичай перевізник пропонується у своїх зонах у Shipping > Carriers. Також він може пропонуватися за країнами.

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

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

Додатково

Debug log: записує запити до ShipStation у logs/vfd_shst_debug.log.php у папці модуля. Файл не можна відкрити з веб-браузера. Помилки API завжди записуються, навіть коли цю опцію вимкнено. API Key, API Secret та адреси клієнтів ніколи не записуються в журнал. Поштовий індекс маскується.

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

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

Робота під час оформлення замовлення

На кроці доставки PrestaShop запитує у модуля ціну. Враховуються лише фізичні товари: віртуальні товари не додають ваги і не входять до суми кошика. Модуль спочатку перевіряє умови: дозволені країни (з Ignore shipping zones), вага кошика та мінімальна сума. Якщо діє безкоштовна доставка, перевізник показується з ціною 0, і запит до ShipStation не надсилається.

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

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

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

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

Якщо ви редагуєте перевізника в Shipping > Carriers після того, як у нього є замовлення, PrestaShop зберігає його як нову версію перевізника. Модуль автоматично слідує за новою версією.

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

Замовлення

Коли замовлення оформлюється з актуальним тарифом ShipStation, обрана служба зберігається разом із замовленням. Сторінка замовлення в бек-офісі показує її в блоці ShipStation як Service, наприклад «USPS Ground Advantage - Package», щоб ви могли створити відповідну етикетку в ShipStation. Подальші перерахунки кошика її не змінюють. Замовлення, оформлені з резервною ціною або безкоштовною доставкою, не мають блоку служби.

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

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox ShipStation є першим блоком на сторінці Modules > Module Manager > VibeFox ShipStation > Configure, над налаштуваннями. Введіть ключ у поле License key і натисніть Activate. Після цього блок показує ключ приховано, статус (наприклад, дату, до якої дійсна ліцензія, і ваш домен) та кнопки Check now, щоб перевірити статус знову, Change key, щоб ввести інший ключ, і Remove key, щоб видалити ключ із цього магазину. Нижче розташовані рядок Product: presta-shipping-shipstation і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише співробітники з правом Configure для модуля. Тексти блоку відповідають мові бек-офісу (включено англійську та російську).

Якщо ключ не прийнято, блок повідомляє причину, наприклад Key not found, This key belongs to another product, Domain limit reached або License expired on з датою. Після зміни адреси магазину або після звільнення слота домену у вашому обліковому записі натисніть Check now. Якщо сервер ліцензій недоступний, модуль продовжує працювати за останнім відомим статусом.

Один ключ працює на одному домені: домені основного магазину, також у багатомагазинній конфігурації. Видалення ключа з магазину не звільняє слот домену. Звільніть його у своєму обліковому записі vibefox.net.

Без активного ключа перевізник ShipStation не показується покупцям під час оформлення замовлення, і тариф не розраховується. Вітрина PrestaShop не знає, що ви увійшли в бек-офіс, тому перевізник приховано і для вас: ви можете налаштувати модуль до купівлі ключа, але не можете перевірити його під час оформлення замовлення. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються.

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

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

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

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

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

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

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

На сторінці написано, що перевізника ShipStation не знайдено: перевізника видалено в Shipping > Carriers. Скиньте модуль у Modules > Module Manager, щоб створити його знову.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox ShipStation і виберіть Uninstall. Ліцензійний ключ і статус ліцензії завжди видаляються. Кеш тарифів і результат перевірки з'єднання завжди видаляються. Якщо Remove data on uninstall увімкнено, перевізника видаляють (замовлення зберігають свою історію), а налаштування, журнал і службу, збережену із замовленнями, видаляють. Якщо вимкнено, перевізника лише вимикають, а налаштування та службу вже оформлених замовлень зберігають. Повторне встановлення модуля або Reset повертає перевізникові той статус, який був раніше.

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