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

Вимоги

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

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

Договір із Correios (лише для тарифів у реальному часі): тарифи в реальному часі використовують API тарифів Correios Web Services (CWS) і потребують облікових даних договору з Correios, у якому є картка відправлення. Потрібні три значення: ваш користувач Meu Correios (зазвичай CNPJ або CPF договору), код доступу до API та номер картки відправлення. Код доступу створюється в порталі Correios Web Services (cws.correios.com.br; для тестового середовища — cwshom.correios.com.br). Також потрібен CEP, з якого ви відправляєте. Без облікових даних розширення працює лише з фіксованими тарифами.

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

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

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

OpenCart 3

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

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

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

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

5. Введіть користувача API Correios, код доступу, номер картки відправлення, CEP відправлення та послугу. Якщо валюта за замовчуванням вашого магазину не BRL, введіть курс до BRL. Заповніть фіксовані тарифи для інших країн і як резервний варіант (див. Конфігурація), увімкніть Enable Correios і натисніть Save.

OpenCart 4

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

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

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

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

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

Конфігурація

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

Сторінка показує попередження, коли тарифи в реальному часі або спосіб доставки не можуть працювати: заповнені не всі три облікові дані, не вказано CEP відправлення, немає курсу до BRL для магазину з іншою валютою або немає ані облікових даних, ані фіксованих тарифів. Кожне попередження повідомляє, чи використовуються тим часом фіксовані тарифи або спосіб доставки приховано. Попередження також з'являється, якщо в магазині немає класу ваги з одиницею kg або класу довжини з одиницею cm; тоді одиниці товарів перераховуються за назвою одиниці їхнього класу (невідомі одиниці вважаються kg або cm). Перевірте System > Localisation > Weight Classes і Length Classes.

