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

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

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

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

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

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

Установка

Загружаемый файл — это один zip-архив с пакетами для обеих версий OpenCart. Распакуйте его на своём компьютере. Он содержит README.txt, пакет для OpenCart 3 vfd_correos_citypaq-oc3-(version).ocmod.zip и пакет для OpenCart 4 vfd_correos_citypaq.ocmod.zip. Устанавливайте только пакет для вашей версии OpenCart. Лицензионный ключ одинаков для обеих версий.

OpenCart 3

1. В админ-панели перейдите в Extensions > Installer, нажмите Upload и выберите файл vfd_correos_citypaq-oc3-(version).ocmod.zip. Расширение не добавляет модификаций OCMOD, поэтому обновлять Extensions > Modifications не нужно. Вместо Installer можно скопировать содержимое папки upload этого пакета в корневую папку магазина.

2. Перейдите в Extensions > Extensions, выберите тип расширения Shipping. Найдите VibeFox Correos CityPaq и нажмите Install (зелёная кнопка +).

3. Нажмите Edit (кнопка с карандашом), чтобы открыть страницу настроек.

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

5. Заполните таблицу цен, выберите, как покупатель выбирает постамат (см. Конфигурация), включите Enable/Disable и нажмите Save.

OpenCart 4

1. В админ-панели перейдите в Extensions > Installer, нажмите Upload и выберите файл vfd_correos_citypaq.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.

2. Пакет появится в списке установленных расширений на той же странице. Нажмите Install (зелёная кнопка +) рядом с ним.

3. Перейдите в Extensions > Extensions и выберите тип расширения Shipping. Найдите VibeFox Correos CityPaq, нажмите Install (зелёная кнопка +), затем Edit (кнопка с карандашом).

4. Введите лицензионный ключ и настройки так же, как в шагах 4 и 5 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях.

После установки способ доставки выключен, пока вы не включите Enable/Disable и не сохраните настройки. Если вы установили расширение заново после удаления, сохранённые настройки снова используются.

Конфигурация

Все настройки находятся на странице расширения: Extensions > Extensions > Shipping > VibeFox Correos CityPaq > Edit. Разделы перечислены слева. Одна кнопка Save внизу сохраняет всю страницу без перезагрузки. Цены и суммы можно вводить с десятичной запятой или точкой. Сохранять настройки может только администратор с правом изменения этого расширения.

Вверху страницы появляются предупреждения: если в таблице цен нет строки для Испании и строки по умолчанию; если выбранный способ выбора постамата не может работать (в вашем списке нет постаматов, нет учётных данных API); о последней ошибке API Correos; а также если в магазине нет класса веса с единицей kg (тогда веса товаров переводятся по названию единицы: kg, g, lb или oz; неизвестные единицы считаются kg). Проверьте System > Localisation > Weight Classes. Если название пустое, недопустимое или длиннее 64 символов, если вес или сумма не является допустимым числом 0 или больше, если Min weight (kg) больше Max weight (kg), или если Sort order не является целым числом, страница показывает ошибку, и ничего не сохраняется. Недопустимые цены в таблице, повторяющиеся строки и недопустимые или повторяющиеся строки в My lockers выводятся как предупреждения, а остальное сохраняется.

Общие

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

Enable/Disable: включает или выключает доставку Correos CityPaq. По умолчанию: выключено.

Name: название способа доставки, которое видит покупатель при оформлении заказа. По умолчанию: Correos CityPaq. Обязательно, не более 64 символов, без < > ; = # { }.

Tax class: OpenCart добавляет налог этого класса к ценам из таблицы. No tax означает, что цены окончательные.

Sort order: место способа доставки в списке способов доставки. Целое число.

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

Correos не публикует API тарифов для CityPaq, поэтому стоимость берётся из этой таблицы. Введите цены вашего договора с Correos в валюте магазина по умолчанию, без налога.

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

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

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

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

Веса товаров переводятся в kg из класса веса каждого товара.

Условия

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

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

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

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

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

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

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

Раздел содержит ссылку на официальный поисковик постаматов CityPaq на сайте Correos.

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

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

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

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

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

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

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

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

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

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

После сохранения оба поля остаются пустыми и показывают Saved - leave empty to keep it. Вводите новое значение, только если хотите его изменить. Отметьте Remove the saved client ID and client secret и нажмите Save, чтобы удалить их. Если ничего не сохранено, раздел показывает No credentials saved. Когда вы меняете учётные данные или выбор постамата, кэшированные списки постаматов и последняя ошибка API очищаются.

