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

Вимоги

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

PHP: 8.0 або новіша версія.

Обліковий запис електронної комерції CTT (лише для тарифів у реальному часі та пунктів CTT): тарифи в реальному часі та доставка до пункту CTT використовують API електронної комерції CTT. Вам потрібен обліковий запис електронної комерції CTT на enviosecommerce.ctt.pt (для клієнтів з договором CTT Expresso або запитайте пропозицію у CTT). На сторінці керування ключами цього облікового запису створіть пару ключів: відкритий і закритий. App ID (X-APPID) видає CTT для вашої інтеграції: уточніть його у свого контакту з електронної комерції CTT. CTT також визначає, які функції API (оцінка вартості, пункти CTT) може використовувати ваш App ID. Нарешті, вам потрібен Carrier ID CTT у вашому обліковому записі. Сторінка налаштувань показує перевізників вашого облікового запису після збереження ключів. Якщо ви використовуєте лише таблицю тарифів і доставку за адресою, API-ключі не потрібні.

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

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

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

OpenCart 3

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

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

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

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

5. Заповніть таблицю тарифів (принаймні рядок Portugal або * Default), увімкніть Enable/Disable та/або Enable CTT point option і натисніть Save. За бажанням заповніть API-ключі CTT, App ID і Carrier ID та увімкніть Live rates (див. розділ Налаштування).

OpenCart 4

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

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

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

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

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

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

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

Попередження у верхній частині сторінки повідомляють про порожню таблицю тарифів, відсутній тариф для Португалії, неповні API-ключі, коли увімкнені тарифи в реальному часі або опція пункту CTT, відсутній Carrier ID, валюту магазину, відмінну від EUR, без курсу обміну, невдале підключення до API CTT, а також магазин без класу ваги в кг або класу довжини в см (тоді одиниці товарів перетворюються за назвою одиниці; перевірте System > Localisation > Weight Classes і Length Classes). Якщо назва порожня, некоректна або довша за 64 символи, якщо Min weight (kg) більша за Max weight (kg), або якщо Sort Order, клас податку чи географічна зона некоректні, сторінка показує помилку і нічого не зберігається. Інші некоректні значення подаються як попередження, а решта зберігається: некоректне число не зберігається, курс обміну 0 або менше очищується, некоректний розмір товару скидається до значення за замовчуванням, невідоме призначення або повторюваний рядок у таблиці тарифів видаляється, некоректний тариф у таблиці залишається порожнім.

Загальні

Розширення пропонує під час оформлення замовлення до двох варіантів: доставка CTT за адресою покупця та доставка до пункту CTT або автоматичної шафи. Тарифи та умови застосовуються до обох.

Enable/Disable: вмикає або вимикає доставку CTT за адресою покупця.

Name: назва способу доставки, яку бачить покупець під час оформлення замовлення, наприклад «CTT Expresso». За замовчуванням: CTT. До 64 символів.

Tax class: клас податку на вартість доставки. OpenCart додає цей податок (наприклад, IVA) до тарифів. --- None --- означає, що тарифи остаточні. Використовується обома варіантами.

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

Доставка до пункту CTT або автоматичної шафи

Другий варіант CTT. Покупець шукає пункти CTT за поштовим індексом або містом (адреса доставки шукається автоматично) і має обрати один, перш ніж продовжити. Потрібні API-ключі CTT і Carrier ID. Без них це варіант без вибору пункту.

Enable CTT point option: пропонує доставку до пункту CTT або автоматичної шафи. За замовчуванням: вимкнено.

CTT point option name: назва цього варіанта під час оформлення замовлення. За замовчуванням: CTT point / parcel locker. До 64 символів.

