VibeFox Correios for OpenCart — Помощь

Требования

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

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

Договор с Correios (только для тарифов в реальном времени): тарифы в реальном времени используют API тарифов Correios Web Services (CWS) и требуют учётных данных договора с Correios, в котором есть карточка отправки. Нужны три значения: ваш пользователь Meu Correios (обычно CNPJ или CPF по договору), код доступа к API и номер карточки отправки. Код доступа создаётся в портале Correios Web Services (cws.correios.com.br; для тестовой среды — cwshom.correios.com.br). Также нужен CEP, с которого вы отправляете. Без учётных данных расширение работает только с фиксированными тарифами.

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

Установка

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

OpenCart 3

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

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

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

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

5. Введите пользователя API Correios, код доступа, номер карточки отправки, CEP отправления и услугу. Если валюта по умолчанию вашего магазина не BRL, введите курс к BRL. Заполните фиксированные тарифы для других стран и запасного варианта (см. Конфигурация), включите Enable Correios и нажмите Save.

OpenCart 4

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

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

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

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

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

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

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

Страница показывает предупреждения, если тарифы в реальном времени или способ доставки не могут работать: заполнены не все три учётных данных, не указан CEP отправления, нет курса к BRL для магазина с другой валютой или нет ни учётных данных, ни фиксированных тарифов. Каждое предупреждение сообщает, используются ли пока фиксированные тарифы или способ доставки скрыт. Предупреждение также появляется, если в магазине нет класса веса с единицей kg или класса длины с единицей cm; тогда единицы товаров переводятся по названию единицы их класса (неизвестные единицы считаются kg или cm). Проверьте System > Localisation > Weight Classes и Length Classes.

