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, введите, сколько единиц вашей валюты стоит один 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.