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

Вимоги

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

PHP: 8.0 або новіший з розширенням cURL.

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

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

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

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

Після встановлення спосіб доставки вимкнено, доки ви не увімкнете Enable/Disable і не збережете налаштування. Якщо ви встановите розширення знову після видалення, використовуватимуться збережені налаштування FedEx.

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

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Shipping > VibeFox FedEx > Edit. Розділи перелічено ліворуч. Одна кнопка Save внизу зберігає всю сторінку без перезавантаження. Кожне збереження також очищує кеш токена й тарифів FedEx. Зберігати налаштування можуть лише адміністратори з правом змінювати це розширення.

У верхній частині сторінки розширення показує попередження: заповнено лише частину з трьох облікових даних API, немає ключів API та фіксованих цін (тоді спосіб доставки не показується ніколи), не вказано індекс відправлення, не вказано штат відправлення для США або Канади, валюта магазину без курсу обміну для тарифів у валюті облікового запису FedEx, одиниця ваги, яку розширення не розпізнає, коли немає класу ваги в кілограмах (додайте його в System > Localisation > Weight Classes), або, за наявності розміру коробки, одиниця довжини, яку воно не розпізнає. Числові поля приймають крапку або кому як десятковий роздільник. Під час збереження неправильні число або розмір коробки, курс обміну 0, валюта облікового запису, що не є тризначним кодом, некоректна назва або порядок сортування повідомляються і не зберігаються; поле зберігає попереднє значення, а інші поля зберігаються (The other settings were saved.). Мінімальна вага більша за максимальну також повідомляється, і обидві ваги зберігають попередні значення.

Загальні

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

Enable/Disable: вмикає або вимикає доставку FedEx під час оформлення замовлення. За замовчуванням: вимкнено.

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

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

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

API FedEx (тарифи в реальному часі)

Розділ містить посилання на портал розробників FedEx. Без ключів використовуються фіксовані ціни.

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

API Key: API Key (client_id) вашого проєкту в порталі розробників FedEx. Очищення цього поля також видаляє збережений Secret Key.

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

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

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

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

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

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

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

Cache: кнопка Clear cached FedEx token and rates миттєво очищує кеш. Токени FedEx кешуються до закінчення строку дії, тарифи — на 1 годину, а невдалі запити — на 5–10 хвилин.

Ship from

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

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

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

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

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

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

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

Country prices: список країн призначення та цін у валюті магазину за замовчуванням, без податків. Натисніть Add row, щоб додати рядок, і кнопку × — щоб його видалити. Виберіть * Any other country для ціни, яка застосовується до кожної країни без власного рядка. Рядки без коректної країни або ціни ігноруються і повідомляються під час збереження.

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

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

Умови

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

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

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

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

Default product weight (kg): вага, яка використовується для товарів без ваги, для тарифів FedEx і для обмежень ваги вище. За замовчуванням: 0.5; порожнє поле також означає 0.5 кг. Ваги товарів переводяться з класу ваги кожного товару.

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

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

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

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

Додатково

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

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

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

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

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

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

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

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

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

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

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

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

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

Замовлення

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

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

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

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

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

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

FedEx не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і Enable/Disable увімкнено. Перевірте Geo zone або Ignore shipping zones і Countries. Перевірте попередження у верхній частині сторінки розширення, обмеження ваги та Minimum subtotal. Без тарифу в реальному часі спосіб доставки потребує ціни за країною, рядка * Any other country або Fallback cost. Перевірте, що товари мають Requires Shipping, встановлений у Yes.

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

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

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

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

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

Для розробників: інші розширення можуть змінити адресу API, дозволені послуги FedEx і запит тарифу через події OpenCart vfd_fedex/api_base_url, vfd_fedex/allowed_services і vfd_fedex/rate_request (реєструються як catalog/vfd_fedex/...); налаштування vfd_fdx_api_url замінює адресу API для тестів і не має поля на сторінці налаштувань.

Видалення

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

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

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