VibeFox Andreani for WooCommerce — Помощь

Требования

WordPress: 5.8 или новее.

WooCommerce: 7.0 или новее, установлен и активен. Без него плагин не активируется.

PHP: 8.0 или новее.

Учётная запись Andreani (только для живых тарифов): живые тарифы используют API расчёта Andreani. Andreani выдаёт бизнес-клиентам учётные данные API, код клиента и номера договоров, обычно при объёме от примерно 300 отправлений в месяц. См. developers.andreani.com или напишите на ventapyme@andreani.com. Нужны имя пользователя и пароль API, код клиента и номер договора. Andreani выдаёт отдельный договор на каждую услугу (доставка на дом, самовывоз из отделения). Без доступа к API используйте фиксированные цены. Выбор отделения работает без учётных данных.

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

Установка

1. В WordPress перейдите в Plugins > Add New > Upload Plugin, выберите ZIP-файл плагина и нажмите Install Now. Также можно загрузить папку vfd_andreani в /wp-content/plugins/ по FTP.

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Shipping > VibeFox Andreani или нажмите Settings под названием плагина на странице «Плагины».

4. Введите лицензионный ключ VibeFox в блоке лицензии вверху страницы и нажмите Activate.

5. Укажите название, источник тарифов, цены по странам (например AR=5000) и, для живых тарифов, учётные данные API, код клиента и номер договора (см. Настройка).

6. Перейдите в WooCommerce > Settings > Shipping > Shipping zones, откройте или создайте зону для Аргентины и добавьте VibeFox Andreani. В окне зоны можно задать заголовок, способ доставки и отдельный договор для этой опции. Также можно включить Ignore shipping zones и выбрать страны.

Настройка

Основные настройки находятся в WooCommerce > Settings > Shipping > VibeFox Andreani. Они действуют для всех зон доставки. Предупреждения о незаполненных настройках (учётные данные API, номер договора, курс обмена, нет цены для Аргентины) выводятся вверху страницы. При каждом сохранении настроек очищаются кэшированный токен, список отделений и тарифы.

Окно зоны (при добавлении способа в зону доставки)

Title: название этой опции на оформлении заказа. Оставьте пустым, чтобы использовать общее Name.

Delivery modality: Use global setting или один из четырёх способов (см. ниже). Добавьте способ в зону дважды, например доставка от двери до двери и самовывоз из отделения, чтобы предлагать оба варианта.

Contract number: договор Andreani для этой опции. Оставьте пустым, чтобы использовать общий договор.

Общие

Enable/Disable: включает или выключает доставку Andreani во всех зонах сразу.

Name: название способа доставки, которое видит покупатель на оформлении заказа. По умолчанию: Andreani.

Tax status: Taxable означает, что WooCommerce добавляет налог к стоимости доставки, поэтому тариф API берётся без IVA. None означает, что тариф API берётся с учётом IVA.

Andreani API (нужен для живых тарифов)

Environment: Sandbox / QA (apisqa.andreani.com) (по умолчанию) или Production (apis.andreani.com). Используйте среду, к которой относятся ваши учётные данные.

API username: имя пользователя API Andreani.

API password: пароль API Andreani.

Client code: код клиента (código de cliente), выданный Andreani, например CL0000000.

Contract number: договор услуги, по которой считаются тарифы, например доставка на дом. Зона может использовать другой договор, например для самовывоза из отделения.

Origin branch code: необязательное отделение отправления (sucursalOrigen) для расчёта тарифов. Оставьте пустым, чтобы использовать отделение, указанное в вашем договоре.

Доставка и тарифы

Delivery modality: первая часть указывает, откуда Andreani забирает посылку (ваш адрес или отделение, куда вы её сдаёте). Вторая часть указывает, где её получает покупатель.

Rate source: как рассчитывается цена.

Country prices: фиксированная цена для каждой страны назначения в валюте магазина, по одной строке на страну в формате CC=PRICE, например AR=5000. Используется в фиксированном режиме и как запасной вариант при сбое API. Строки в другом формате пропускаются, а при сохранении выводится предупреждение со списком таких строк.

