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

Вимоги

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

PHP: 8.0 або новіший.

Обліковий запис Servientrega (лише для актуальних тарифів): актуальні тарифи використовують Cotizador Corporativo Servientrega (API корпоративних котирувань). Вам потрібен корпоративний (кредитний) обліковий запис Servientrega з доступом до нього. Потрібні три дані: користувач, пароль і платіжний код (código de facturación, зазвичай починається з SER). Це ваші облікові дані SISCLINET, які видає ваш комерційний консультант Servientrega. Якщо ви використовуєте лише фіксовані ціни, обліковий запис Servientrega не потрібен.

Доступ до сервера (лише для актуальних тарифів): ваш сервер має мати доступ до web.servientrega.com через HTTP на порту 8058 (API котирувань) і порту 8081 (веб-сервіс шифрування паролів).

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

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

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

OpenCart 3

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

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

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

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

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

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

OpenCart 4

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

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

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

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

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

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

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

Якщо актуальні тарифи не можуть працювати із збереженими налаштуваннями, попередження над налаштуваннями пояснить причину: не вказано користувача, пароль або платіжний код, не задано курс конвертації або не задано код DANE відправлення. Попередження також з'являється, якщо в магазині немає вагового класу в кг або класу довжини в см, а його одиниця за замовчуванням не відома розширенню; тоді ваги читаються як кг, а розміри як см. Під час збереження значення, яке не є числом, від'ємне число, курс конвертації 0, мінімальна вага більша за максимальну, неправильна ціна в таблиці, порожня назва способу, назва довша за 64 символи або з символами < > ; = # { }, або порядок сортування, який не є цілим числом, відхиляється з помилкою, і нічого не зберігається.

Загальні

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

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

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