Збереження відхиляється з повідомленням, якщо назва способу доставки порожня або недопустима (не більше 64 символів, без < > ; = # { }), якщо числове поле чи тариф у Country prices не є числом 0 або більше, якщо курс до BRL дорівнює 0, якщо Min cart weight більше за Max cart weight, якщо CEP відправлення має не 8 цифр, якщо код іншої послуги має більше 5 цифр або якщо Sort order не є цілим числом. Нічого не зберігається, доки ви не виправите значення.

Загальні

Налаштування застосовуються до всіх географічних зон. Ви можете обмежити спосіб доставки географічною зоною в Conditions або списком країн за допомогою Ignore shipping zones.

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

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

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

API Correios (тарифи в реальному часі в Бразилії)

Для адрес у Бразилії вартість береться з API тарифів Correios. Якщо API не повертає вартість (API недоступний, CEP не обслуговується, посилка завелика), використовується фіксований тариф із Country prices, а якщо його немає, спосіб доставки приховується. Деталі помилок потрапляють до журналу і ніколи не показуються покупцеві.

API user: ваш логін у порталі Meu Correios, зазвичай CNPJ або CPF договору. Очищення також видаляє збережений код доступу.

Access code: код доступу до API (código de acesso), створений у порталі Correios Web Services. Це не пароль від порталу. Після збереження поле залишається порожнім і показує Saved — leave empty to keep it (empty the API user as well to remove it). Вводьте нове значення, лише якщо хочете його змінити. Щоб видалити збережений код, очистіть API user і збережіть.

Posting card: номер картки відправлення (cartão de postagem) вашого договору: 10 цифр, зазвичай починається з двох нулів, наприклад 0012345678. Коротші номери доповнюються нулями зліва. Номер можна перевірити на сторінці Correios Fácil на сайті Correios.

Homologation: використовує тестове середовище Correios (homologation): запити надсилаються на apihom.correios.com.br з кодом доступу для тестів. Вимкніть на робочому магазині.

Origin CEP: CEP (8 цифр), з якого відправляються посилки, наприклад 01001-000.

Service: послуга Correios, за якою розраховується вартість під час оформлення замовлення. Роздрібні коди: PAC (04510, за замовчуванням), SEDEX (04014), SEDEX 12 (04782), SEDEX 10 (04790), SEDEX Hoje (04804). Договірні коди: PAC (03298), SEDEX (03220), SEDEX 12 (03140), SEDEX 10 (03158), SEDEX Hoje (03204), Correios Mini Envios (04227). Договірним кодам потрібна картка відправлення договору, до якого входить ця послуга.

Other service code: необов'язково, 5-значний код послуги вашого договору, якого немає в списку, наприклад 03085. Коротший код доповнюється нулями зліва. Якщо його заповнено, він використовується замість Service.

Package format: тип відправлення, що передається в Correios.

Default product weight (kg): передається в Correios для кожного товару без ваги. За замовчуванням: 0.3. Ваги та розміри товарів перераховуються з їхніх класів ваги й довжини, а кошик розраховується як одна посилка.

BRL → store currency rate: у назві поля показано валюту магазину за замовчуванням, наприклад BRL → EUR rate. Тарифи Correios вказані в BRL. Якщо валюта за замовчуванням не BRL, введіть, скільки одиниць вашої валюти коштує один BRL, наприклад 0.17. Без цього значення тарифи в реальному часі не використовуються. Курс має бути більшим за 0. Якщо валюта за замовчуванням — BRL, залиште поле порожнім.

Фіксовані тарифи (використовуються для країн поза Бразилією, без облікових даних API і як резервний варіант, коли API не повертає вартість)

Country prices: таблиця країн із базовим тарифом Base і тарифами залежно від ваги кошика у валюті магазину за замовчуванням, без податку: XS до 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL понад 5 kg. Порожній або нульовий тариф розміру використовує базовий тариф Base. Натисніть Add country, щоб додати рядок, і кнопку ×, щоб видалити його. Рядок * All other countries задає тарифи для всіх країн без власного рядка. Країна без рядка (і без *) не отримує фіксованого тарифу. У рядку має бути хоча б один тариф. Базовий тариф 0 означає безкоштовну доставку для цієї країни.

Fixed price per: Order (за замовчуванням) стягує тариф один раз. Item (price × quantity) множить його на кількість товарів у кошику. Це стосується лише фіксованих тарифів. Тарифи в реальному часі завжди розраховуються для всієї посилки.

Умови

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

Max cart weight (kg): приховує спосіб доставки, якщо кошик важчий за це значення. За замовчуванням: 30. 0 означає без обмеження, порожнє поле означає 30 kg. Посилки Correios PAC і SEDEX можуть важити до 30 kg.

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

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

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

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

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

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

Зазвичай спосіб доставки пропонується в географічній зоні, вибраній у Conditions (у всіх зонах, якщо жодну не вибрано).

Ignore shipping zones: пропонувати спосіб доставки для країн, вказаних нижче, незалежно від того, яка географічна зона відповідає. Geo zone у Conditions тоді не перевіряється.

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

Додатково

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

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

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

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

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

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

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

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

Для адреси в Бразилії із заданими обліковими даними розширення спочатку отримує токен API для вашої картки відправлення. Токен також містить номери договору та регіонального відділення, тож вартість — це вартість вашого договору. Потім запитується вартість обраної послуги за CEP відправлення та призначення, вагою посилки в грамах і розміром посилки в см. Вартість запитується лише тоді, коли CEP призначення має 8 цифр. Якщо всі товари мають розміри, розмір посилки оцінюється за ними; інакше надсилається мінімальний розмір Correios. Посилки понад 30 kg до API не надсилаються. Вартість у BRL конвертується за вашим курсом. Вартість розраховується у валюті магазину за замовчуванням, округлюється до її десяткових знаків і показується покупцеві у його валюті з податком обраного Tax class.

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

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

Розширення лише розраховує тарифи. Воно не отримує міжнародні тарифи Correios (Exporta Fácil, Packet), оцінки термінів доставки, етикетки, попередні відправлення, декларації чи відстеження. Покупці не можуть обрати відділення або поштомат Correios. Додаткові послуги (оголошена цінність, вручення особисто, повідомлення про вручення) не додаються. Розширення показує одну послугу Correios на магазин, а курси валют автоматично не оновлюються.

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

Замовлення

Коли замовлення оформлено з Correios, розширення зберігає, як було розраховано його вартість доставки. Сторінка замовлення в Sales > Orders тоді показує блок Correios з Correios service (наприклад PAC — contract (03298)) і Price: Live price (Correios API), Fixed price або Free shipping. Блок показується лише в адмін-панелі, а не в листах покупцям, і залишається видимим, коли розширення вимкнено.

В OpenCart 4 оформлення замовлення створює одне замовлення і оновлює його, коли покупець підтверджує знову. Дані Correios замовлення оновлюються разом із ним, а якщо покупець обирає інший спосіб доставки, блок Correios для цього замовлення більше не показується.

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

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

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

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

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

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

Спосіб доставки показує фіксований тариф замість тарифу Correios: подивіться поле Log на сторінці розширення. Там записуються помилки Correios: неправильний код доступу, послуга не входить до вашого договору, CEP не обслуговується, посилка понад 30 kg або перевищує обмеження розміру. Також перевірте, чи задано CEP відправлення, чи має CEP покупця 8 цифр і, якщо валюта за замовчуванням не BRL, курс до BRL. Увімкніть Debug log, щоб бачити кожен розрахунок.

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

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

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

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

Видалення

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

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

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