ARS exchange rate: Andreani выставляет котировки в аргентинских песо. Нужен, только если валюта вашего магазина не ARS: цена 1 ARS в валюте вашего магазина, например 0.001. Без него тарифы API не используются. Фиксированные цены всегда в валюте магазина.

Default product weight (kg): используется для товаров без веса при запросе тарифов API и проверке ограничений по весу. По умолчанию: 0.5.

Calculation type: Per order берёт цену один раз. Per item (price x number of items) умножает фиксированную цену из Country prices на количество товаров в корзине. Живой тариф Andreani уже рассчитан на всю корзину и не умножается.

Доступность

Min weight (kg): минимальный вес корзины, при котором способ отображается. 0 означает без ограничения.

Max weight (kg): максимальный вес корзины. Если он превышен, способ скрывается. По умолчанию: 100. 0 означает без ограничения.

Minimum subtotal: показывать способ, только если сумма корзины не меньше этой величины. Оставьте пустым, чтобы показывать всегда.

Excluded shipping classes: если хотя бы один товар в корзине относится к выбранному классу доставки WooCommerce, способ скрывается.

Ignore shipping zones: предлагать способ для стран ниже, даже если он не добавлен в зону доставки.

Countries: страны назначения для этого режима. Оставьте пустым, чтобы разрешить все страны. Используется только при включённом Ignore shipping zones.

Бесплатная доставка

Free shipping: включает порог бесплатной доставки.

Free shipping from: сумма корзины, начиная с которой доставка бесплатна. Требует включённого Free shipping.

Выбор отделения на оформлении заказа (показывается для Door to branch и Branch to branch)

Province select width: ширина списка провинций в CSS, например 100% или 300px. По умолчанию: 100%.

Branch select width: ширина списка отделений в CSS, например 100% или 400px. По умолчанию: 100%.

Дополнительно

Debug log: записывает запросы к API и расчёты тарифов в WooCommerce > Status > Logs (источник «vfd-andreani»). Ошибки записываются всегда. Учётные данные и токены никогда не записываются.

Remove data on uninstall: если включено, при удалении плагина удаляются все его настройки и способы в зонах. Деактивация ничего не удаляет. Данные об отделениях, сохранённые в заказах, всегда сохраняются.

Как это работает на оформлении заказа

Когда покупатель вводит адрес доставки, плагин проверяет вес корзины (веса товаров переводятся в кг, для товаров без веса используется Default product weight (kg)), Minimum subtotal и Excluded shipping classes.

В фиксированном режиме цена берётся из Country prices. В живых режимах плагин входит в API Andreani и запрашивает котировку с почтовым индексом назначения, договором, кодом клиента, весом в кг, объёмом по размерам товаров и заявленной стоимостью (сумма корзины в ARS). Живой тариф запрашивается только для корректного аргентинского почтового индекса. Сумма в ARS пересчитывается по курсу ARS exchange rate, если валюта вашего магазина не ARS.

Токен входа кэшируется на 23 часа и автоматически обновляется, если Andreani его отклоняет. Котировки кэшируются на 1 час. Неудачный запрос к API не повторяется в течение 5 минут. Ошибки API никогда не показываются покупателю: способ скрывается или в запасном режиме используется фиксированная цена. Причина записывается в журнал.

Если Free shipping включено и сумма корзины достигает Free shipping from, тариф равен 0. Бесплатная доставка применяется только там, где у способа есть цена: если API Andreani не возвращает тариф (и нет фиксированной цены для запасного варианта), способ не показывается. При Per item фиксированная цена умножается на количество товаров.

Способ работает на классическом оформлении заказа и в блоках «Корзина» и «Оформление заказа». Он совместим с High-Performance Order Storage (HPOS) WooCommerce.

Плагин не создаёт отправления Andreani, не печатает этикетки и не отслеживает посылки. Для этого используйте веб-портал Andreani.

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

При Door to branch или Branch to branch под опцией Andreani на оформлении заказа появляются список провинций и список отделений, как в классическом оформлении заказа, так и в блоке «Оформление заказа». Провинция подставляется по адресу доставки. Список отделений берётся из публичного API отделений Andreani и кэшируется на 12 часов. Отделения, которые не выдают посылки, не показываются. Если отделений нет, покупатель видит сообщение и может выбрать другой способ доставки.