API Servientrega (актуальні тарифи для Колумбії) (необов'язково; без облікових даних використовуються лише фіксовані ціни)

User (login): ваш користувач Servientrega / SISCLINET. Його очищення також видаляє збережений пароль.

Password: ваш пароль Servientrega / SISCLINET, як ви його вводите. Розширення передає його веб-сервісу Servientrega для шифрування перед входом. Після збереження поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Billing code: платіжний код (código de facturación) вашого облікового запису Servientrega, як він відображається в SISCLINET. Зазвичай починається з SER.

Усі три поля потрібні для актуальних тарифів. Актуальні тарифи запитуються лише для напрямків у Колумбії. Для інших країн використовуються фіксовані ціни.

Servientrega product: послуга з вашої угоди з Servientrega, за якою запитується котирування.

Оплачувана вага — більша з фактичної та об'ємної ваги.

Currency conversion rate: Servientrega рахує в COP. Якщо валюта за замовчуванням вашого магазину не COP, введіть значення 1 COP у валюті вашого магазину, наприклад 0.00023. Оголошена вартість посилки конвертується в COP так само. Якщо валюта вашого магазину — COP, поле повідомляє, що конвертація не потрібна: залиште його порожнім. Якщо ваш магазин використовує іншу валюту, а це поле порожнє, актуальні тарифи не використовуються і діють фіксовані ціни. Розширення не отримує курси валют. Крапка та кома приймаються як десятковий роздільник.

Ship from (використовується для актуальних тарифів)

Origin city (DANE code): 8-значний код DANE муніципалітету, з якого ви відправляєте, наприклад 11001000 Bogotá, 05001000 Medellín, 76001000 Cali або 08001000 Barranquilla. Приймається також 5-значний код муніципалітету. Адреса магазину в OpenCart — це вільний текст, тож відправлення ніколи не береться з неї: без цього поля актуальних тарифів не буде.

Fixed prices (використовуються, коли немає актуального тарифу: немає облікових даних, напрямок поза Колумбією, невідомий муніципалітет, відсутній курс конвертації, помилка API або немає покриття для маршруту)

Price per country: таблиця країн і цін у валюті за замовчуванням вашого магазину, без податку. Натисніть Add country, щоб додати рядок, і кнопку видалення, щоб видалити рядок. Price діє для будь-якої ваги. Стовпці ваги XS (до 1 кг), S (1–2 кг), M (2–3 кг), L (3–5 кг) і XL (понад 5 кг) замінюють її для цієї ваги, якщо вони більші за 0. Рядок * Default діє для всіх країн без власного рядка. Новий рядок починається як * Default. Рядок без жодної ціни не зберігається.

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

Fixed price applies: як стягуються фіксовані ціни.

Актуальні тарифи Servientrega завжди розраховуються за відправлення.

Conditions

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

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

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

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

Tax class: податковий клас вартості доставки або No tax (за замовчуванням). Котирування Servientrega (ValorTotal) вже включають збори перевізника. Оберіть No tax, якщо не хочете додавати податок зверху.

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

Availability without geo zone

Зазвичай спосіб пропонується в геозоні, вибраній у Conditions, або всюди.

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

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

Advanced

Debug log: записує розрахунки тарифів і помилки API у storage/logs/vfd_svtg_debug.log.php. Файл неможливо прочитати з веб. Облікові дані, токени та адреси покупців не записуються. Коли журнал вимкнено, нічого не записується, включно з помилками API. Коли файл досягає 5 МБ, його переносять до vfd_svtg_debug.old.log.php і починають новий журнал. Вимкніть журнал, коли закінчите.

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

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

Import / Export

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

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

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

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

Для напрямку в Колумбії з налаштованими обліковими даними розширення знаходить код DANE муніципалітету покупця. Воно використовує код DANE, введений у полі поштового індексу або міста, або зіставляє департамент і місто із вбудованою таблицею близько 1 130 муніципалітетів. Департамент — це Region / State адреси: в OpenCart вже є всі 33 департаменти Колумбії. Наголоси та «D.C.» ігноруються. Місто, яке існує лише в одному департаменті, знаходиться навіть без вказання департаменту.

Далі розширення надсилає до Servientrega одне місце на замовлення: загальна вага, переведена з вагового класу товару в кг, і коробка з довжиною та шириною найбільшого товару та загальним об'ємом усіх товарів, переведеним у см. Товари без розмірів вважаються як 10 × 10 × 10 см. Оголошена вартість — це сума замовлення, переведена в COP, але не менше 6 000 COP. Servientrega повертає підсумок у COP. Розширення перераховує його у валюту за замовчуванням вашого магазину і округлює до її десяткових знаків. Покупець бачить ціну у своїй валюті з податком обраного Tax class.

Токен входу зберігається до закінчення строку, але не більше 4 днів. Відхилений токен один раз оновлюється автоматично. Кожне котирування кешується на 1 годину для маршруту та посилки, тож той самий кошик не викликає новий запит. Невдалий запит (шифрування, вхід або котирування) кешується на 10 хвилин, щоб оформлення замовлення не чекало Servientrega під час кожного оновлення. Тайм-аут становить 10 секунд на запит.

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

Розширення лише розраховує тарифи. Воно не створює накладні (guías), етикетки чи наклейки, не замовляє забір посилок, не відстежує і не скасовує відправлення і не дозволяє покупцеві вибрати відділення Servientrega (Centro de Soluciones). Створіть накладну в SISCLINET або у вашому порталі Servientrega. Накладений платіж (logística de recaudo) не розраховується. Актуальні котирування стосуються лише внутрішніх відправлень у межах Колумбії. Розширення нічого не додає до замовлень: замовлення показує назву способу та вартість доставки, як і будь-який інший спосіб доставки OpenCart.

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

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

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

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

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

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

Servientrega не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і що Enable Servientrega увімкнено. Перевірте Geo zone або увімкніть Ignore shipping zones і перевірте Countries. Перевірте обмеження ваги та Minimum order amount. Без актуального тарифу перевірте, що в країни або * Default є ціна, або що задано Fallback cost. Перевірте, що в товарів Requires Shipping встановлено Yes.

Актуальні тарифи не з'являються: увімкніть Debug log, перезавантажте оформлення замовлення і подивіться поле Log на сторінці розширення. Типові причини: відсутній курс конвертації (валюта магазину не COP), немає коду DANE відправлення, департамент або місто покупця ще не введено чи не є відомим муніципалітетом, неправильні облікові дані, немає покриття для маршруту або сервер не може дістатися до web.servientrega.com через порти 8058 і 8081. Фіксовані ціни покривають ці випадки, якщо ви їх налаштували.

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

Місто покупця не розпізнається: покупець має вибрати департамент у полі Region / State. Для рідкісних написань покупець може ввести 8-значний код DANE замість поштового індексу.

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

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

Для розробників: події OpenCart vfd_servientrega/dane_code і vfd_servientrega/quote_request дозволяють іншому розширенню змінити код DANE призначення та запит котирування.

Видалення

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

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

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