VibeFox CTT for OpenCart — Помощь

Требования

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

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

Аккаунт электронной коммерции CTT (только для актуальных тарифов и пунктов CTT): актуальные тарифы и доставка в пункт CTT используют API электронной коммерции CTT. Вам нужен аккаунт электронной коммерции CTT на enviosecommerce.ctt.pt (для клиентов с договором CTT Expresso или запросите предложение у CTT). На странице управления ключами этого аккаунта создайте пару ключей: открытый и закрытый. App ID (X-APPID) выдаёт CTT для вашей интеграции: уточните его у своего контакта CTT по электронной коммерции. CTT также определяет, какие функции API (оценка стоимости, пункты CTT) может использовать ваш App ID. Наконец, вам нужен Carrier ID CTT в вашем аккаунте. Страница настроек показывает перевозчиков вашего аккаунта после сохранения ключей. Если вы используете только таблицу тарифов и доставку по адресу, API-ключи не нужны.

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

Установка

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

OpenCart 3

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

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

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

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

5. Заполните таблицу тарифов (как минимум строку Portugal или * Default), включите Enable/Disable и/или Enable CTT point option и нажмите Save. При желании укажите API-ключи CTT, App ID и Carrier ID и включите Live rates (см. раздел Настройка).

OpenCart 4

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

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

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

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

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Shipping > VibeFox CTT > Edit. Разделы перечислены слева. Одна кнопка Save внизу сохраняет всю страницу без перезагрузки. Тарифы и условия применяются к обоим вариантам CTT. Каждое сохранение очищает кэшированные ответы CTT: API-токен, перевозчиков, тарифы и списки пунктов CTT. Сохранять настройки могут только администраторы с правом изменения для этого расширения.

Предупреждения вверху страницы сообщают о пустой таблице тарифов, отсутствующем тарифе для Португалии, неполных API-ключах при включённых актуальных тарифах или опции пункта CTT, отсутствующем Carrier ID, валюте магазина, отличной от EUR, без курса обмена, неудачном подключении к API CTT, а также о магазине без класса веса в кг или класса длины в см (тогда единицы товаров преобразуются по их названию единицы; проверьте System > Localisation > Weight Classes и Length Classes). Если название пустое, некорректное или длиннее 64 символов, если Min weight (kg) больше Max weight (kg), или если Sort Order, налоговый класс или географическая зона некорректны, страница показывает ошибку и ничего не сохраняется. Другие некорректные значения выводятся как предупреждения, а остальное сохраняется: некорректное число не сохраняется, курс обмена 0 или меньше очищается, некорректный размер товара сбрасывается к значению по умолчанию, неизвестное направление или повторяющаяся строка в таблице тарифов удаляется, некорректный тариф в таблице остаётся пустым.

Общие

Расширение предлагает при оформлении заказа до двух вариантов: доставка CTT по адресу покупателя и доставка в пункт CTT или постамат. Тарифы и условия применяются к обоим.

Enable/Disable: включает или отключает доставку CTT по адресу покупателя.

Name: название способа доставки, которое видит покупатель при оформлении заказа, например «CTT Expresso». По умолчанию: CTT. До 64 символов.

Tax class: налоговый класс стоимости доставки. OpenCart добавляет этот налог (например, IVA) к тарифам. --- None --- означает, что тарифы окончательные. Используется обоими вариантами.

Sort Order: позиция CTT среди способов доставки при оформлении заказа. Целое число.

Доставка в пункт CTT или постамат

Второй вариант CTT. Покупатель ищет пункты CTT по почтовому индексу или городу (адрес доставки ищется автоматически) и должен выбрать пункт, прежде чем продолжить. Для него нужны API-ключи CTT и Carrier ID. Без них это вариант без выбора пункта.

Enable CTT point option: предлагает доставку в пункт CTT или постамат. По умолчанию: выключено.

CTT point option name: название этого варианта при оформлении заказа. По умолчанию: CTT point / parcel locker. До 64 символов.

API электронной коммерции CTT (актуальные тарифы, пункты CTT) (необязательно; без ключей используется таблица тарифов)

Public key: открытый ключ со страницы управления ключами вашего аккаунта электронной коммерции CTT.

Private key: секретный ключ, которым подписывается каждый запрос (HMAC-SHA256). Он никогда не отправляется в CTT и не записывается в журнал.

Оба ключа после сохранения больше не отображаются. Тогда описание поля гласит Saved - leave empty to keep it. Вводите новое значение, только если хотите его изменить. Отметьте Remove the saved public and private key и сохраните, чтобы удалить оба ключа. Если ничего не сохранено, раздел показывает No keys saved.

