VibeFox Correos CityPaq for WooCommerce — Помощь

Требования

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

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

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

Учётные данные API Correos (только для актуального списка постаматов): список CityPaq от Correos читает активные постаматы через API «terminals» Correos. На портале разработчиков Correos откройте API «terminals» и нажмите Request access для вашего приложения. Correos одобряет запросы своих корпоративных клиентов и присылает client ID и client secret. Они также показаны в разделе My applications на портале. Если покупатели вводят постамат сами или выбирают из вашего списка, учётные данные API не нужны.

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

Установка

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

2. Нажмите Activate.

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

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

5. Заполните таблицу цен и выберите, как покупатель выбирает постамат (см. раздел «Настройка»).

6. Добавьте VibeFox Correos CityPaq в зону доставки для Испании в WooCommerce > Settings > Shipping > Shipping zones или включите Ignore shipping zones.

Настройка

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

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

Предупреждения над настройками сообщают, когда в таблице цен нет ни одной пригодной строки, когда выбранный способ выбора постамата не может работать (нет постаматов в вашем списке, нет учётных данных API) и какой была последняя ошибка API Correos. Цены и суммы принимают десятичную запятую или десятичную точку.

Общие

Постаматы CityPaq есть только в Испании, поэтому способ никогда не предлагается для других стран.

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

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

Tax status: Taxable добавляет налог WooCommerce к ценам из таблицы, None не добавляет.

Цены (в заголовке раздела указана валюта вашего магазина)

Price table: строка для Spain (ES) и/или строка по умолчанию *. Каждая строка содержит базовую Price и необязательные цены для размеров посылок XS (до 1 кг), S (до 2 кг), M (до 3 кг), L (до 5 кг) и XL (больше 5 кг). Цена размера 0 или пустая использует базовую цену. Нажмите + Add row, чтобы добавить строку, и крестик, чтобы удалить её. Вводите тарифы по вашему договору с Correos в валюте магазина. Без подходящей строки способ скрыт. Некорректные цены и повторяющиеся строки сообщаются при сохранении.

Calculation type: как определяется размер посылки.

Per order (size by the total cart weight): одна цена на всю корзину, выбирается по общему весу. Это значение по умолчанию.

Per item (size by each item weight, multiplied by quantity): каждый товар получает цену своего размера, умноженную на количество, и цены складываются.

Веса товаров переводятся в кг из единицы веса вашего магазина (кг, г, фунты или унции).

Условия

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

Max weight (kg): скрывает способ, когда корзина тяжелее. По умолчанию: 30, так как CityPaq принимает посылки до 30 кг. 0 означает без ограничения.

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

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

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

Free shipping: включает бесплатную доставку CityPaq от суммы ниже.

Free shipping from: подытог корзины (после скидок, до налогов), начиная с которого этот способ стоит 0. Используется, только когда включена опция Free shipping.

Выбор постамата CityPaq

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

Customer chooses from the Correos CityPaq list (Correos API, credentials below): покупатель видит активные постаматы CityPaq по почтовому индексу адреса доставки и может искать другой 5-значный почтовый индекс. Если для индекса нет постамата, показываются постаматы той же местности, затем той же провинции, сначала с ближайшими почтовыми индексами. Каждый постамат показывает название, адрес, почтовый индекс, город и часы работы. Если список не загружается или ничего не находит, покупатель вводит постамат вручную.

Customer enters the locker (code or address from the Correos finder): обязательное поле для кода постамата (например, S0000213D) или адреса, со ссылкой на официальный поиск постаматов Correos CityPaq.

Customer chooses from my list of lockers (below): обязательный выпадающий список постаматов из My lockers. Постаматы рядом с почтовым индексом покупателя показываются первыми.

Do not ask for a locker: вопрос о постамате при оформлении не задаётся.

Если вы выбираете список Correos без учётных данных API или свой список, когда My lockers пуст, покупателю предлагается ввести постамат вручную.

My lockers: используется, когда Locker selection установлен на ваш список. Один постамат в строке: CODE | Name | Address | Postal code | City. Код и название обязательны. Некорректные и повторяющиеся строки сообщаются при сохранении.

Список Correos CityPaq (API) (используется только со списком Correos CityPaq)

В разделе есть ссылка на страницу API «terminals» на портале разработчиков Correos. Читается только список постаматов. Цены всегда берутся из таблицы цен.

