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

Вимоги

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

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

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

Товари: товари мають містити вагу і, бажано, розміри.

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

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

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

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

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

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

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

Під час встановлення модуль створює перевізника EasyPost Shipping з текстом строку доставки Live carrier rate (EasyPost). Перевізник призначається всім зонам і всім групам покупців. Зони, групи покупців, строк доставки, логотип і обмеження розмірів можна змінити в Shipping > Carriers. Ціни там не встановлюйте: ціна завжди береться з модуля.

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

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

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

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

Загальні

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

Name: назва перевізника, яку бачить покупець під час оформлення замовлення, не більше 64 символів (довша назва відхиляється, і нічого не зберігається). За замовчуванням: EasyPost Shipping. Якщо назва порожня або містить символи, які PrestaShop не допускає в назві перевізника, використовується назва за замовчуванням.

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

API key: ваш ключ API EasyPost з розділу EasyPost Dashboard > Account Settings > API Keys. Виробничий ключ (починається з EZAK) повертає реальні тарифи. Тестовий ключ (починається з EZTK) повертає тестові тарифи EasyPost; використовуйте його лише для перевірки. Після збереження поле залишається порожнім і показує збережений ключ у замаскованому вигляді, наприклад EZAK******abcd. Залиште поле порожнім, щоб зберегти ключ. Вводьте нове значення, лише щоб його змінити.

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

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

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

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

Sender name / company: ім'я відправника або назва компанії.

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

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

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

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

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

Тарифи

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

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

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

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

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

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

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

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

Умови

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

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

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

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

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

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

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

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

Додатково

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

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

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

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

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

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

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

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

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

Замовлення

Коли оформлюється замовлення з перевізником EasyPost, тариф, показаний під час оформлення, зберігається разом із замовленням. Сторінка замовлення в бек-офісі показує блок 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. Тарифи покинутих кошиків видаляються через 30 днів.

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

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

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

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

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

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

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

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

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

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

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

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

Хуки для розробників: хуки actionVfdEpShipmentRequest (тіло запиту), actionVfdEpSelectedRate (обраний тариф) та actionVfdEpApiUrl (базова URL-адреса API) дозволяють налаштовувати модуль.

Видалення

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

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