VibeFox Servientrega for WooCommerce — Помощь

Требования

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

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

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. Один ключ работает на одном домене.

Установка

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

2. Нажмите Activate.

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

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

5. Для тарифов в реальном времени введите пользователя, пароль и код биллинга, выберите продукт Servientrega, введите код DANE отправления и, если валюта вашего магазина не COP, курс конвертации валюты (см. раздел «Настройка»).

6. При желании добавьте фиксированные цены по стране и весу и резервную стоимость.

7. Добавьте VibeFox Servientrega в зону доставки в WooCommerce > Settings > Shipping > Shipping zones или включите Ignore shipping zones и выберите страны.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Shipping > VibeFox Servientrega. Они действуют во всех зонах доставки. Когда вы добавляете метод в зону, окно зоны содержит только одно поле:

Title (zone): название, которое покупатели видят для этой зоны. Оставьте пустым, чтобы использовать общий Method title.

Каждый раз при сохранении настроек очищаются кэш котировок Servientrega и токен входа. Если тарифы в реальном времени не могут работать с сохраненными настройками, предупреждение над настройками сообщит причину: не указаны пользователь, пароль или код биллинга, не задан курс конвертации или не указан код DANE отправления.

Общие

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

Method title: название способа доставки, которое показывается в корзине и при оформлении заказа. Зона может его переопределить. По умолчанию: Servientrega.

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

User (login): ваш пользователь Servientrega / SISCLINET.

Password: ваш пароль Servientrega / SISCLINET, как вы его вводите. Плагин передает его на шифрование веб-сервису Servientrega перед входом, как это делает официальный клиент Servientrega.

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. Если магазин работает в другой валюте, а это поле пусто, тарифы в реальном времени не используются и действуют фиксированные цены. Плагин не загружает курсы валют. Точка и запятая принимаются как десятичный разделитель.

Отправление из (используется для тарифов в реальном времени)

Origin city (DANE code): 8-значный код DANE муниципалитета отправления, например 11001000 Bogotá, 05001000 Medellín, 76001000 Cali или 08001000 Barranquilla. Принимается и 5-значный код муниципалитета. Если поле пусто, а адрес магазина в WooCommerce > Settings > General находится в Колумбии, используется муниципалитет адреса магазина.

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

Price per country: таблица стран и цен в валюте вашего магазина. Нажмите + Add country, чтобы добавить строку, и крестик, чтобы удалить. Price действует для любого веса. Весовые колонки XS ≤1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg и XL >5 kg заменяют Price для этого веса, если их значение больше 0. Строка * Default действует для всех стран без собственной строки.

Fallback cost: используется, когда нет тарифа в реальном времени и ни одна строка таблицы не подходит. Оставьте пустым, чтобы скрыть метод в этом случае.

Fixed price applies: как начисляются фиксированные цены.

Тарифы Servientrega в реальном времени всегда считаются за отправление.

Условия

Minimum weight (kg): скрывает метод, если корзина весит меньше. 0 — без ограничения.

Maximum weight (kg): скрывает метод, если корзина весит больше. По умолчанию: 50. 0 — без ограничения.

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

Free shipping from: доставка бесплатна, когда промежуточный итог корзины (после скидок, до налогов) достигает этой суммы. Это действует только там, где у метода есть цена: цена из таблицы или резервная стоимость (тогда запрос к Servientrega не отправляется) либо тариф в реальном времени. Оставьте пустым, чтобы никогда не предлагать бесплатную доставку.

Excluded shipping classes: скрывает метод, если в корзине есть товар из любого из этих классов доставки WooCommerce.

Tax status: Taxable добавляет налог WooCommerce к стоимости доставки, None — не добавляет. Котировки Servientrega (ValorTotal) уже включают сборы перевозчика. Выберите None, если не хотите добавлять налог сверху.

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

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

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

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

Debug log: записывает расчеты тарифов и ошибки API в журнал WooCommerce: WooCommerce > Status > Logs, источник vfd_servientrega. Учетные данные, токены и адреса покупателей не записываются. Выключите журнал, когда закончите.

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

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

Когда покупатель вводит адрес доставки, WooCommerce запрашивает у плагина тариф. Плагин сначала проверяет условия: страна доставки, вес корзины, минимальная сумма заказа и исключенные классы доставки. Затем он ищет цену: тариф Servientrega в реальном времени, потом таблицу цен и наконец резервную стоимость. Если цены нет, метод скрывается. Если применяется бесплатная доставка, метод показывается с ценой 0.

