VibeFox Correios for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более старых версиях PHP.

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

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

Установка

1. В back office откройте Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. После окончания загрузки нажмите Configure или позже найдите VibeFox Correios в списке модулей и нажмите Configure.

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

4. Введите пользователя API Correios, код доступа, номер posting card, CEP отправления и услугу. Если валюта по умолчанию вашего магазина не BRL, введите курс BRL. Заполните фиксированные тарифы для других стран и как запасной вариант (см. раздел «Настройки») и нажмите Save.

При установке модуль создаёт перевозчика Correios с текстом срока доставки Correios (Brazilian Post). Перевозчик назначается всем зонам и всем группам клиентов. Зоны, группы клиентов, срок доставки, логотип и ограничения по размеру можно изменить в Shipping > Carriers. Цены там не задавайте: цена всегда берётся из модуля.

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Correios > Configure. У каждого раздела есть собственная кнопка Save, которая сохраняет всю страницу. Каждое сохранение также очищает кеш тарифов Correios и токенов API. Числа можно вводить с точкой или с запятой.

Страница показывает предупреждения, когда актуальные тарифы или перевозчик не могут работать: заполнены только некоторые из трёх учётных данных, не указан CEP отправления, не задан курс BRL для магазина в другой валюте или нет ни учётных данных, ни фиксированных тарифов. Каждое предупреждение сообщает, используются ли пока фиксированные тарифы или перевозчик скрыт. Предупреждение также появляется, если модуль не знает единицу веса или размера магазина (тогда она читается как кг или см); задайте кг, г, фунт или унцию и см, мм, м или дюйм в International > Localization (Local units).

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

Общие

Enable Correios: включает или выключает перевозчика во всех зонах сразу. Это тот же переключатель, что и статус перевозчика в Shipping > Carriers.

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

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

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 и Access code и сохраните.

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

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

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). Договорным кодам нужна posting card договора, в который входит эта услуга.

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

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

Default product weight: в кг, отправляется в 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 кг, S 1–2 кг, M 2–3 кг, L 3–5 кг, XL свыше 5 кг. Пустая или нулевая цена для размера использует базовую цену Base. Нажмите Add country, чтобы добавить строку, и крестик, чтобы удалить строку. Строка * Default (all other countries) задаёт цены для всех стран без собственной строки. Страна без строки (и без *) не получает фиксированной цены. Строка без единой цены не сохраняется. Цена, которая не является числом или отрицательна, останавливает сохранение с ошибкой. Базовая цена 0 означает бесплатную доставку для этой страны.

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

Условия

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

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

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

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

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

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

Обычно перевозчик показывается в тех зонах, которые назначены ему в Shipping > Carriers.

Ignore shipping zones: предлагает перевозчика для указанных ниже стран независимо от того, какая зона подходит. При сохранении перевозчик добавляется во все зоны. Выключение опции удаляет добавленные ею зоны. Зона, созданная позже при включённой опции, добавляется автоматически.

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

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

Debug log: записывает расчёты цен в logs/vfd_crr_debug.log.php в папке модуля. Файл нельзя открыть через веб. Ошибки API всегда записываются в журнал, даже когда эта опция выключена. Пользователь API, код доступа, posting card, токен и CEP покупателей в журнал не попадают.

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

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

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

На этапе доставки PrestaShop запрашивает у модуля цену Correios. Учитываются только физические товары: виртуальные товары не добавляют вес и не входят в сумму заказа. Модуль сначала проверяет условия: разрешённые страны (с Ignore shipping zones), вес корзины и минимальную сумму заказа. Если применяется бесплатная доставка, цена равна 0 и запрос в Correios не отправляется.

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

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

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

Если вы редактируете перевозчика в Shipping > Carriers после того, как у него появились заказы, PrestaShop сохраняет его как новую версию перевозчика. Модуль автоматически переходит на новую версию.

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

Заказы

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

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Correios — это первый блок на странице Modules > Module Manager > VibeFox Correios > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-shipping-correios и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт на vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока следуют языку back office (включены английский и русский).

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

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

Без активного ключа перевозчик Correios не показывается покупателям при оформлении заказа, и тариф не рассчитывается. Витрина PrestaShop не знает, что вы вошли в back office, поэтому перевозчик скрыт и для вас: модуль можно настроить до покупки ключа, но нельзя проверить при оформлении заказа. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются.

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

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

Correios не появляется при оформлении заказа: проверьте, что лицензия активна и включена опция Enable Correios. В Shipping > Carriers проверьте, что перевозчик охватывает зону страны покупателя и группу покупателя (или что включена опция Ignore shipping zones и страна разрешена). Проверьте ограничения по весу и Minimum order amount. Без актуального тарифа для страны или для * должен существовать фиксированный тариф. Кроме того, товары могут быть ограничены определёнными перевозчиками на странице товара.

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

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

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

Страница сообщает, что перевозчик Correios не найден: перевозчик был удалён в Shipping > Carriers. Сбросьте модуль в Modules > Module Manager, чтобы создать его снова.

При сохранении пишет, что у вас нет прав: ваш профиль сотрудника может просматривать модуль, но не настраивать его. Сохранение настроек и очистка журнала требуют права на настройку модуля.

Удаление

Откройте Modules > Module Manager, откройте меню рядом с VibeFox Correios и выберите Uninstall. Лицензионный ключ, статус лицензии, кешированные цены и токены всегда удаляются. Если Remove data on uninstall включено, перевозчик удаляется (заказы сохраняют свою историю), а настройки, сохранённые услуги заказов и журнал удаляются. Если выключено, перевозчик только отключается и все настройки сохраняются. При повторной установке модуля перевозчик восстанавливается в том статусе, который у него был раньше.

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