Заказ нельзя оформить без отделения: покупатель видит сообщение Please select an Andreani pickup branch. Это проверяется на сервере для обоих вариантов оформления.

Выбранное отделение сохраняется в заказе. На экране заказа в админ-панели способ и отделение показываются под адресом доставки. Нажмите Edit, чтобы выбрать другую провинцию и отделение. Покупатель видит отделение как Andreani pickup branch на странице заказа и в письмах о заказе (HTML и текстовая версия). Существующие заказы сохраняют данные об отделении.

Лицензионный ключ

Плагин работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии находится вверху страницы WooCommerce > Settings > Shipping > VibeFox Andreani. Вставьте ключ в поле License key и нажмите Activate. В блоке отображается статус, например дата, до которой лицензия действует, и ваш домен. Check now повторно проверяет статус, Change key позволяет ввести другой ключ, а Remove key удаляет ключ с этого сайта. Ссылка Manage licenses and domains in your account открывает ваш аккаунт на vibefox.net.

Один ключ работает на одном домене. Удаление ключа с сайта не освобождает место для домена. Освободите его в своём аккаунте на vibefox.net.

Без активного ключа Andreani не показывается покупателям на оформлении заказа. Менеджеры магазина, которые вошли в систему, по-прежнему его видят, с пометкой (unlicensed — visible to admins only), чтобы вы могли настроить и проверить плагин до покупки ключа. Напоминание появляется на странице «Плагины» и на страницах WooCommerce. Существующие заказы не затрагиваются.

Когда срок лицензии истекает, плагин продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется в фоне повторно.

Решение проблем

Andreani не появляется на оформлении заказа: проверьте, что лицензия активна, что Enable/Disable включено и способ добавлен в зону адреса покупателя (или включено Ignore shipping zones и страна разрешена). Проверьте, что в Country prices есть строка для страны (для фиксированных цен или как запасной вариант), а также ограничения по весу, Minimum subtotal и Excluded shipping classes. Прочитайте предупреждения вверху страницы настроек.

Живые тарифы не появляются: включите Debug log, обновите оформление заказа и откройте WooCommerce > Status > Logs (источник «vfd-andreani»). Там указана причина: нет учётных данных или номера договора, ошибка входа (неверные имя пользователя, пароль или среда), пока нет корректного аргентинского почтового индекса, нет курса обмена или ошибка HTTP от Andreani. При Andreani API, fixed price if the API fails покупатели получают фиксированную цену, пока вы устраняете проблему.

Мой магазин работает не в аргентинских песо: укажите в ARS exchange rate значение 1 ARS в валюте вашего магазина.

Налог на доставку выглядит неправильно: при Tax status = Taxable используется тариф Andreani без IVA, а налог добавляет WooCommerce. При None используется тариф с IVA, и WooCommerce налог не добавляет. Если вы используете Taxable, проверьте, что налоги WooCommerce настроены.

В списке нет отделений: API отделений Andreani не ответил. Неудачный запрос повторяется через 5 минут. Проверьте журнал.

Тарифы выглядят устаревшими после изменения: сохраните страницу настроек. Это очистит кэшированный токен, список отделений и тарифы.

Блок лицензии показывает ошибку: следуйте сообщению в блоке. Например, если ключ уже используется на другом домене, освободите место в аккаунте vibefox.net и нажмите Check now. Если адрес сайта изменился, нажмите Check now, чтобы активировать ключ для нового домена. Если сервер лицензий недоступен, плагин продолжает работать по последнему известному статусу.

Удаление

Деактивация плагина сохраняет все настройки и только очищает кэши. Чтобы удалить плагин, деактивируйте его и удалите на странице Plugins. Лицензионный ключ и статус лицензии этого плагина, а также кэшированные токен, список отделений и тарифы всегда удаляются. Настройки и способы в зонах удаляются, только если была включена опция Remove data on uninstall. Иначе они сохраняются для повторной установки. Данные об отделениях, сохранённые в заказах, никогда не удаляются.

Andreani — товарный знак соответствующего владельца. Этот плагин не связан с Andreani и не одобрен компанией Andreani.