Доступность

Geo zone: предлагает способ доставки только для адресов в этой географической зоне. All zones (по умолчанию) означает все адреса в Испании. Географические зоны настраиваются в System > Localisation > Geo Zones.

Ignore geo zone: предлагает CityPaq для всех адресов в Испании, даже если они не входят в географическую зону выше.

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

Debug log: записывает строки отладки в storage/logs/vfd_cpq_debug.log.php (в OpenCart 4 — system/storage/logs/vfd_cpq_debug.log.php). Файл нельзя прочитать из веб-браузера. Ошибки API Correos записываются всегда, даже если эта опция выключена. Учётные данные и персональные данные никогда не записываются.

Log: показывает размер и последние записи журнала. Нажмите Clear log, чтобы очистить его.

Remove data on uninstall: если включено, при удалении расширения удаляются настройки, кэшированные списки и журналы. Постаматы, сохранённые в заказах, остаются. Если выключено (по умолчанию), всё сохраняется для повторной установки.

Импорт / экспорт

Export: нажмите Download JSON, чтобы сохранить настройки в файл JSON. Client ID и secret API в файл не включаются.

Import: вставьте JSON с настройками, экспортированный из этого расширения, и нажмите Import. Значения проверяются так же, как при обычном сохранении. Сохранённые учётные данные остаются.

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

Когда OpenCart показывает способы доставки, он запрашивает у расширения стоимость CityPaq. Если задана Geo zone (и Ignore geo zone выключено) и адрес находится вне неё, CityPaq не предлагается. Учитываются только товары с Requires Shipping, установленным в Yes: остальные товары не добавляют вес и не входят в сумму заказа. Расширение проверяет, что адрес доставки находится в Испании, вес корзины и минимальную сумму заказа, находит строку цен для Испании (или строку *) и размер посылки и возвращает цену. Если применяется бесплатная доставка, цена равна 0. Цена рассчитывается в валюте магазина по умолчанию, округляется до её знаков после запятой и показывается покупателю в его валюте с налогом выбранного Tax class. Для расчёта цены запрос в Correos не отправляется.

Блок CityPaq locker появляется под способом CityPaq на шаге способа доставки. Выбор сохраняется, как только покупатель его сделал. Недопустимый постамат отклоняется с сообщением, а предыдущий выбор остаётся. При списке Correos код постамата принимается, только если Correos предложил его для введённого почтового индекса; название и адрес берутся из Correos. Покупатель может искать до 30 разных почтовых индексов за одну сессию оформления. После этого он видит сообщение Too many searches. Please enter the CityPaq locker you found on the Correos map.

Кнопка Continue на шаге способа доставки не переходит к CityPaq без действительного постамата. Это проверяется на сервере. Покупатель видит, например, сообщение Please choose the CityPaq locker where you want to collect your parcel. При оформлении заказа постамат сохраняется в заказе.

В OpenCart 4 покупатель нажимает Choose в блоке способа доставки на странице оформления заказа и выбирает CityPaq в окне Shipping method options. Блок CityPaq locker появляется в этом окне под вариантом CityPaq и работает так, как описано выше. Кнопка Continue окна не переходит к CityPaq без действительного постамата. OpenCart 4 хранит один заказ для оформления и обновляет его каждый раз, когда покупатель подтверждает выбор снова, и постамат заказа обновляется вместе с ним.

Список Correos запрашивается только тогда, когда выбран способ CityPaq, а не при отрисовке шага. Список кэшируется на 12 часов для каждого почтового индекса. Неудачный запрос кэшируется на 10 минут, чтобы оформление заказа не ждало Correos при каждом обновлении. Покупатель никогда не видит техническую ошибку, только сообщение The Correos CityPaq list cannot be loaded right now. и ручное поле.

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

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

Выбранный постамат добавляется к способу доставки заказа, например Correos CityPaq - CityPaq locker: .... Поэтому покупатель видит его в истории заказов своего аккаунта и в письмах о заказе, а также он печатается в счёте и отображается в Sales > Orders. Страница успешного оформления заказа в OpenCart способ доставки не показывает.

