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

Вимоги

PrestaShop: 8.0–9.x.

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

Обліковий запис FedEx і ключі API (лише для актуальних тарифів): у FedEx Developer Portal (developer.fedex.com) створіть проєкт з Rate API, прив'яжіть свій обліковий запис доставки FedEx і скопіюйте API Key та Secret Key. Також знадобиться 9-значний номер облікового запису FedEx. Тестові ключі працюють лише з увімкненим Sandbox, ключі production — лише з вимкненим. Модуль використовує REST API FedEx з OAuth 2.0; йому не потрібні meter number і пароль веб-служб. Якщо ви використовуєте лише фіксовані ціни, ключі FedEx не потрібні.

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

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

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

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

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

4. Введіть API Key, Secret Key, 9-значний номер облікового запису FedEx і адресу Ship from (поштовий індекс і, для США та Канади, 2-літерний код штату). Вимкніть Sandbox, якщо використовуєте ключі production. За бажанням введіть фіксовані ціни як резерв. Натисніть Save.

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

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

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

Угорі сторінки модуль показує попередження: заповнені лише деякі з трьох облікових даних API; немає ключів API та фіксованих цін (тоді перевізник ніколи не показується); не вказано поштовий індекс відправлення; не вказано код штату відправлення для США або Канади; валюта магазину відрізняється від валюти облікового запису FedEx без курсу обміну; одиниця ваги магазину (або, з розміром коробки, одиниця розміру) модулем не підтримується; або перевізника видалено. Числові поля приймають крапку або кому як десятковий роздільник. Некоректне число чи розмір коробки, курс обміну 0, код валюти облікового запису, що не є 3-літерним кодом, і назва довша за 64 символи не зберігаються та повідомляються як помилка; поле зберігає попереднє значення, інші поля зберігаються. Також повідомляється, якщо мінімальна вага більша за максимальну; обидві ваги зберігають попередні значення.

Загальні

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

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

Tax status: податкове правило перевізника або No tax. З податковим правилом (і з увімкненими податками в магазині) PrestaShop додає податок до вартості доставки, тому використовується вартість FedEx без податків. З No tax чиста вартість FedEx використовується без змін.

API FedEx (актуальні тарифи)

Без ключів використовуються фіксовані ціни, наведені нижче. У розділі є кнопка Clear cached FedEx token and rates.

Sandbox: використовує пісочницю FedEx (apis-sandbox.fedex.com) з тестовими ключами. Вимкніть її для реальних тарифів (apis.fedex.com) з ключами production. За замовчуванням: увімкнено.

API Key: API Key (client_id) вашого проєкту у FedEx Developer Portal.

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

FedEx account number: 9-значний номер облікового запису доставки FedEx, пов'язаного з проєктом. Для нього розраховуються тарифи облікового запису (погоджені).

Rates: Account rates (your negotiated FedEx prices) (за замовчуванням) або List rates (FedEx published prices).

Residential delivery: розраховувати адреси клієнтів як житлові (FedEx Home Delivery, надбавка за доставку на житлову адресу). Вимкніть, якщо ви відправляєте переважно організаціям. За замовчуванням: увімкнено.

Box size: необов'язкові розміри коробки в одиницях розміру вашого магазину, наприклад 30x20x15. Тоді FedEx застосовує об'ємну вагу. Залиште поле порожнім, щоб рахувати лише за вагою.

FedEx account currency: валюта вашого облікового запису FedEx, наприклад USD для американських облікових записів або CAD для Канади. За замовчуванням: USD. FedEx також завжди просять розрахувати вартість у валюті за замовчуванням магазину.

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

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

Адреса, з якої FedEx забирає посилки або на яку ви їх здаєте. Використовується для актуальних тарифів.

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

State / province code: 2-літерний код, обов'язковий для США та Канади, наприклад TN, CA або ON.

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

ZIP / postal code: поштовий індекс відправлення. FedEx потребує його для розрахунку тарифів.

Фіксовані ціни

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

Country prices: таблиця кодів країн призначення з 2 літер і цін у валюті за замовчуванням вашого магазину, без податків. Натисніть Add row, щоб додати країну, і значок кошика, щоб видалити її. Використовуйте * як код країни для всіх інших країн. Рядки, які не містять коду країни (або *) з ціною, ігноруються і повідомляються під час збереження.

Fallback cost: фіксована ціна, коли жодна ціна для країни не підходить. Залиште порожнім, щоб приховати перевізника.

Fixed price is: Per order стягує ціну один раз. Per item (price x number of items) множить її на кількість товарів у кошику. Це стосується лише фіксованих цін. Актуальні тарифи FedEx завжди розраховуються для загальної ваги кошика.

Умови

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

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

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

Max weight: максимальна вага кошика в кг. Якщо її перевищено, перевізника приховано. 0 означає без обмеження.

Default product weight: вага в кг для товарів без ваги, для тарифів FedEx і для обмежень за вагою, наведених вище. За замовчуванням: 0.5. Ваги товарів перераховуються з одиниці ваги вашого магазину (кг, г, фунти або унції), яку задано в International > Localization (Local units).

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

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

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

Додатково

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

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

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

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

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

Інакше модуль отримує токен OAuth і надсилає до Rate API FedEx адресу відправлення, адресу доставки, вагу кошика (у кг або, для магазинів з фунтами чи унціями, у фунтах), розмір коробки, якщо його задано, і вашу валюту за замовчуванням як бажану валюту. Для країн, які потребують поштового індексу, запит надсилається лише після того, як покупець його ввів. Для міжнародних відправлень передається митна вартість кошика. Коди штатів надсилаються лише для США та Канади.

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

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

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

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

Замовлення

На сторінці замовлення в бекофісі замовлення з перевізником FedEx мають блок FedEx shipping. У ньому показано FedEx service тарифу (для актуальних тарифів), Price source (FedEx live rate, Fixed price (no live rate) або Free shipping threshold) і Calculated price (excl. tax) у вашій валюті за замовчуванням. Значення фіксуються під час оформлення замовлення: подальші зміни налаштувань їх не змінюють.

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

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

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

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

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

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

Актуальні тарифи не з'являються: увімкніть Debug log, перезавантажте оформлення замовлення та перегляньте поле Log на сторінці модуля. Там записуються неправильні ключі, хибне середовище (тестові ключі з вимкненим Sandbox або ключі production з увімкненим), відсутній поштовий індекс доставки та коди помилок FedEx.

Мій магазин не в USD: FedEx просять розрахувати тариф у валюті за замовчуванням вашого магазину. Якщо ваш обліковий запис повертає лише власну валюту, вкажіть FedEx account currency і Exchange rate. Без курсу обміну такі тарифи ігноруються і використовується фіксована ціна, тож сума в USD ніколи не показується в гривнях.

Чи множить «Per item» тариф FedEx? Ні. Per item застосовується лише до фіксованих цін.

Тарифи виглядають застарілими після зміни: збереження сторінки модуля очищає кеш. Також можна натиснути Clear cached FedEx token and rates.

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

Слід пропонувати лише деякі служби: розробники можуть обмежити служби за допомогою хука actionVfdFdxAllowedServices. Хуки actionVfdFdxRateRequest та actionVfdFdxApiBaseUrl змінюють запит тарифу та адресу API.

Видалення

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

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