App ID (X-APPID): ключ приложения, выданный CTT, отправляется в заголовке X-APPID.

Carrier ID: ID перевозчика CTT в вашем аккаунте, используется для актуальных тарифов и поиска пунктов CTT. После сохранения ключей и App ID перевозчики вашего аккаунта перечисляются под полем (Carriers of your CTT account:), а те, что поддерживают пункты CTT, отмечены CTT points. Только цифры.

Live rates: запрашивает у CTT стоимость (оценку) после того, как покупатель введёт улицу, почтовый индекс и город. Таблица тарифов используется, пока адрес не заполнен, и всякий раз, когда CTT не возвращает стоимость. CTT называет эту стоимость оценкой. По умолчанию: выключено.

Service ID: необязательно. Если CTT возвращает несколько услуг, используется та, у которой этот ServiceId. Оставьте поле пустым, чтобы использовать самую дешёвую.

Exchange rate: тарифы CTT указаны в евро. Если основная валюта вашего магазина другая, укажите, сколько единиц валюты магазина равны 1 единице валюты CTT. Без этого значения актуальные тарифы в другой валюте не используются, и применяется таблица тарифов.

Default product size (cm): длина x ширина x высота, отправляемые в CTT для товаров без размеров. По умолчанию: 30x20x15. Товары с размерами используют свои. Размеры переводятся в см, а веса в граммы по классам длины и веса товаров.

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

Введите тарифы по вашему договору с CTT или по публичному прайс-листу CTT на ctt.pt, в основной валюте магазина, без налогов. Когда актуальные тарифы выключены, эта таблица задаёт цену. Когда они включены, она служит запасным вариантом.

Price table: одна строка на направление. Выберите страну, Portugal - Azores, Portugal - Madeira или * Default (other destinations). Каждая строка содержит базовую Price и необязательные цены для размеров XS (до 1 кг), S (до 2 кг), M (до 3 кг), L (до 5 кг) и XL (более 5 кг). Пустая (или нулевая) цена размера использует базовую цену. Строка, в которой обе цены пусты, скрывает способ доставки. Строка Azores используется для португальских почтовых индексов 9500-9999, строка Madeira для 9000-9499. Без них применяется строка Portugal. Нажмите Add destination, чтобы добавить строку, и кнопку × — чтобы удалить. Цены принимают точку или запятую как десятичный разделитель. После установки таблица пуста.

Calculation: как определяется цена из таблицы.

Актуальная стоимость CTT всегда относится ко всему отправлению.

Условия

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

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

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

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

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

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

Доступность

Как правило, варианты CTT предлагаются в географической зоне, выбранной ниже. All Zones означает везде. С опцией Ignore shipping zones географическая зона не проверяется, и решают Countries.

Geo Zone: географическая зона адреса доставки. Географические зоны настраиваются в System > Localisation > Geo Zones.

Ignore shipping zones: не проверять географическую зону; предлагать CTT в странах, указанных ниже.

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

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

Debug log: записывает расчёт тарифов и вызовы API CTT в storage/logs/vfd_ctt_debug.log.php (в OpenCart 4 system/storage/logs/vfd_ctt_debug.log.php). Файл нельзя прочитать из интернета. Ошибки API CTT записываются всегда, даже когда эта опция выключена. Ключи, токены и адреса покупателей никогда не записываются в журнал. Когда файл достигает 5 МБ, он переносится в vfd_ctt_debug.old.log.php, и начинается новый журнал.

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

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

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

Export: нажмите Download JSON, чтобы сохранить настройки в файл JSON. Открытый и закрытый ключи не экспортируются.

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

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

Когда OpenCart показывает способы доставки, он запрашивает у расширения стоимость CTT. С опцией Ignore shipping zones CTT предлагается только для страны из Countries (пусто = все страны); в противном случае, если задана Geo Zone, только для адресов внутри неё. Учитываются только товары с Requires Shipping, установленным в Yes: остальные товары не добавляют веса и не входят в сумму заказа. Расширение проверяет вес корзины и минимальную сумму заказа. При включённых Live rates и полном адресе оно отправляет в CTT адрес доставки и для каждой позиции корзины количество, вес в граммах и размеры в см, а затем использует возвращённую стоимость. Иначе, или когда CTT не возвращает стоимость (ошибка API, тайм-аут, нет покрытия, функция не включена для вашего App ID), стоимость берётся из таблицы. Если применяется бесплатная доставка, стоимость равна 0. Оба варианта получают одну и ту же стоимость. Стоимость рассчитывается в основной валюте магазина, округляется до его знаков после запятой и показывается покупателю в его валюте с налогом выбранного Tax class.