API client ID: client_id вашего приложения на портале разработчиков Correos.

API client secret: client_secret вашего приложения на портале разработчиков Correos.

При изменении учётных данных или выбора постамата кэшированные списки постаматов очищаются.

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

Ignore shipping zones: предлагает CityPaq для любого испанского адреса, даже если ни одна зона доставки не содержит этот способ. Выключено (рекомендуется) означает, что способ предлагается там, где вы добавили его в зону доставки.

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

Debug log: пишет строки отладки в WooCommerce > Status > Logs, источник vfd-correos-citypaq. Ошибки API Correos записываются всегда, даже когда опция выключена. Учётные данные и персональные данные никогда не записываются.

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

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

Когда покупатель вводит адрес доставки в Испании, WooCommerce запрашивает у плагина тариф. Плагин проверяет вес корзины, минимальную сумму заказа и исключённые классы доставки, находит строку цен для Испании (или строку *) и размер посылки и показывает цену. Если действует бесплатная доставка, цена равна 0.

Когда покупатель выбирает CityPaq, поле постамата появляется под способом. Заказ нельзя оформить без корректного постамата. Это также проверяется на сервере, в том числе для заказов, оформленных через блоки корзины и оформления заказа. Со списком Correos код постамата принимается, только если Correos предложил его этому покупателю, а название и адрес берутся из Correos. Число поисков по почтовому индексу за сеанс покупателя ограничено. Когда лимит достигнут, покупатель вводит постамат вручную.

Список Correos кэшируется на 12 часов для каждого почтового индекса. Неудачный запрос кэшируется на 10 минут, чтобы оформление заказа не ждало Correos при каждом обновлении. Таймаут API — 12 секунд. Покупатель никогда не видит техническую ошибку, только короткое сообщение и поле для ручного ввода.

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

Плагин не получает актуальные тарифы от Correos, не показывает карту, не регистрирует отправления заранее, не печатает этикетки, не заказывает заборы посылок и не отслеживает посылки. Создайте отправление в своём аккаунте Correos, используя постамат, сохранённый в заказе.

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

Выбранный постамат сохраняется в заказе. Он показывается в административной части заказа под адресом доставки, на странице «Заказ получен», в My account > Orders и во всех письмах о заказе (HTML и текстовых) как CityPaq locker.

В административной части заказа можно изменить постамат в поле Change CityPaq locker: выбрать другой постамат из вашего списка или ввести новый код или адрес. Со списком Correos введённый код постамата проверяется в Correos. Оставьте поле пустым, чтобы сохранить текущий постамат. Каждое изменение добавляет примечание к заказу.

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

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

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

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

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

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

Correos CityPaq не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено, адрес находится в Испании, а способ добавлен в соответствующую зону доставки (или включено Ignore shipping zones). Проверьте, есть ли в таблице цен строка для Испании или строка *, и что корзина укладывается в ограничения по весу, Minimum order amount и Excluded shipping classes.

Покупатели должны вводить постамат, хотя выбран список Correos: проверьте, что заполнены API client ID и API client secret, и посмотрите предупреждение над настройками. Оно показывает последнюю ошибку API Correos. HTTP 401/403 означает, что Correos отклонил учётные данные: проверьте их и убедитесь, что ваше приложение имеет доступ к API «terminals». После ошибки следующая попытка выполняется через 10 минут.

Нет постаматов для почтового индекса: Correos не нашёл активного постамата для этого индекса, его местности или провинции. Покупатель может поискать другой почтовый индекс или ввести постамат, найденный в поиске CityPaq на сайте Correos.

Выпадающий список моих постаматов не появляется: My lockers пуст или его строки некорректны. Каждая строка должна содержать как минимум CODE | Name.

Где покупатели находят код постамата: в поиске CityPaq на сайте Correos, ссылка на который находится под полем постамата.

Заметки для разработчиков: постамат сохраняется в метаданных заказа _vfd_cpq_locker (текст, который показывается везде) и _vfd_cpq_locker_id (код постамата, когда он выбран из списка Correos или вашего списка). Плагин использует рабочий API «terminals» Correos. Песочница (sandbox) для этого API не описана в документации.

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

Удаление

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

Correos и CityPaq — товарные знаки их владельцев. Этот плагин не связан с Correos и не одобрен ею.