Для направления в Колумбии при заданных учетных данных плагин находит код DANE муниципалитета покупателя. Он использует код DANE, введенный как почтовый индекс или в поле города, или сопоставляет департамент и город со встроенной таблицей около 1 130 муниципалитетов. Акценты и «D.C.» игнорируются. Название города, которое есть только в одном департаменте, находится даже без указания департамента.

Затем плагин отправляет в Servientrega одно место на заказ: общий вес, пересчитанный из единиц вашего магазина в кг, и коробку с длиной и шириной самого большого товара и общим объемом всех товаров, пересчитанным в см. Товары без размеров считаются как 10 × 10 × 10 см. Объявленная стоимость — промежуточный итог корзины, пересчитанный в COP, но не менее 6 000 COP. Servientrega возвращает итог в COP, а плагин конвертирует его в валюту вашего магазина.

Токен входа хранится до истечения срока, но не дольше 4 дней. Отклоненный токен автоматически обновляется один раз. Каждая котировка кэшируется на 1 час на маршрут и посылку, поэтому та же корзина не вызывает новый запрос. Неудачный запрос (шифрование, вход или котировка) кэшируется на 10 минут, чтобы оформление заказа не ждало Servientrega при каждом обновлении. Тайм-аут — 10 секунд на запрос.

Если тарифа в реальном времени нет, цена берется из таблицы фиксированных цен, затем из Fallback cost. Если ни то, ни другое не подходит, метод скрывается. Покупатель никогда не видит ошибку API. Причина записывается в журнал отладки.

Метод работает в классическом оформлении заказа и в блоках «Корзина» и «Оформление заказа». Он совместим с WooCommerce High-Performance Order Storage (HPOS). Включены испанские переводы (Колумбия, Испания).

Плагин только рассчитывает тарифы. Он не создает накладные (guías), этикетки или стикеры, не заказывает забор, не отслеживает и не отменяет отправления и не позволяет покупателям выбрать офис Servientrega (Centro de Soluciones). Накладную создайте в SISCLINET или в портале Servientrega. Наложенный платеж (logística de recaudo) не рассчитывается. Актуальные котировки — только для внутренних отправлений внутри Колумбии. Эквадор, Перу, Панама и международные отправления используют фиксированные цены.

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

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

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

Без активного ключа Servientrega не показывается покупателям при оформлении заказа. Администраторы магазина, вошедшие в систему, видят его, помеченным (unlicensed — visible to admins only), чтобы вы могли настроить и протестировать плагин до покупки ключа. Напоминание появляется на странице Plugins и на страницах WooCommerce. Существующие заказы не затрагиваются.

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

Устранение неполадок

Servientrega не появляется при оформлении заказа: проверьте, что лицензия активна, что Enable/Disable включен и метод добавлен в зону страны покупателя (или включен Ignore shipping zones и страна разрешена). Проверьте ограничения веса, Minimum order amount и Excluded shipping classes. Без тарифа в реальном времени проверьте, что для страны или * Default задана цена, или что задана Fallback cost.

Тарифы в реальном времени не появляются: включите Debug log, перезагрузите оформление заказа и откройте WooCommerce > Status > Logs, источник vfd_servientrega. Частые причины: не задан курс конвертации (валюта магазина не COP), нет кода DANE отправления, департамент или город покупателя еще не введены либо не являются известным муниципалитетом, неверные учетные данные или нет покрытия для маршрута. Фиксированные цены покрывают эти случаи, если вы их задали.

Вход не работает: проверьте пользователя, пароль и код биллинга у своего коммерческого консультанта Servientrega. После неудачного входа плагин ждет 10 минут перед следующей попыткой. Сохраните настройки, чтобы повторить сразу.

Город покупателя не распознается: департамент и город сопоставляются со встроенной таблицей DANE. Для редких написаний покупатель может ввести 8-значный код DANE как почтовый индекс. Разработчики могут сопоставить его фильтром vfd_svtg_dane_code.

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

Для разработчиков: фильтры vfd_svtg_quote_request и vfd_svtg_default_dimensions меняют запрос котировки и размеры товаров, у которых их нет. vfd_svtg_api_base и vfd_svtg_soap_url меняют конечные точки, например если Servientrega дает вам другой сервер.

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

Удаление

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

Servientrega — товарный знак его правообладателя. Этот плагин не связан с Servientrega и не одобрен ею.