Актуальная стоимость CTT кэшируется на 1 час, поэтому та же корзина не вызывает новый запрос. Неудачный запрос запоминается на 5 минут, чтобы оформление заказа не ждало CTT при каждом обновлении. API-токен, список перевозчиков и списки пунктов CTT тоже кэшируются, не дольше срока жизни кэша OpenCart (по умолчанию 1 час). Ошибки API никогда не доходят до покупателя: используется стоимость из таблицы, либо способ доставки скрывается, если для направления нет цены.

Когда API-ключи заполнены, расширение отправляет в CTT адрес доставки, веса и размеры товаров и URL вашего магазина, чтобы получить стоимость или ближайшие пункты CTT.

Расширение не создаёт отправления, не печатает этикетки, не оформляет заявки на забор, не выдаёт трек-номера и не показывает карту пунктов CTT. Для обоих вариантов есть одна таблица тарифов и один набор настроек API.

В OpenCart 4 покупатель нажимает Choose в блоке способа доставки на странице оформления заказа и выбирает вариант CTT в окне Shipping method options. Стоимость такая же, как в OpenCart 3.

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

Когда покупатель выбирает вариант пункта CTT на шаге способа доставки, под ним появляются поле поиска и список. Почтовый индекс адреса доставки заполняется и ищется автоматически. Покупатель может искать другие пункты CTT по почтовому индексу или городу (кнопка Search) и выбрать один из списка. Выбор сохраняется сразу. Принимается только пункт из списка CTT для этого поиска.

Перед тем как продолжить, покупатель должен выбрать пункт. Когда покупатель нажимает Continue, расширение проверяет пункт на сервере. Без пункта покупатель видит Please select a CTT point., а если пункта нет в списке CTT, The selected CTT point is not in the CTT list for this search. Please choose the CTT point again. Если CTT недоступен, покупатель видит CTT points cannot be loaded right now. Please try again in a few minutes or choose another shipping method.

Выбор пункта активен только тогда, когда заполнены открытый ключ, закрытый ключ, App ID и Carrier ID. Он рассчитан на стандартную тему OpenCart и её оформление заказа; другим темам могут понадобиться доработки.

В OpenCart 4 поле поиска и список появляются в окне Shipping method options, под вариантом пункта CTT. Кнопка Continue в окне не пропускает дальше без действующего пункта, с теми же сообщениями. OpenCart 4 использует один заказ на время оформления и обновляет его каждый раз, когда покупатель подтверждает выбор снова; пункт CTT в заказе обновляется вместе с ним.

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

На странице заказа в административной части панель CTT point над историей показывает название и ID пункта. Чтобы его изменить, введите почтовый индекс или город в поле Change CTT point, нажмите Search, выберите пункт и нажмите Save. Страница покажет CTT point updated., текст способа доставки заказа обновится, и в историю заказа будет добавлена запись CTT point changed to: ... без уведомления покупателя. Для изменения пункта нужны право изменения заказов (sale/order) и настройки API. Панель показывается и для заказов CTT, пока расширение выключено.

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

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

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

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

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

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

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

CTT не появляется при оформлении заказа: проверьте, что лицензия активна и включена опция Enable/Disable (или Enable CTT point option). Проверьте Geo Zone или Ignore shipping zones и Countries. Убедитесь, что для направления есть строка в таблице тарифов (или строка * Default), вес корзины находится в пределах Min weight и Max weight, достигнута Minimum order amount и у товаров Requires Shipping установлено Yes.

Покупатель не может выбрать пункт CTT: выбор появляется только под вариантом пункта CTT и только когда заполнены открытый ключ, закрытый ключ, App ID и Carrier ID. Проверьте предупреждения вверху страницы настроек, включите Debug log и посмотрите поле Log на странице расширения.

Актуальные тарифы не появляются: до тех пор, пока покупатель не введёт улицу, почтовый индекс и город, используется таблица тарифов. Проверьте предупреждения и журнал. Ответ «405» означает, что функция не включена для вашего App ID: обратитесь в CTT. В магазине, работающем не в евро, заполните Exchange rate.

Не удалось подключиться к API CTT: предупреждение вверху страницы настроек показывает ошибку. Проверьте ключи и App ID. Расширение автоматически повторит попытку через несколько минут.

Цены с НДС или без НДС: если выбран Tax class, OpenCart добавляет этот налог к цене. С --- None --- цена окончательная.

Цены выглядят устаревшими после изменения: нажмите Save на странице расширения. Это очистит кэшированные ответы CTT.

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

Для разработчиков: адрес API CTT можно заменить настройкой vfd_ctt_api_url (для тестов); на странице настроек для неё нет поля.

Удаление

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

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

CTT — торговая марка её владельца. Это расширение не связано с CTT и не одобрено CTT.