API електронної комерції CTT (тарифи в реальному часі, пункти CTT) (необов'язково; без ключів використовується таблиця тарифів)

Public key: відкритий ключ зі сторінки керування ключами вашого облікового запису електронної комерції CTT.

Private key: секретний ключ, яким підписується кожен запит (HMAC-SHA256). Він ніколи не надсилається в CTT і не записується в журнал.

Обидва ключі після збереження більше не відображаються. Тоді опис поля каже Saved - leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити. Позначте Remove the saved public and private key і збережіть, щоб видалити обидва. Коли нічого не збережено, розділ показує No keys saved.

App ID (X-APPID): ключ застосунку, виданий CTT, надсилається в заголовку X-APPID.

Carrier ID: ідентифікатор перевізника CTT у вашому обліковому записі, використовується для тарифів у реальному часі та пошуку пунктів CTT. Після збереження ключів і App ID перевізники вашого облікового запису перелічуються під полем (Carriers of your CTT account:), а ті, що підтримують пункти CTT, позначені CTT points. Лише цифри.

Live rates: запитує в CTT вартість (оцінку) щойно покупець введе вулицю, поштовий індекс і місто. Таблиця тарифів використовується, поки адреса неповна, і щоразу, коли CTT не повертає вартість. CTT називає цю вартість оцінкою. За замовчуванням: вимкнено.

Service ID: необов'язково. Якщо CTT повертає кілька послуг, використовується та, що має цей ServiceId. Залиште порожнім, щоб використовувати найдешевшу.

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

Default product size (cm): довжина x ширина x висота, що надсилаються в CTT для товарів без розмірів. За замовчуванням: 30x20x15. Товари з розмірами використовують власні. Розміри переводяться в см, а ваги в грами за класами довжини та ваги товарів.

Тарифи (у заголовку розділу показано основну валюту вашого магазину)

Введіть тарифи за вашим договором із CTT або з публічного прайс-листа CTT на ctt.pt, в основній валюті магазину, без податків. Коли тарифи в реальному часі вимкнені, ця таблиця визначає ціну. Коли вони увімкнені, таблиця є запасним варіантом.

Price table: один рядок на призначення. Виберіть країну, Portugal - Azores, Portugal - Madeira або * Default (other destinations). Кожен рядок має базову Price і необов'язкові ціни для розмірів XS (до 1 кг), S (до 2 кг), M (до 3 кг), L (до 5 кг) і XL (понад 5 кг). Порожня (або нульова) ціна розміру використовує базову ціну. Рядок, у якому обидві ціни порожні, приховує спосіб доставки. Рядок Azores застосовується для португальських поштових індексів 9500-9999, рядок Madeira для 9000-9499. Без них застосовується рядок Portugal. Натисніть Add destination, щоб додати рядок, і кнопку × — щоб видалити. Ціни приймають крапку або кому як десятковий роздільник. Таблиця порожня після встановлення.

Calculation: як визначається ціна з таблиці.

Тариф CTT у реальному часі завжди стосується всього відправлення.

Умови

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

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

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

Безкоштовна доставка

Free shipping: вмикає безкоштовну доставку CTT від суми, вказаної нижче.

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

Доступність

Зазвичай варіанти CTT пропонуються в географічній зоні, вибраній нижче. All Zones означає всюди. З Ignore shipping zones географічна зона не перевіряється, і вирішують Countries.

Geo Zone: географічна зона адреси доставки. Географічні зони керуються в System > Localisation > Geo Zones.

Ignore shipping zones: не перевіряти географічну зону; пропонувати CTT у країнах, зазначених нижче.

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

Додатково

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

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

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

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

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

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

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

Коли OpenCart показує способи доставки, він запитує в розширення вартість CTT. З Ignore shipping zones CTT пропонується лише для країни з Countries (порожньо = усі країни); інакше, якщо задано Geo Zone, лише для адрес у її межах. Враховуються лише товари з Requires Shipping, встановленим у Yes: інші товари не додають ваги й не входять до суми замовлення. Розширення перевіряє вагу кошика та мінімальну суму замовлення. З увімкненими Live rates і повною адресою воно надсилає в CTT адресу доставки та для кожного рядка кошика кількість, вагу в грамах і розміри в см, а потім використовує повернуту вартість. Інакше або коли CTT не повертає вартість (помилка API, тайм-аут, відсутнє покриття, функція не увімкнена для вашого App ID), вартість береться з таблиці. Якщо застосовується безкоштовна доставка, вартість дорівнює 0. Обидва варіанти отримують однакову вартість. Вартість розраховується в основній валюті магазину, округлюється за його десятковими знаками та показується покупцю в його валюті з податком обраного Tax class.

Вартість CTT кешується на 1 годину, тож той самий кошик не викликає новий запит. Невдалий запит запам'ятовується на 5 хвилин, щоб оформлення замовлення не чекало CTT під час кожного оновлення. API-токен, список перевізників і списки пунктів CTT також кешуються, але не довше, ніж триває життя кешу OpenCart (за замовчуванням 1 година). Помилки API ніколи не доходять до покупця: використовується вартість із таблиці, або спосіб доставки приховується, якщо для призначення немає ціни.

Коли API-ключі заповнені, розширення надсилає в CTT адресу доставки, ваги та розміри товарів і URL вашого магазину, щоб отримати вартість або найближчі пункти CTT.

Розширення не створює відправлень, не друкує етикетки, не замовляє забір, не надає номери для відстеження та не показує карту пунктів CTT. Для обох варіантів існує одна таблиця тарифів і один набір API-налаштувань.

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

Пункти видачі

Коли покупець обирає варіант пункту CTT на кроці способу доставки, під ним з'являються поле пошуку та список. Поштовий індекс адреси доставки заповнюється та шукається автоматично. Покупець може шукати інші пункти CTT за поштовим індексом або містом (кнопка Search) і вибрати один зі списку. Вибір зберігається одразу. Приймається лише пункт зі списку CTT для цього пошуку.

Перед тим як продовжити, покупець має обрати пункт. Коли покупець натискає Continue, розширення перевіряє пункт на сервері. Без пункту покупець бачить Please select a CTT point., а з пунктом, якого немає у списку CTT, — The selected CTT point is not in the CTT list for this search. Please choose the CTT point again. Якщо CTT недоступний, покупець бачить CTT points cannot be loaded right now. Please try again in a few minutes or choose another shipping method.

Вибір пункту активний лише тоді, коли заповнені відкритий ключ, закритий ключ, App ID і Carrier ID. Він розрахований на стандартну тему OpenCart та її оформлення замовлення; іншим темам можуть знадобитися зміни.

В OpenCart 4 поле пошуку та список з'являються у вікні Shipping method options, під варіантом пункту CTT. Кнопка Continue у вікні не переходить далі без дійсного пункту, з тими самими повідомленнями. OpenCart 4 зберігає одне замовлення для оформлення і оновлює його щоразу, коли покупець підтверджує знову, а пункт CTT замовлення оновлюється разом з ним.

Обраний пункт додається до способу доставки замовлення, наприклад CTT point / parcel locker: .... Тож покупець бачить його в історії замовлень свого облікового запису та в листах про замовлення, а також пункт друкується на рахунку і відображається в Sales > Orders. Сторінка успішного оформлення замовлення OpenCart спосіб доставки не показує.

На сторінці замовлення в адмінпанелі панель CTT point над історією показує назву та ID пункту. Щоб його змінити, введіть поштовий індекс або місто в полі Change CTT point, натисніть Search, оберіть пункт і натисніть Save. Сторінка покаже CTT point updated., текст способу доставки замовлення оновиться, а в історію додасться запис CTT point changed to: ... без сповіщення покупця. Зміна пункту потребує права змінювати замовлення (sale/order) і API-налаштувань. Панель показується й для замовлень CTT, поки розширення вимкнено.

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

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

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

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

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

CTT не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і увімкнено Enable/Disable (або Enable CTT point option). Перевірте Geo Zone або Ignore shipping zones і Countries. Перевірте, що для призначення є рядок у таблиці тарифів (або рядок * Default), вага кошика в межах Min weight і Max weight, досягнута Minimum order amount і в товарів Requires Shipping встановлено Yes.

Покупець не може вибрати пункт CTT: вибір з'являється лише під варіантом пункту CTT і лише коли заповнені відкритий ключ, закритий ключ, App ID і Carrier ID. Перевірте попередження у верхній частині сторінки налаштувань, увімкніть Debug log і подивіться поле Log на сторінці розширення.

Тарифи в реальному часі не з'являються: таблиця тарифів використовується, доки покупець не введе вулицю, поштовий індекс і місто. Перевірте попередження та журнал. Відповідь «405» означає, що функція не увімкнена для вашого App ID: запитайте в CTT. У магазині не в євро заповніть Exchange rate.

Не вдалося підключитися до API CTT: попередження у верхній частині сторінки налаштувань показує помилку. Перевірте ключі та App ID. Розширення автоматично повторить спробу через кілька хвилин.

Ціни з ПДВ чи без ПДВ: з обраним Tax class OpenCart додає цей податок до ціни. З --- None --- ціна остаточна.

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

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

Для розробників: адресу API CTT можна замінити налаштуванням vfd_ctt_api_url (для тестів); на сторінці налаштувань для нього немає поля.

Видалення

Перейдіть до Extensions > Extensions, оберіть тип Shipping і натисніть Uninstall (червона кнопка −) поруч із VibeFox CTT. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди скидає статус розширення, Sort Order, Tax class і Geo Zone. Закешовані відповіді CTT і API-токен завжди видаляються. Якщо Remove data on uninstall увімкнено, також видаляються налаштування, журнал і пункти CTT незавершених оформлень, які так і не стали замовленнями. Якщо вимкнено, інші налаштування зберігаються і знову використовуються під час повторного встановлення розширення. Пункти CTT, збережені в замовленнях, завжди залишаються, а наявні замовлення зберігають свій спосіб доставки та вартість.

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

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