На странице заказа в админ-панели блок CityPaq locker над историей показывает постамат и его Locker code:, если он был выбран из списка. Чтобы изменить его, используйте поле Change CityPaq locker и нажмите Save: при вашем списке выберите другой постамат из выпадающего списка; при списке Correos введите код постамата (он проверяется в Correos) или адрес; в остальных случаях введите новый код или адрес. Оставьте поле пустым или выберите -- Keep the current locker --, чтобы сохранить текущий постамат. Каждое изменение также обновляет текст способа доставки заказа и добавляет запись в историю CityPaq locker changed to: ... без уведомления покупателя. Для изменения постамата нужно право изменения заказов (sale/order). Доступ к настройкам расширения не нужен. Блок показывается для заказов CityPaq и тогда, когда расширение выключено.

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

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Correos CityPaq — первый блок на странице Extensions > Extensions > Shipping > VibeFox Correos CityPaq > Edit, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в маскированном виде, статус (например, дату, до которой лицензия действует, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: opencart-shipping-correos-citypaq и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт vibefox.net. Изменить ключ могут только администраторы с правом Modify для расширения. Тексты блока следуют языку админ-панели (включены английский и русский).

Если ключ не принят, блок сообщит причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on с датой. После смены адреса магазина или после освобождения слота домена в аккаунте vibefox.net нажмите Check now. Если сервер лицензий недоступен, расширение продолжает работать по последнему известному статусу.

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

Без действующего ключа способ доставки Correos CityPaq не показывается покупателям при оформлении заказа, и стоимость не рассчитывается. Администратор, вошедший в админ-панель в том же браузере, всё равно видит способ доставки в магазине с пометкой (unlicensed — visible to admins only), поэтому можно настроить и протестировать расширение до покупки ключа. В OpenCart 4 такого предпросмотра нет: магазин не видит вход администратора, поэтому без действующего ключа способ скрыт для всех. После того как вы один раз откроете страницу Edit, на странице Dashboard админ-панели появится напоминание. Закройте его кнопкой ×, чтобы скрыть на 7 дней. Существующие заказы не затрагиваются.

Когда срок лицензии истекает, расширение продолжает работать, но обновления и поддержка требуют продления. Статус проверяется автоматически при открытии Dashboard админ-панели или страницы Edit: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Cron-задача не нужна. Удаление расширения всегда удаляет лицензионный ключ и статус лицензии.

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

Correos CityPaq не появляется при оформлении заказа: проверьте, что лицензия активна, включена опция Enable/Disable и адрес доставки находится в Испании. Проверьте Geo zone (или включите Ignore geo zone). Проверьте, что в таблице цен есть строка для Испании или строка *, что корзина в пределах ограничений по весу и Minimum order amount, и что у товаров установлено Requires Shipping в Yes.

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

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

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

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

Страница пишет «Warning: You do not have permission to modify VibeFox Correos CityPaq!»: возможно, ваша группа администраторов может только просматривать настройки. Дайте группе право изменения для extension/shipping/vfd_correos_citypaq (OpenCart 3) или extension/vfd_correos_citypaq/shipping/vfd_correos_citypaq (OpenCart 4) в System > Users > User Groups.

Для разработчиков: постамат сессии оформления и постамат заказа хранятся в таблице vfd_cpq_locker (с префиксом вашей базы данных). Адрес API Correos можно заменить настройкой vfd_cpq_api_url (для тестов); на странице настроек для неё нет поля.

Удаление

Перейдите в Extensions > Extensions, выберите тип Shipping и нажмите Uninstall (красная кнопка −) рядом с VibeFox Correos CityPaq. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда сбрасывает Enable/Disable, Sort order, Tax class и Geo zone. Кэшированные списки постаматов Correos и последняя ошибка API всегда удаляются. Если Remove data on uninstall включено, также удаляются настройки, журнал и постаматы сессий оформления без заказа. Если выключено, остальные настройки сохраняются и снова используются при повторной установке расширения. Постаматы, сохранённые в заказах, никогда не удаляются, а существующие заказы сохраняют свой способ доставки и стоимость.

В OpenCart 4, чтобы удалить также файлы расширения, после удаления перейдите в Extensions > Installer и нажмите Uninstall (оранжевая кнопка −) рядом с VibeFox Correos CityPaq в списке установленных расширений, затем Delete (красная кнопка с корзиной), чтобы удалить загруженный пакет.

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