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

Вимоги

PrestaShop: від 8.0 до 9.x.

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

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

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

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

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

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

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

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

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

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

6. За бажанням введіть резервні ціни в таблиці за країнами та вагою, а потім натисніть Save.

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

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox Shippo > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Кожне збереження також очищає кеш тарифів Shippo.

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

Загальні

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

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

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

Обліковий запис 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). Показується найдешевший дозволений тариф. Залиште поле порожнім, щоб показувати найдешевший тариф будь-якого перевізника.

Адреса відправлення (адреса, з якої відправляються ваші посилки; порожні поля заповнюються з адреси магазину в Shop Parameters > Contact > Stores, якщо вона в тій самій країні)

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

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

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

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

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

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 (до 2 кг), M (до 3 кг), L (до 5 кг) та XL (понад 5 кг). Порожній діапазон або 0 використовує колонку Price. Рядок * Default застосовується до країн без власного рядка. Новий рядок створюється як * Default. Рядок, збережений з усіма порожніми клітинками, стягує 0, тож видаляйте рядки, які ви не заповнюєте.

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

Умови

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

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

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

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

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

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

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

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

Додатково

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

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

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

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

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

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

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

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

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

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

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

Замовлення

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Видалення

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

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