VibeFox Correios for WooCommerce — Допомога
Вимоги
WordPress: 5.8 або новіша.
WooCommerce: 5.0 або новіша, встановлений і активний. Плагін не активується без нього.
PHP: 8.0 або новіша.
Договір Correios (лише для актуальних тарифів): актуальні тарифи використовують API тарифів Correios Web Services (CWS) і потребують облікових даних договору Correios з posting card. Потрібні три значення: ваш логін Meu Correios (зазвичай CNPJ або CPF за договором), код доступу API і номер posting card. Код доступу створюється в порталі Correios Web Services (cws.correios.com.br; для homologação — cwshom.correios.com.br). Також потрібен CEP, з якого ви відправляєте. Без облікових даних плагін працює лише з фіксованими тарифами.
Ліцензійний ключ VibeFox: купується на vibefox.net. Один ключ працює на одному домені.
Встановлення
1. У WordPress перейдіть до Plugins > Add New > Upload Plugin, виберіть ZIP-файл плагіна і натисніть Install Now. Також можна завантажити папку vfd_correios до /wp-content/plugins/ через FTP.
2. Натисніть Activate.
3. Відкрийте налаштування: WooCommerce > Settings > Shipping > VibeFox Correios або натисніть Settings під назвою плагіна на сторінці Plugins.
4. Введіть ліцензійний ключ VibeFox у блоці ліцензії у верхній частині сторінки і натисніть Activate.
5. Введіть користувача API Correios, код доступу, номер posting card, CEP відправлення та послугу. Якщо валюта вашого магазину не BRL, введіть курс до BRL. Заповніть фіксовані тарифи для інших країн і як запасний варіант (див. Налаштування).
6. Додайте VibeFox Correios до зони доставки в WooCommerce > Settings > Shipping > Shipping zones або увімкніть Ignore shipping zones і оберіть країни.
Налаштування
Усі налаштування розташовані на одній сторінці: WooCommerce > Settings > Shipping > VibeFox Correios. Вони діють для всіх зон доставки. Коли ви додаєте метод до зони, вікно зони містить лише одне поле:
Title (zone): назва, яку бачить покупець для цієї зони. Залиште порожнім, щоб використовувати загальний Method title.
Сторінка налаштувань показує попередження, коли актуальні тарифи або метод не можуть працювати: заповнені лише деякі з трьох облікових даних, не вказано CEP відправлення, не задано курс BRL для магазину в іншій валюті, або немає ні облікових даних, ні фіксованих тарифів. Під час кожного збереження налаштувань очищаються кешовані тарифи і токен API. Числа можна вводити з крапкою або з комою.
Загальні
Enable/Disable: вмикає або вимикає метод у всіх зонах одночасно.
Method title: назва способу доставки, яка показується в кошику і на оформленні замовлення. За замовчуванням: Correios. Зона може замінити її власним заголовком.
Tax status: Taxable додає податок WooCommerce до вартості доставки, None — не додає.
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. Це не пароль від порталу.
Posting card: номер posting card (cartão de postagem) вашого договору: 10 цифр, зазвичай починається з двох нулів, наприклад 0012345678. Коротші номери доповнюються нулями зліва. Номер можна перевірити на сторінці Correios Fácil на сайті Correios.
Homologation: використовує тестове середовище Correios (homologação) з кодом доступу homologação. Вимикайте на робочому магазині.
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). Договірні коди потребують posting card договору, до якого входить ця послуга.
Other service code: необов'язково, 5-значний код послуги вашого договору, якого немає у списку, наприклад 03085. Якщо поле заповнене, код використовується замість Service.
Package format: тип об'єкта, що відправляється до Correios.
Default product weight (kg): відправляється до Correios для кожного товару без ваги. Default: 0.3. Вага і розміри товарів перераховуються з одиниць вашого магазину, а кошик тарифікується як одна посилка.
BRL → store currency rate: у назві поля показано валюту вашого магазину. Тарифи Correios вказані в BRL. Якщо валюта магазину не BRL, введіть, скільки одиниць вашої валюти коштує 1 BRL, наприклад 0.17. Без цього курсу актуальні тарифи не використовуються. Якщо валюта вашого магазину BRL, залиште поле порожнім.
Фіксовані тарифи (для країн поза межами Бразилії, без облікових даних API і як запасний варіант, якщо API не повертає ціну)
Country prices: таблиця країн із базовою ціною Base і цінами залежно від ваги кошика у валюті вашого магазину: XS до 1 кг, S 1–2 кг, M 2–3 кг, L 3–5 кг, XL понад 5 кг. Порожня або нульова ціна розміру використовує базову ціну Base. Натисніть Add country, щоб додати рядок, і хрестик, щоб його видалити. Рядок * Default (all other countries) задає ціни для всіх країн без власного рядка. Країна без рядка (і без *) не отримує фіксованого тарифу. Базова ціна 0 означає безкоштовну доставку до цієї країни.
Fixed price per: Order стягує ціну один раз. Item (price × quantity) множить її на кількість товарів у кошику. Це стосується лише фіксованих тарифів. Актуальні тарифи завжди розраховуються для всієї посилки.
Умови
Min cart weight (kg): приховує метод при вазі кошика нижче цього значення. 0 означає без обмеження.
Max cart weight (kg): приховує метод при вазі кошика вище цього значення. За замовчуванням: 30. 0 означає без обмеження. Посилки Correios PAC і SEDEX можуть важити до 30 кг.
Minimum order amount: показувати метод лише тоді, коли проміжна сума кошика досягає цього значення. Залиште порожнім, щоб показувати завжди.
Excluded shipping classes: приховує метод, якщо в кошику є товар з одним із цих класів доставки WooCommerce.
Free shipping: вмикає безкоштовну доставку від суми, вказаної нижче.
Free shipping from: проміжна сума кошика, починаючи з якої доставка безкоштовна. У цьому разі запит до API не надсилається.
Доступність без зон доставки
Ignore shipping zones: пропонує метод для країн, вказаних нижче, незалежно від того, яка зона підходить.
Countries: країни призначення для цього режиму. Залиште порожнім, щоб використовувати всі країни, куди магазин доставляє. Це поле використовується лише коли ввімкнено Ignore shipping zones.
Додатково
Debug log: записує розрахунки тарифів у WooCommerce > Status > Logs, джерело vfd-correios. Помилки API записуються завжди, навіть коли ця опція вимкнена. Користувач API, код доступу, posting card, токен і CEP покупців не записуються.
Remove data on uninstall: якщо увімкнено, видалення плагіна видаляє його налаштування, методи зон і кешовані тарифи. Деактивація плагіна нічого не видаляє.
Як це працює на оформленні замовлення
Коли покупець вводить адресу доставки, WooCommerce запитує у плагіна тариф. Плагін спочатку перевіряє умови: вагу кошика, мінімальну суму замовлення і виключені класи доставки. Якщо діє безкоштовна доставка, покупець отримує тариф 0, і запит до Correios не надсилається.
Для адреси в Бразилії із заданими обліковими даними плагін спочатку отримує токен API для вашої posting card. Токен також повертає номери договору та регіонального відділення, тож ціна є ціною вашого договору. Потім плагін запитує ціну обраної послуги за CEP відправлення і призначення, вагою посилки в грамах і розмірами посилки в см. Ціна запитується, лише якщо CEP призначення містить 8 цифр. Якщо всі товари мають розміри, розмір посилки оцінюється за ними; інакше надсилається мінімальний розмір Correios. Посилки понад 30 кг до API не надсилаються. Ціна в BRL конвертується за вашим курсом. Послуга зберігається з рядком доставки замовлення як Correios service і видна в адмінці замовлення.
Кожна ціна кешується на 1 годину для кожної посилки. Невдалий запит кешується на 10 хвилин, щоб збій API не сповільнював кожне оновлення оформлення замовлення. Токен кешується до незадовго до закінчення терміну дії й оновлюється автоматично; якщо Correios його відхиляє, запитується новий токен і запит ціни повторюється один раз. Тайм-аут API становить 12 секунд.
Якщо API не повертає ціну, використовується фіксований тариф, а якщо його немає, метод приховується. Покупець ніколи не бачить подробиць помилок API; вони потрапляють до журналу WooCommerce.
Метод працює на класичному оформленні замовлення та в блоках Кошик і Оформлення замовлення. Він сумісний з WooCommerce High-Performance Order Storage (HPOS).
Плагін лише розраховує тарифи. Він не отримує міжнародні тарифи Correios (Exporta Fácil, Packet), оцінки строків доставки, етикетки, попередні відправлення, декларації чи відстеження. Покупці не можуть обрати відділення або поштомат Correios. Додаткові послуги (оголошена цінність, вручення особисто, повідомлення про вручення) не додаються. У магазині показується одна послуга Correios, а курси валют не оновлюються автоматично.
Ліцензійний ключ
Плагін працює з ліцензійним ключем VibeFox із vibefox.net. Блок ліцензії розташований угорі сторінки WooCommerce > Settings > Shipping > VibeFox Correios. Вставте ключ у License key і натисніть Activate. Блок показує статус, наприклад дату, до якої ліцензія активна, і ваш домен. Використовуйте Check now, щоб перевірити статус знову, Change key, щоб ввести інший ключ, і Remove key, щоб видалити його з цього сайту. Посилання Manage licenses and domains in your account відкриває ваш обліковий запис vibefox.net.
Один ключ працює на одному домені. Видалення ключа з сайту не звільняє слот домену. Звільніть слот в обліковому записі vibefox.net.
Без активного ключа Correios не показується покупцям на оформленні замовлення. Адміністратори магазину, які увійшли в систему, бачать його, позначений як (unlicensed — visible to admins only), щоб ви могли налаштувати й протестувати плагін до покупки ключа. Нагадування з'являється на сторінці Plugins і на сторінках WooCommerce. Наявні замовлення не змінюються.
Коли ліцензія закінчується, плагін продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус автоматично перевіряється знову у фоновому режимі.
Усунення несправностей
Correios не з'являється на оформленні замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено і метод доданий до зони країни покупця (або увімкнено Ignore shipping zones і країна дозволена). Перевірте обмеження ваги, Minimum order amount і Excluded shipping classes. Без актуального тарифу має бути фіксований тариф для країни або для *.
Метод показує фіксований тариф замість тарифу Correios: відкрийте WooCommerce > Status > Logs, джерело vfd-correios. Там записано помилку Correios: неправильний код доступу, послуги немає у вашому договорі, CEP не обслуговується, посилка понад 30 кг або понад обмеження розміру. Також перевірте, чи заданий CEP відправлення і, якщо валюта магазину не BRL, курс BRL. Увімкніть Debug log, щоб бачити кожен розрахунок.
Запит токена завершується помилкою: перевірте користувача API, код доступу, posting card і середовище. Код доступу homologação працює лише з увімкненою опцією Homologation, а продуктивний код — лише з вимкненою.
Тарифи виглядають застарілими після зміни: збережіть сторінку налаштувань. Це очистить кешовані тарифи і токен API.
Блок ліцензії показує помилку: дотримуйтеся повідомлення в блоці. Наприклад, якщо ключ уже використовується на іншому домені, звільніть слот в обліковому записі vibefox.net і натисніть Check now. Якщо адреса сайту змінилася, натисніть Check now, щоб активувати ключ для нового домену. Якщо сервер ліцензій недоступний, плагін продовжує працювати з останнім відомим статусом.
Видалення
Деактивація плагіна зберігає всі дані. Щоб видалити його, деактивуйте і видаліть на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна завжди видаляються. Налаштування, методи зон і кешовані тарифи видаляються, лише якщо була увімкнена опція Remove data on uninstall. Інакше вони зберігаються для повторного встановлення. Замовлення ніколи не змінюються.
Correios — торговельна марка її власника. Цей плагін не афілійований із Correios і не схвалений Correios.