Сохранение отклоняется с сообщением, если название способа доставки пустое или недопустимое (не более 64 символов, без < > ; = # { }), если числовое поле или тариф в Country prices не является числом 0 или больше, если курс к BRL равен 0, если Min cart weight больше Max cart weight, если CEP отправления содержит не 8 цифр, если код другой услуги содержит больше 5 цифр или если Sort order не является целым числом. Ничего не сохраняется, пока вы не исправите значение.

Общие

Настройки применяются ко всем географическим зонам. Вы можете ограничить способ доставки географической зоной в Conditions или списком стран с помощью Ignore shipping zones.

Enable Correios: показывает или скрывает Correios при оформлении заказа. По умолчанию: выключено.

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

Sort order: место Correios в списке способов доставки при оформлении заказа. Целое число.

API Correios (тарифы в реальном времени в Бразилии)

Для адресов в Бразилии стоимость берётся из API тарифов Correios. Если API не возвращает стоимость (API недоступен, CEP не обслуживается, посылка слишком большая), используется фиксированный тариф из Country prices, а если его нет, способ доставки скрывается. Подробности ошибок попадают в журнал и никогда не показываются покупателю.

API user: ваш логин в портале Meu Correios, обычно CNPJ или CPF по договору. Очистка поля также удаляет сохранённый код доступа.

Access code: код доступа к API (código de acesso), созданный в портале Correios Web Services. Это не пароль от портала. После сохранения поле остаётся пустым и показывает Saved — leave empty to keep it (empty the API user as well to remove it). Вводите новое значение, только если хотите его изменить. Чтобы удалить сохранённый код, очистите API user и сохраните настройки.

Posting card: номер карточки отправки (cartão de postagem) вашего договора: 10 цифр, обычно начинается с двух нулей, например 0012345678. Более короткие номера дополняются нулями слева. Номер можно проверить на странице Correios Fácil на сайте Correios.

Homologation: использует тестовую среду Correios (homologation): запросы отправляются на apihom.correios.com.br с кодом доступа для тестовой среды. На рабочем магазине выключите эту опцию.

Origin CEP: CEP (8 цифр), с которого отправляются посылки, например 01001-000.

Service: услуга Correios, по которой рассчитывается стоимость при оформлении заказа. Розничные коды: PAC (04510, по умолчанию), SEDEX (04014), SEDEX 12 (04782), SEDEX 10 (04790), SEDEX Hoje (04804). Договорные коды: PAC (03298), SEDEX (03220), SEDEX 12 (03140), SEDEX 10 (03158), SEDEX Hoje (03204), Correios Mini Envios (04227). Договорным кодам нужна карточка отправки договора, в котором есть эта услуга.

Other service code: необязательно, 5-значный код услуги вашего договора, которого нет в списке, например 03085. Более короткий код дополняется нулями слева. Если он заполнен, используется вместо Service.

Package format: тип отправления, который передаётся в Correios.

Default product weight (kg): передаётся в Correios для каждого товара без веса. По умолчанию: 0.3. Веса и размеры товаров пересчитываются из их классов веса и длины, а корзина рассчитывается как одна посылка.

BRL → store currency rate: в названии поля показана валюта магазина по умолчанию, например BRL → EUR rate. Тарифы Correios указаны в BRL. Если валюта по умолчанию не BRL, введите, сколько единиц вашей валюты стоит один BRL, например 0.17. Без этого значения тарифы в реальном времени не используются. Курс должен быть больше 0. Если валюта по умолчанию — BRL, оставьте поле пустым.

Фиксированные тарифы (используются для стран вне Бразилии, без учётных данных API и как запасной вариант, если API не возвращает стоимость)

Country prices: таблица стран с базовым тарифом Base и тарифами в зависимости от веса корзины в валюте магазина по умолчанию, без налога: XS до 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL более 5 kg. Пустой или нулевой тариф размера использует базовый тариф Base. Нажмите Add country, чтобы добавить строку, и кнопку ×, чтобы удалить её. Строка * All other countries задаёт тарифы для всех стран, у которых нет собственной строки. Страна без строки (и без *) не получает фиксированного тарифа. В строке должен быть хотя бы один тариф. Базовый тариф 0 означает бесплатную доставку для этой страны.

Fixed price per: Order (по умолчанию) берёт тариф один раз. Item (price × quantity) умножает его на количество товаров в корзине. Это относится только к фиксированным тарифам. Тарифы в реальном времени всегда рассчитываются для всей посылки.

Условия

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

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

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

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

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

Tax class: класс налога, который добавляется к стоимости доставки, или No tax (по умолчанию).

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

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

Обычно способ доставки предлагается в географической зоне, выбранной в Conditions (во всех зонах, если ни одна не выбрана).

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

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

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

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

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

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

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

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

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

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

Когда OpenCart показывает способы доставки, он запрашивает у расширения стоимость Correios. Если задана Geo zone (и Ignore shipping zones выключено) и адрес находится вне неё, Correios не предлагается. Учитываются только товары с Requires Shipping, установленным в Yes: остальные товары не добавляют вес и не входят в сумму заказа. Затем расширение проверяет условия: разрешённые страны (с Ignore shipping zones), вес корзины и минимальную сумму заказа. Сумма заказа — это стоимость товаров, требующих доставки, после скидки по купону и до налога. Если применяется бесплатная доставка, стоимость равна 0 и запрос к Correios не отправляется.

Для адреса в Бразилии с заданными учётными данными расширение сначала получает токен API для вашей карточки отправки. Токен также содержит номера договора и регионального отделения, поэтому стоимость — это стоимость вашего договора. Затем запрашивается стоимость выбранной услуги по CEP отправления и назначения, весу посылки в граммах и размеру посылки в см. Стоимость запрашивается, только если CEP назначения содержит 8 цифр. Если у всех товаров есть размеры, размер посылки оценивается по ним; иначе передаётся минимальный размер Correios. Посылки весом более 30 kg в API не отправляются. Стоимость в BRL пересчитывается по вашему курсу. Стоимость рассчитывается в валюте магазина по умолчанию, округляется до её знаков после запятой и показывается покупателю в его валюте с налогом выбранного Tax class.

Каждая стоимость кэшируется на 1 час. Неудачный запрос кэшируется на 10 минут, чтобы сбой API не замедлял каждое обновление оформления заказа. Токен кэшируется до незадолго до истечения срока (не дольше времени жизни кэша OpenCart, по умолчанию 1 час) и обновляется автоматически; если Correios его отклоняет, запрашивается новый токен и запрос стоимости повторяется один раз. Таймаут API — 12 секунд.

Если API не возвращает стоимость, используется фиксированный тариф, а если его нет, способ доставки скрывается. Покупатель никогда не видит подробностей ошибок API; они попадают в журнал отладки.

Расширение только рассчитывает тарифы. Оно не получает международные тарифы Correios (Exporta Fácil, Packet), оценки сроков доставки, этикетки, предварительные отправления, декларации или отслеживание. Покупатели не могут выбрать отделение или постамат Correios. Дополнительные услуги (объявленная ценность, вручение лично, уведомление о вручении) не добавляются. Расширение показывает одну услугу Correios на магазин, а курсы валют автоматически не обновляются.

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

Заказы

Когда заказ оформлен с Correios, расширение сохраняет, как была рассчитана его стоимость доставки. Страница заказа в Sales > Orders тогда показывает блок Correios с Correios service (например PAC — contract (03298)) и Price: Live price (Correios API), Fixed price или Free shipping. Блок показывается только в админ-панели, не в письмах покупателям, и остаётся видимым, когда расширение выключено.

В OpenCart 4 оформление заказа создаёт один заказ и обновляет его, когда покупатель подтверждает заказ повторно. Данные Correios заказа обновляются вместе с ним, а если покупатель выбирает другой способ доставки, блок Correios для этого заказа больше не показывается.

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

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Correios — первый блок на странице Extensions > Extensions > Shipping > VibeFox Correios > Edit, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой лицензия действительна, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: opencart-shipping-correios и ссылка 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 с датой. После смены адреса магазина или после освобождения слота домена в аккаунте нажмите Check now. Если сервер лицензий недоступен, расширение продолжает работать по последнему известному статусу.

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

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

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

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

Correios не появляется при оформлении заказа: проверьте, что лицензия активна и включена опция Enable Correios. Проверьте Geo zone (или Ignore shipping zones и Countries), ограничения веса и Minimum order amount. Без тарифа в реальном времени должен быть фиксированный тариф для страны или для *. Проверьте, что у товаров установлено Requires Shipping в Yes.

Способ доставки показывает фиксированный тариф вместо тарифа Correios: посмотрите поле Log на странице расширения. Там записываются ошибки Correios: неверный код доступа, услуга не входит в ваш договор, CEP не обслуживается, посылка больше 30 kg или превышает ограничения по размеру. Также проверьте, задан ли CEP отправления, содержит ли CEP покупателя 8 цифр и, если валюта по умолчанию не BRL, указан ли курс к BRL. Включите Debug log, чтобы видеть каждый расчёт.

Запрос токена не проходит: проверьте пользователя API, код доступа, карточку отправки и среду. Код доступа для тестовой среды работает только при включённой опции Homologation, а рабочий код — только при выключенной.

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

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

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

Удаление

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

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

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